Appearance

토스앱 ​

샌드박스 앱에서 테스트를 마쳤다면, 콘솔에 앱 번들(.ait) 을 업로드하고 QR코드로 토스앱에서 최종 테스트한 뒤 출시할 수 있어요.

이미지

1. 앱 번들 업로드 ​

먼저 앱 번들(.ait) 을 업로드하세요.
업로드가 완료되면 워크스페이스 멤버만 접근 가능한 테스트 스킴/QR을 생성할 수 있어요.

  • 접속 방법: 워크스페이스 선택 → 앱 선택 → 좌측 메뉴에서 ‘앱 출시’ 선택

이미지

이미지

💡 앱 번들 정책

앱 번들은 압축 해제 기준 100MB 이하만 허용돼요.
빌드 파일에 모든 리소스(이미지, 사운드, 영상 등)을 포함하면 용량을 초과할 수 있어요.
리소스 다운로드를 빌드 파일과 반드시 분리해야 해요.

  • 앱 실행에 꼭 필요한 최소 리소스만 빌드 파일에 포함하세요.
  • 대용량 리소스는 외부 스토리지/CDN을 통해 다운로드하도록 구성해 주세요.
  • 추가 리소스는 단계적 다운로드(Lazy Loading)을 적용하면 사용자 경험이 향상돼요.

2. 테스트 진행하기 ​

앱 번들을 올린 후 '테스트하기' 버튼을 눌러 테스트를 진행해 주세요.

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

샌드박스 환경에서는 정상적으로 동작하더라도, 토스앱 내에서 실행 시 메모리 또는 리소스 부족으로 인해 흰 화면이 노출될 수 있어요.
메모리 사용량을 점검하고, 미니앱의 리소스를 최적화해 주세요.

토스앱에서 통신이 되지 않나요?

  1. CORS 설정을 확인해 주세요.
    다음 도메인을 Origin 허용 목록에 등록해 주세요
  • https://<appName>.apps.tossmini.com : 실제 서비스 환경
  • https://<appName>.private-apps.tossmini.com : 콘솔 QR 테스트 환경
  1. App Transport Security (ATS)를 확인해주세요.
    샌드박스 환경에서는 HTTP 통신이 가능하지만, 서비스 환경에서는 HTTPS만 허용돼요.
    HTTP 요청은 샌드박스 앱에서만 정상적으로 동작한다는 점을 유의하세요.
  2. iOS의 서드파티 쿠키 차단 정책을 확인하세요.
    iOS/iPadOS 13.4 이상에서는 서드파티 쿠키가 완전히 차단돼요.
    앱인토스 도메인이 아닌 파트너사 도메인에서 쿠키 기반 로그인을 구현하면 정상 동작하지 않아요.
    토큰 기반 등 대체 인증 방식을 적용해주세요.

이미지

이미지

QR 코드를 카메라로 스캔하면 테스트 토스앱이 실행돼요.
워크스페이스 멤버 전체에게 푸시 메시지를 보내 테스트를 유도할 수도 있어요.
단, 토스앱에 로그인된 만 19세 이상만 테스트할 수 있어요.

앱 출시 전 테스트 방법 ​

intoss:// 스킴은 앱이 출시된 이후에만 접근할 수 있어요.
앱 출시 전에 테스트를 하려면, 아래 방법으로 진행하세요.

  1. 업로드 후 생성된 QR 코드(앱 스킴) 를 통해 deploymentId를 확인해요.

deploymentId는 앱 번들을 업로드할 때마다 새로 발급돼요.

예시 :

intoss-private://intossbench?_deploymentId=0198c10b-68c3-7d2b-a0ab-2c9626b475ec
  1. 아래 예시를 참고해 테스트를 진행해요.
  • 하위 path를 적용한 경우 :
intoss-private://intossbench/path/pathpath?_deploymentId=0198c10b-68c3-7d2b-a0ab-2c9626b475ec
  • 쿼리 파라미터를 적용한 경우 :
intoss-private://intossbench?_deploymentId=0198c10b-68c3-7d2b-a0ab-2c9626b475ec&queryParams=%7B%22categoryKey%22%3A%22

3. 검토 요청하기 ​

테스트를 진행했다면 ‘검토 요청하기’ 버튼을 눌러 주세요.
검토는 영업일 3일 소요돼요.

참고하세요

테스트를 1회 이상 완료해야 검토 요청하기 버튼이 활성화돼요.

검토가 반려된 경우 ​

'반려사유 보기' 버튼을 눌러 사유를 확인한 뒤, 번들을 새로 등록해 다시 검토를 요청해 주세요.

이미지

4. 출시하기 ​

번들이 승인되면 '출시하기' 버튼을 눌러 앱을 유저에게 공개해 보세요.

이미지

자주 묻는 질문 ​

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

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


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