앱인토스 미니앱은 출시 전에 두 곳에서 확인합니다. 개발하는 동안에는 샌드박스 앱이나 devtools로 기능을 맞추고, 번들을 올린 뒤에는 실제 토스 앱에서 테스트 스킴으로 엽니다. 두 단계는 보는 것이 달라서 한쪽이 다른 쪽을 대신하지 못합니다.
개발 중 확인: 샌드박스 앱과 devtools
앱인토스는 개발용 토스 앱을 따로 주지 않습니다. SDK 2.x에서는 개발·QA용 샌드박스 앱을 설치하고, 콘솔에서 쓰는 토스 비즈니스 개인 계정으로 로그인합니다. 테스트할 앱을 고른 뒤 intoss://{appName} 스킴을 입력하면 로컬 개발 서버의 미니앱이 열립니다. 샌드박스 앱은 Android 7, iOS 16 이상에서 동작하고 수시로 업데이트되니, 오류가 나면 최신 버전인지부터 봅니다.
WebView SDK 3.x에는 샌드박스 앱이 없습니다. 함께 설치되는 devtools로 npm run dev가 띄운 localhost 주소를 로컬 브라우저에서 열어 확인합니다. 새로 만든 프로젝트나 CLI 3.0.2 이상으로 옮긴 프로젝트는 자동으로 설정되고, 더 낮은 CLI로 옮겼다면 @apps-in-toss/devtools를 직접 붙입니다.
React Native는 현재 SDK 2.x만 지원하므로 샌드박스 앱 테스트가 필수입니다. 아직 SDK 2.x를 쓰는 WebView 프로젝트도 같습니다.
샌드박스 앱에서 확인할 수 없는 기능도 있습니다. 분석, 공유 리워드, 인앱 광고, 가로 버전 게임, 내비게이션 바 공유하기가 그렇고, 사용자 식별키는 mock 데이터로 내려옵니다. 이런 기능은 다음 단계의 QR 코드로 토스 앱에서 봅니다.
번들 업로드와 테스트 스킴
npm run build를 실행하면 프로젝트 루트에 <서비스명>.ait 번들이 생깁니다. 번들은 압축을 푼 크기 기준 100MB 이하만 올릴 수 있고, 콘솔이나 CLI로 올립니다.
CLI 업로드에는 SDK v1.4.0 이상과 API 키가 필요합니다. API 키는 콘솔에서 워크스페이스를 고른 뒤 왼쪽 메뉴의 '키'에서 발급하고, 전체 앱이나 특정 앱 단위로 권한을 줄 수 있습니다. 토큰을 한 번 등록해 두면 매번 키를 넣지 않아도 됩니다.
bash
업로드가 끝나면 테스트 스킴이 나옵니다. 업로드마다 새 deploymentId가 발급되고, 테스트 스킴에는 _deploymentId가 반드시 들어갑니다. 하위 경로나 쿼리를 붙이면 특정 화면을 바로 열 수 있고, queryParams 값은 URL 인코딩해야 합니다.
콘솔에서는 번들을 올린 뒤 '토스앱 테스트' 버튼으로 QR 코드를 봅니다. QR 코드는 토스 앱에 로그인한 워크스페이스 멤버이면서 만 19세 이상이어야 열립니다. intoss:// 스킴은 정식 출시 뒤에만 열리므로 출시 전에는 테스트 스킴(intoss-private://)이나 QR 코드로만 확인할 수 있습니다.
샌드박스와 라이브가 다른 지점
| 구분 | 샌드박스 앱·devtools | 테스트 스킴·QR 코드 |
|---|---|---|
| 실행 위치 | 샌드박스 앱 또는 로컬 브라우저 | 실제 토스 앱 |
| 여는 대상 | 로컬 개발 서버 | 업로드한 .ait 번들 |
| http 요청 | 허용 | 차단, https만 허용 |
| 분석·인앱 광고 등 | 샌드박스 앱에서는 확인 불가 | 확인 가능 |
가장 흔한 차이는 통신입니다. 샌드박스와 devtools에서 되던 http API는 토스 앱에서 막히니, API는 https로, WebSocket은 wss://로 엽니다.
서버 CORS 허용 Origin에는 미니앱 Origin을 넣어야 합니다. SDK 2.x와 3.1.0 이상 번들은 QR 테스트 환경이 https://<appName>.private-apps.tossmini.com, 실제 서비스가 https://<appName>.apps.tossmini.com입니다. 3.0.x 번들은 도메인이 달랐으니 함께 운영하거나 서로 롤백할 수 있다면 네 도메인을 모두 등록합니다.
iOS·iPadOS 13.4 이상은 서드파티 쿠키를 막습니다. 미니앱과 다른 도메인에서 쿠키로 로그인을 유지하면 동작하지 않으니 토큰 기반 인증을 씁니다.
토스 앱에서만 문제가 보이면 테스트 스킴으로 연 미니앱의 더보기 버튼에서 웹 디버그 툴즈를 엽니다. Log 탭에서 콘솔 로그를, Network 탭에서 API 요청과 응답을 봅니다. 미니앱이 아예 열리지 않으면 토스 앱이 최신 버전인지 확인합니다.
검토 요청 전 확인 순서
- 로컬에서 기능을 맞춥니다. WebView SDK 3.x는 devtools, React Native와 SDK 2.x 프로젝트는 최신 샌드박스 앱을 씁니다.
- API는 https, WebSocket은 wss인지 보고, 서버 CORS에 QR 테스트와 실제 서비스 Origin을 넣습니다.
.ait번들을 만들어 100MB를 넘지 않는지 보고, 콘솔이나npx ait deploy로 올립니다.- 최신 토스 앱에서 QR 코드나 테스트 스킴으로 열어 흰 화면, API 실패, 기기별 화면 차이를 봅니다.
- 샌드박스에서 못 본 기능과 하위 경로·쿼리로 들어오는 화면을 테스트 스킴으로 엽니다.
- 공유 기능이
intoss-private://대신intoss://스킴을 쓰는지 비게임 출시 가이드와 대조합니다.
토스 앱 테스트를 한 번 이상 마쳐야 콘솔에서 검토를 요청할 수 있습니다. 테스트 단계 전체는 앱인토스 미니앱 개발 가이드에서 이어서 볼 수 있습니다.