미니앱 테스트하기
앱 번들(.ait) 파일을 업로드하고 생성된 테스트용 앱스킴으로 토스 앱에서 최종 테스트를 할 수 있어요.
1. 앱 번들 파일 생성하기
앱 번들은 .ait 확장자를 가진 파일로, 빌드된 프로젝트를 패키징한 결과물이에요. 아래 명령어를 실행해 앱 번들을 생성하세요. 빌드가 끝나면 프로젝트 루트 디렉터리에 <서비스명>.ait 파일이 생겨요.
npm run buildpnpm buildyarn build2. 토스 앱 테스트하기
앱 번들을 업로드하고 토스 앱에서 테스트하는 방법은 두 가지예요.
콘솔에서 직접 업로드 후 QR 코드로 테스트
CI/CD 명령어로 자동 업로드
앱 번들은 압축 해제 기준 100MB 이하만 업로드할 수 있어요. 이미지·사운드·영상 같은 리소스를 모두 포함하면 용량을 넘길 수 있으니, 리소스 파일은 빌드와 분리해서 관리하세요.
리소스 관리는 이렇게 하는 걸 권장해요.
앱 실행에 꼭 필요한 최소 리소스만 번들에 포함하세요.
대용량 리소스는 외부 스토리지나 CDN에서 내려받도록 구성해 주세요.
추가 리소스는 단계적으로 내려받는 방식(Lazy Loading)을 적용하면 사용자 경험이 좋아져요.
2-1. 콘솔에서 앱 번들 업로드 후 QR로 테스트하기
먼저 콘솔에 앱 번들(.ait) 파일을 업로드하세요. 테스트를 최소 1번 이상 완료해야 검토를 요청할 수 있어요.
앱 번들 파일이 업로드되지 않나요?
앱이 정상적으로 빌드됐는지 확인해 주세요.
npm run build로 생성한 번들이 아니거나 프로젝트 구조가 올바르지 않으면, 앱 번들 컴파일이 실패해서 업로드되지 않아요.
앱 번들을 업로드한 뒤 '테스트하기' 버튼을 누르면, 콘솔에서 토스 앱 테스트용 QR 코드를 확인할 수 있어요. QR 코드를 스캔하면 토스 앱에서 미니앱이 실행돼요.
QR 코드 테스트는 아래 조건을 모두 충족해야 실행돼요.
토스 앱에 로그인되어 있어야 해요.
워크스페이스 멤버여야 해요.
만 19세 이상 사용자만 테스트할 수 있어요.
2-2. CI/CD 명령어 사용하기
콘솔에 접속하지 않고 CLI로 앱 번들을 업로드할 수 있어요.
CI/CD 명령어로 자동 업로드하려면 SDK v1.4.0 이상이 필요해요. 이전 버전을 쓰고 있다면 먼저 SDK를 업그레이드해 주세요.
먼저 콘솔에서 API 키를 발급해 주세요. 전체 앱 또는 특정 앱 단위로 접근 권한을 설정할 수 있어요.
접속 경로: 워크스페이스 선택 → 왼쪽 메뉴에서 '키'
아래 명령어를 실행해 앱 번들을 업로드하세요. 정상적으로 업로드되면 테스트용 앱스킴을 확인할 수 있어요.
API 키를 등록해 두면 반복해서 입력하지 않아도 돼요.
-m 옵션으로 번들을 업로드할 때 메모를 함께 남길 수 있어요.
필요에 따라 아래 명령어를 사용해 보세요.
npx ait token --help
도움말 보기
npx ait token add [워크스페이스명] [API 키]
토큰 등록하기
npx ait token remove [워크스페이스명]
등록된 토큰 삭제하기
npx ait deploy [워크스페이스명] [API 키]
번들 업로드하기
npx ait deploy [워크스페이스명] [API 키] --timeout [초]
배포 상태 확인 최대 대기 시간 설정하기 (10초 이상 300초 이하)
3. 기능 테스트하기
intoss:// 스킴은 앱이 정식 출시된 뒤에만 접근할 수 있어요. 출시 전 기능 테스트는 업로드할 때 생성된 테스트 스킴(QR 코드)으로 해야 해요.
QR 코드에서 deploymentId 확인하기
앱 번들을 업로드할 때마다 새로운 deploymentId가 발급돼요. 테스트 스킴에서 _deploymentId는 필수 파라미터예요.
스킴에 path·query 적용해 테스트하기
하위 path를 적용한 경우:
쿼리 파라미터를 적용한 경우 (queryParams는 반드시 URL 인코딩해야 해요):