앱인토스 개발자센터 로고

토스앱 ​

샌드박스 앱에서 테스트가 완료되었다면,
앱 번들(.ait) 파일을 업로드하고 생성된 테스트용 앱스킴을 통해 토스앱에서 최종 테스트를 진행할 수 있어요.

1. 앱 번들 파일 생성 ​

앱 번들은 .ait 확장자를 가진 파일로, 빌드된 프로젝트를 패키징한 결과물이에요.
아래 명령어를 실행해 앱 번들을 생성하세요.
빌드가 완료되면 프로젝트 루트 디렉토리에 <서비스명>.ait 파일이 생성돼요.

sh
npm run build
sh
pnpm build
sh
yarn build

2. 앱 번들 업로드 및 토스앱 테스트 ​

앱 번들을 업로드하고 토스앱에서 테스트하는 방법은 두 가지예요.

  1. 콘솔에서 직접 업로드 + QR 코드 테스트
  2. CI/CD 명령어를 통한 자동 업로드

앱 번들 용량 정책

  • 앱 번들은 압축 해제 기준 100MB 이하만 업로드할 수 있어요.
  • 모든 리소스(이미지, 사운드, 영상 등)을 포함하면 용량을 초과할 수 있어요.
  • 리소스 파일은 빌드와 분리하여 관리하세요.

권장 사항

  1. 앱 실행에 필요한 최소 리소스만 번들에 포함하세요.
  2. 대용량 리소스는 외부 스토리지 또는 CDN에서 다운로드하도록 구성해 주세요.
  3. 추가 리소스는 단계적 다운로드(Lazy Loading) 방식을 적용하면 사용자 경험이 향상돼요.

① 콘솔에서 앱 번들 업로드 및 QR 테스트하기 ​

  1. 콘솔에 앱 번들(.ait) 파일을 업로드하세요.
  2. 업로드가 완료되면 테스트용 스킴 및 QR 코드가 자동으로 생성돼요.

접속 경로:
워크스페이스 선택 → 앱 선택 → 좌측 메뉴에서 앱 출시

이미지

앱 번들을 업로드한 후 '테스트하기' 버튼을 클릭하면 콘솔에서 토스앱 테스트용 QR 코드를 확인할 수 있어요.
QR 코드를 스캔하면 토스앱 내에서 미니앱이 실행돼요.

QR 코드 테스트는 아래 조건을 충족해야 실행돼요.

  • 토스앱에 로그인이 되어있어야 해요.
  • 워크스페이스 멤버여야 해요.
  • 만 19세 이상 사용자만 테스트 가능해요.

워크스페이스 멤버 전체에게 푸시 알림을 발송하여 테스트 참여를 유도할 수도 있어요.
테스트 스킴(intoss-private://)을 직접 실행하여 테스트할 수도 있어요.

테스트를 최소 1번 이상 완료해주세요

테스트를 최소 1회 이상 완료해야 검토 요청을 진행할 수 있어요.

이미지

이미지

② CI/CD 명령어 사용하기 ​

콘솔에 접속하지 않고 CLI를 통해 앱 번들을 업로드할 수 있어요.

먼저 콘솔에서 API 키를 발급해주세요.
전체 앱 또는 특정 앱 단위로 접근 권한을 설정할 수 있어요.

접속 경로:
워크스페이스 선택 → 좌측 메뉴에서 키

이미지

이미지

아래 명령어를 실행해 앱 번들을 업로드하세요.
정상적으로 업로드가 되었다면, 테스트용 앱스킴을 확인할 수 있어요.

npx ait deploy --api-key {API 키}

API 키를 등록해두면 반복 입력할 필요가 없어요.

npx ait token add
npx ait deploy

필요에 따라 아래 명령어를 사용해보세요.

명령어용도
npx ait token --help도움말 보기
npx ait token add [워크스페이스명] [API 키]토큰 등록하기
npx ait token remove [워크스페이스명]등록된 토큰 삭제하기
npx ait deploy [워크스페이스명] [API 키]번들 업로드하기

3. 앱 출시 전 피처 테스트 ​

intoss:// 스킴은 앱이 정식 출시된 이후에만 접근 가능해요.
출시 전 기능 테스트를 위해서는 업로드 시 생성된 테스트 스킴(QR 코드) 를 활용해야 해요.

테스트 시 디버깅이 필요하다면?

디버깅하기 문서를 확인하여 보다 빠르게 이슈를 해결하세요.

① QR 코드에서 deploymentId 확인하기 ​

앱 번들을 업로드할 때마다 새로운 deploymentId가 발급돼요.
테스트 스킴에서는 _deploymentId 는 필수 파라미터예요.

예시 :

intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec

② 스킴에 path/query 적용하여 테스트하기 ​

  • 하위 path를 적용한 경우 :
intoss-private://appsintoss/path/pathpath?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec
  • 쿼리 파라미터를 적용한 경우 : queryParams는 반드시 URL-encoding이 필요해요.
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec&queryParams=%7B%22categoryKey%22%3A%22

문제 해결 가이드 ​

iOS에서 흰 화면이 보이나요? ​

샌드박스에서는 정상 동작하지만,
토스앱 내에서는 메모리 또는 리소스 부족으로 흰 화면이 표시될 수 있어요.

  • 이미지·폰트 등 리소스 용량을 줄여 빌드 파일을 최적화하세요.
  • 불필요한 객체, 메모리 누수를 점검해 주세요.

토스앱에서 통신이 되지 않는 경우 ​

1. CORS 설정 확인 ​

Origin 허용 목록에 다음 도메인을 등록하세요.

  • https://<appName>.apps.tossmini.com : 실제 서비스 환경
  • https://<appName>.private-apps.tossmini.com : 콘솔 QR 테스트 환경

2. App Transport Security (ATS) 설정 확인 ​

샌드박스에서는 HTTP 요청이 허용되지만, 라이브 환경에서는 HTTPS만 허용됩니다.
HTTP 기반 API는 토스앱 내에서 차단됩니다.

3. iOS 서드파티 쿠키 차단 정책 확인 ​

iOS/iPadOS 13.4 이상에서는 서드파티 쿠키가 완전히 차단돼요.
쿠키 기반 로그인 대신 토큰 기반 인증 방식을 적용하세요.

자주 묻는 질문 ​

토스앱 하위 버전에서 오류가 발생할 수 있어요 최신 버전의 토스앱에서 테스트를 진행해 주세요.

granite.config.ts 파일에서 icon 값을 채운 상태에서 빌드된 ait 파일인지 확인해주세요. appInToss 플러그인 내의 brand 값이 모두 포함된 상태여야 합니다.


export default defineConfig({
  appsInToss({
    brand: {
      // 👈 brand 값에 빈 값이 없도록
    },
  }),
});