본문 바로가기
스마트폰 (Mobile)

Tuya MiniApp 패널 개발 환경 설정부터 제품 연동 출시까지 가이드

by 날으는물고기 2025. 1. 10.

Tuya MiniApp 패널 개발 환경 설정부터 제품 연동 출시까지 가이드

Tuya MiniApp 패널(Panel MiniApp)을 개발하기 위해 필요한 환경 설정부터, 실제 제품과 연동하여 배포하기까지의 전 과정을 단계별로 정리합니다. Node.js 및 NVM 설치, Yarn 설치, 가상/실물 기기 디버깅, 그리고 최종적으로 Tuya Developer Platform에서 앱을 출시하고 제품에 연결하는 방법까지 폭넓게 다룹니다.

 

또한 각 단계에서 기본적인 보안 관점의 체크포인트를 함께 제시하므로, 내부 사용자나 팀원들에게 가이드를 제공할 때도 참고할 수 있습니다.

1. 환경 설정 (Set up environment)

1.1 사전 준비 (Prerequisites)

  • Node.js 설치
    1. Node.js 공식 웹사이트로 이동합니다.
    2. OS(Windows, macOS 등)에 맞는 설치 파일(.msi, .pkg 등)을 다운로드받아 설치합니다.
    3. 설치 완료 후, 터미널(명령 프롬프트)에서 node -v 명령으로 버전이 정상적으로 출력되는지 확인합니다.
  • 체크포인트
    • Node.js를 다운로드받을 때는 반드시 공식 웹사이트에서 받아 설치해야 합니다.
    • 설치된 Node.js 버전이 취약점이 없는 최신 LTS(Long-Term Support) 버전인지 확인합니다.

1.2 에디터 설치

  • Visual Studio Code(추천)
    • 포맷팅, 탐색, 확장 플러그인 설치 등 커뮤니티 활성도가 높고 편의 기능이 풍부합니다.
  • WebStorm
    • IntelliJ 기반의 고급 IDE로, 프로젝트 구조 파악과 자동 완성 기능이 우수합니다.
  • Sublime Text
    • 가벼우면서도 빠른 에디터로, 단순 작업 시 빠르게 사용할 수 있습니다.
  • Cursor
    • 인공지능(AI)을 활용하여 소프트웨어 개발을 더욱 효율적으로 돕는 현대적인 코드 편집기입니다. AI 기반 기능을 통합하여 코드 작성, 디버깅, 리팩토링, 그리고 문서화 과정을 단순화하고 개발자 생산성을 향상시킵니다.

1.3 앱 설치

  • iOS (App Store)
    • App Store에서 “Smart Life”를 검색 후 다운로드받습니다.
  • Android (Google Play)
    • Google Play 스토어에서 “Smart Life”를 검색 후 다운로드받습니다.
  • 체크포인트
    • 공식 마켓(App Store, Google Play)에서 앱을 다운로드해야 악성 앱 설치를 방지할 수 있습니다.
    • 만약 특정 버전의 Smart Life 앱이 필요하다면, Tuya Developer Platform에 티켓을 생성해 공식 지원을 요청하십시오.

2. Tuya MiniApp IDE 설치

Tuya MiniApp IDE는 미니앱(Panel MiniApp 포함)을 생성, 개발, 디버깅, 업로드하는 통합 개발 환경입니다.

  1. Tuya MiniApp IDE 페이지로 이동하여 최신 버전을 다운로드합니다.
  2. 설치 후, IDE를 실행하고 기본 동작이 잘 되는지 확인합니다.

3. NVM(Node Version Manager) 설치

NVM은 여러 버전의 Node.js를 관리할 수 있게 해줍니다.

  1. 터미널(명령 프롬프트) 열기
  2. 다음 명령으로 NVM 설치 스크립트를 실행 
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.36.0/install.sh | bash
  3. nvm -v 명령어를 통해 NVM이 정상적으로 설치되었는지 확인
    • 버전 번호가 표시되면 정상 설치입니다.
    • 만약 nvm: command not found 오류가 발생하면, 아래 FAQ 섹션의 환경 변수 설정 방법을 확인하십시오.
  4. Node.js v16.0.0 이상을 사용해야 하므로 다음 명령으로 설치합니다. 
    nvm install 16.20.2
  5. 여러 버전이 설치된 경우, 원하는 버전을 아래와 같이 선택할 수 있습니다. 
    nvm use 16.20.2

체크포인트

  • curl -o- ... | bash 방식은 스크립트를 즉시 실행하므로, 반드시 공식 GitHub 페이지 또는 신뢰할 수 있는 출처인지 재확인해야 합니다.
  • 설치가 완료된 후, ~/.bash_profile, ~/.bashrc 등에 설정된 환경 변수를 꼼꼼히 확인하세요(Windows는 ~/.bash_profile 대신 PowerShell 또는 Git Bash 설정 파일 등을 점검).

4. Yarn 설치

Yarn은 Node.js 패키지 매니저 중 하나입니다. 이미 npm, pnpm 등 다른 매니저를 사용 중이라면 이 단계는 생략해도 됩니다.

  1. 터미널 열기
  2. Yarn 설치 
    npm install -g yarn
  3. 설치 확인 
    yarn -v

5. 제품 생성 (Create product)

5.1 개념 이해 (Concepts)

  • 컨트롤 패널(Control Panel)
    • Smart Life 앱에서 동작하는 GUI 애플리케이션으로, 스마트 기기를 제어하고 실시간 상태를 보여줍니다.
  • 제품(Product)
    • 컨트롤 패널과 실제 스마트 기기를 연결해주는 추상화 개념입니다. 기기의 DPs(데이터 포인트)와 기능이 정의됩니다.
  • 스마트 기기(Device)
    • Tuya 모듈이 탑재된 실제 물리 기기이며, QR 코드를 통해 앱에서 스캔 및 등록이 가능합니다.

5.2 제품 생성 (Tuya Developer Platform)

  1. Tuya Developer Platform에 회원가입 및 로그인
  2. 좌측 메뉴에서 Product > Development 진입 후 Create 클릭
  3. 제품 종류 예시: Standard Category > Large Home Appliance > Air Conditioner
  4. 제품 이름을 입력하고 Create
  5. 생성된 제품의 개발 페이지에서 Function Definition 단계로 이동
  6. Standard Functions에서 Select All > OK 클릭해 기본 기능(표준 DPs) 추가

체크포인트

  • 제품 생성 시, 불필요한 DPs를 추가하면 오인 제어나 정보 노출 가능성이 있으므로, 실제 제품에 필요한 DPs만 추가하는 것을 권장합니다.
  • 표준 기능 외에 커스텀 DPs를 사용할 경우, 데이터 암호화나 접근 권한 설정을 고려해 주세요.

6. 프로젝트 초기화 (Initialize project)

6.1 사전 준비사항 (Prerequisites)

  • Tuya Developer Platform 계정이 있어야 하며, 이 계정으로 Tuya MiniApp Developer Platform에 로그인해야 미니앱을 생성할 수 있습니다.

6.2 패널 미니앱 생성

  1. Tuya MiniApp Developer Platform에 로그인
  2. 기존에 생성된 미니앱 목록 페이지에서 Create 클릭
  3. 미니앱 이름, 로고, 타입 등을 설정
    • Miniapp Type을 Panel Miniapp으로 설정
  4. 생성 완료 후, 미니앱 목록에서 해당 미니앱 확인 가능

6.3 프로젝트 초기화 (Tuya MiniApp IDE)

  1. Tuya MiniApp IDE 실행 후, Tuya Developer Platform 계정으로 로그인
  2. Create a new MiniApp Project 혹은 새 프로젝트 생성 버튼 선택
  3. Project Path, Project Name 설정
  4. Link MiniApp: 방금 만든 미니앱 연결
  5. Link Product: 사전에 만든 제품 선택
  6. 템플릿 선택 후 Create
    • 템플릿 종류에 따라 미리 보기 및 GitHub 소스, 가이드 문서(Codelabs) 링크를 제공함
  7. 프로젝트 생성 직후, IDE에서 개발 및 디버깅 화면으로 진입

7. 개발 및 디버깅 (Develop and debug)

7.1 프로젝트 실행 (Start project)

  • 프로젝트 디렉터리로 이동 후, Tuya MiniApp IDE가 자동으로 의존성을 설치하고 앱을 실행
  • 만약 자동 설치가 안 될 경우, project.tuya.json 파일에 "devMode": "ray"가 있는지 확인

7.2 패널 도구(Panel Tools) 활성화

  • 패널 미니앱은 가상의 기기에 종속되므로, UI 레이아웃을 바로 IDE에서 미리보기 하기 어렵습니다.
  • 우측 상단 Account 버튼 > QR 코드 생성
    • 스마트폰의 Smart Life 앱으로 스캔해 계정 권한 부여
  • 상단 Plugins > Panel Tools > 디바이스 목록 확인

7.3 디버깅 모드 종류

  1. 가상 디바이스(Virtual Device) 디버깅
    • “Virtual Device” 섹션에서 원하는 기기를 선택 후 디버깅 가능
    • 가상 디바이스가 없으면, Add virtual devices 클릭
    • 가상의 상태 보고 기능이 있어 빠른 UI 개발이 가능
  2. 실물 디바이스(Real Device) 디버깅
    • 이미 Smart Life 앱에 등록된 기기가 있다면 목록에서 선택
    • Wi-Fi, Zigbee, Mesh, Bluetooth mesh, Beacon, TuyaLink 기기 등을 모두 지원
  3. 디바이스 그룹(Device Group) 디버깅
    • 그룹에 묶인 기기를 한 번에 디버깅 할 수 있음
  4. 체크포인트
    • 실제(Real) 디바이스를 디버깅할 때는 내부망 혹은 안전한 테스트 환경에서 진행하여 외부 공격이나 정보 노출을 최소화하세요.
    • 가상 디바이스와 달리 실물 디바이스는 실제 네트워크 트래픽이 오가므로, 네트워크 스니핑 등의 공격에 대비해야 합니다.

7.4 원격 디버거(Remote Debugger)

  • 앱의 실제 기능(QR 코드 스캔, 전화걸기 등)을 테스트할 때 유용합니다.
  • Tuya MiniApp IDE 내장 플러그인이 v1.4.0 이상이라면, 별도의 파라미터 설정 없이 원격 디버그 화면을 열 수 있습니다.
  • 블루투스 전용 기기는 일부 제한이 있으니 주의하세요.

7.5 디버그/개발 버전 테스트

  • changeDebugMode 호출로 앱 디버그 모드 활성화 가능
  • 배포용 환경에서는 디버그 모드를 해제해야 합니다.

8. 미니앱 테스트 (Test miniapp)

8.1 프로그램 업로드

  1. Tuya MiniApp IDE 우측 상단의 Upload 클릭
  2. 버전 정보, 설명(remarks) 입력 후 업로드

8.2 기본 설정 완료

  1. Tuya MiniApp Developer Platform에서 업로드된 미니앱을 선택
  2. Basic Settings에서 로고, 이름, 미리보기 이미지(중국어, 영어 각각 설정 가능) 설정

8.3 테스트 버전 설정

  1. Versions 탭에서 방금 업로드한 버전 찾아 Set as Trial Version 클릭
  2. 시험 버전용 QR 코드(Trial QR code)를 생성하기 전, Allowlist(화이트리스트) 먼저 설정

8.4 테스트 계정 화이트리스트 추가

  1. Allowlist 탭 진입 후 Add 클릭
  2. 테스트할 앱 계정을 등록

8.5 테스트 기기 등록 및 스캔

  1. Versions > 테스트 버전 > Trial QR code 버튼 클릭
  2. (가상 디바이스 or 실물 디바이스) deviceId를 입력
  3. 화이트리스트에 등록된 계정이 Smart Life 앱으로 QR 코드를 스캔하여 패널 미니앱 실행
  4. 가상 디바이스나 실제 디바이스가 같은 홈(가정)에 있어야 합니다.

9. 제출 및 출시 (Submit for review and release)

9.1 검수(Submit for review)

  1. Tuya MiniApp Developer Platform > Versions
  2. Dev Version 탭에서 대상 버전을 찾아 Submit for Review 클릭

9.2 출시(Release approved version)

  1. 검수가 끝나면 Review Version 탭에서 상태를 확인
  2. 승인된 버전은 Official Version 탭으로 이동
  3. Start Service 버튼으로 사용자에게 공개할 수 있으며, Pause Service로 공개 중단 가능

10. 제품 연결 (Link product)

공개된 패널 미니앱을 기기에 연동하려면, Tuya Developer Platform에서 제품과 패널을 연결해야 합니다.

  1. Tuya Developer Platform > 해당 제품 진입
  2. Device Interaction 단계로 이동 후 Change Panel 클릭
  3. Self-Developed Panel 탭에서 출시된 패널 미니앱 선택
  4. Select로 적용

11. 회귀 테스트 (Perform regression test)

  1. 다시 Tuya Developer Platform의 Device Interaction 단계로 이동
  2. 가상 디바이스 QR 코드를 스캔하여 테스트 (혹은 실제 디바이스 추가)
  3. 이제 테스트 계정이 아니더라도, 제품과 연결된 디바이스를 모든 사용자가 새 패널로 제어 가능

12. FAQs 및 문제 해결

12.1 nvm -v가 안 될 때(nvm: command not found)

  • NVM이 설치된 위치를 환경 변수에 설정해야 합니다.
  • macOS 기준, cd ~ 후 open .bashrc(또는 open .bash_profile) 명령으로 설정 파일을 열어 아래 코드 추가 
    export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
  • source .bashrc 후 다시 nvm -v 확인

12.2 Tuya MiniApp IDE 디버깅 vs 원격 디버거(Remote Debugger)의 차이

  • IDE 디버깅
    • 가상 디바이스 사용
    • 빠른 UI 구현 및 로직 확인 가능
  • 원격 디버거
    • 실제 앱 기능(QR 코드 스캔, 통화 등)과 연동 테스트 가능
    • 후반 기능 완성 단계에서 활용

12.3 앱이 미니앱을 지원하지 않는 경우

  • 베이스 라이브러리나 Kit 패키지 버전이 호환되지 않을 수 있습니다.
  • API Overview에서 의존 버전을 확인 후 업데이트해야 합니다.

이상으로 Tuya MiniApp IDE 환경 설정부터 패널 미니앱을 생성하고, 제품과 연동하여 최종 사용자에게 배포하는 모든 과정을 알아보았습니다.

  • 개발 관점: Node.js, NVM, Yarn 등의 기본 환경 구성과 Tuya MiniApp IDE를 통한 빠른 UI/기능 개발
  • 보안 관점
    • 공식 소스 및 공식 마켓을 통한 설치
    • 환경 변수 보안 설정
    • 실제 디바이스 디버깅 시 내부망에서 테스트
    • 불필요한 DPs 제거를 통한 최소 권한 원칙 적용
  • 출시 관점
    • Tuya Developer Platform의 제품과 패널 연결
    • 미니앱의 버전 관리 및 퍼블릭 배포 과정

 

이 과정을 통해 원하는 스마트 기기의 패널 UI를 자유롭게 구성하고, Tuya 생태계를 활용해 빠르게 서비스를 운영할 수 있습니다. 각각의 단계에서 제시한 체크포인트와 FAQ를 참고하면, 문제를 쉽게 해결할 수 있을 것입니다.

 

모두 안전하고 편리한 Tuya MiniApp 개발 여정이 되길 바랍니다!

728x90
저작자표시 비영리 동일조건

관련글

댓글

티스토리툴바