> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/guide/operation/toss.md).

# 미니앱 테스트하기

앱 번들(.ait) 파일을 업로드하고 생성된 테스트용 앱스킴으로 토스 앱에서 최종 테스트를 할 수 있어요.

### 1. 앱 번들 파일 생성하기

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

{% tabs %}
{% tab title="npm" %}

```sh
npm run build
```

{% endtab %}

{% tab title="pnpm" %}

```sh
pnpm build
```

{% endtab %}

{% tab title="yarn" %}

```sh
yarn build
```

{% endtab %}
{% endtabs %}

***

### 2. 토스 앱 테스트하기

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

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

앱 번들은 압축 해제 기준 100MB 이하만 업로드할 수 있어요. 이미지·사운드·영상 같은 리소스를 모두 포함하면 용량을 넘길 수 있으니, 리소스 파일은 빌드와 분리해서 관리하세요.

리소스 관리는 이렇게 하는 걸 권장해요.

* 앱 실행에 꼭 필요한 최소 리소스만 번들에 포함하세요.
* 대용량 리소스는 외부 스토리지나 CDN에서 내려받도록 구성해 주세요.
* 추가 리소스는 단계적으로 내려받는 방식(Lazy Loading)을 적용하면 사용자 경험이 좋아져요.

{% hint style="info" %}
**앱 번들 용량 정책**

* 앱 번들은 압축 해제 기준 100MB 이하만 업로드할 수 있어요.
* 리소스를 모두 포함하면 용량을 넘길 수 있으니, 리소스 파일은 빌드와 분리해서 관리하세요.
  {% endhint %}

#### 2-1. 콘솔에서 앱 번들 업로드 후 QR로 테스트하기

먼저 콘솔에 앱 번들(`.ait`) 파일을 업로드하세요. 테스트를 최소 1번 이상 완료해야 검토를 요청할 수 있어요.

> **앱 번들 파일이 업로드되지 않나요?**
>
> 앱이 정상적으로 빌드됐는지 확인해 주세요. `npm run build`로 생성한 번들이 아니거나 프로젝트 구조가 올바르지 않으면, 앱 번들 컴파일이 실패해서 업로드되지 않아요.

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

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

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

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2F7UHLc2xBtRJ3Z66xdaFT%2F%E1%84%87%E1%85%B5%E1%84%80%E1%85%A6%E1%84%8B%E1%85%B5%E1%86%B7%2032.png?alt=media&amp;token=e2471961-74e5-42fe-bab2-26c1384acd42" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FUfLbu8Jhp1iMYNz4ZYQV%2F%E1%84%8B%E1%85%B5%E1%84%86%E1%85%B5%E1%84%8C%E1%85%B5.png?alt=media&amp;token=ffe46d48-7b15-40d7-96c4-00f773d1385b" alt=""><figcaption></figcaption></figure>

#### 2-2. CI/CD 명령어 사용하기

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

CI/CD 명령어로 자동 업로드하려면 SDK v1.4.0 이상이 필요해요. 이전 버전을 쓰고 있다면 먼저 SDK를 업그레이드해 주세요.

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

> 접속 경로: 워크스페이스 선택 → 왼쪽 메뉴에서 '키'

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FTRGlSNFN10sqdcSQ4APK%2F%E1%84%8F%E1%85%B5%2065.png?alt=media&amp;token=4683c816-1797-43e2-aafb-6a303e0a5b6f" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FjOJeYrLClNjd8ioFdl20%2Fimage.png?alt=media&amp;token=51ed417b-f10d-41ae-b047-8e3ca33c54ef" alt=""><figcaption></figcaption></figure>

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

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

API 키를 등록해 두면 반복해서 입력하지 않아도 돼요.

```
npx ait token add
npx ait deploy
```

`-m` 옵션으로 번들을 업로드할 때 메모를 함께 남길 수 있어요.

```
npx ait deploy -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`는 필수 파라미터예요.

```
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 인코딩해야 해요):

```
intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec&queryParams=%7B%22categoryKey%22%3A%22
```

***

### 자주 묻는 질문

<details>

<summary>iOS에서 흰 화면이 보여요.</summary>

샌드박스에서는 정상 동작하는데 토스 앱에서 흰 화면이 보인다면, 아래 항목을 순서대로 점검해 보세요.

1. **Sentry로 오류 감지·모니터링하기** — 런타임 에러가 났는데 바로 확인되지 않는 경우가 있어요. Sentry로 에러를 수집해서, 실제 사용자 환경에서 생기는 오류를 추적해 보세요. [Sentry 설정 가이드](https://developers-apps-in-toss.toss.im/ai-vibe-coding/integration/sentry#id-1.-sentry)
2. **메모리·리소스 사용량 점검하기** — 토스 앱에서는 메모리 제약 때문에 앱이 제대로 렌더링되지 못하고 흰 화면이 보일 수 있어요.
   * 이미지·폰트 등 리소스 용량을 줄여 빌드 파일을 최적화하세요.
   * 분할 로딩 구조를 적용해, 처음에는 꼭 필요한 파일만 불러오고 나머지 리소스는 순차적으로 불러오도록 구성해 보세요.
   * 불필요한 객체 생성이나 메모리 누수가 없는지 점검하세요.

</details>

<details>

<summary>토스 앱에서 통신이 되지 않아요.</summary>

* **CORS 설정 확인** — 미니앱에서 서버와 통신하려면, 서버의 CORS 허용 Origin에 미니앱 Origin을 추가해야 해요. 허용해야 하는 Origin은 SDK 버전과 적용일에 따라 달라요.

{% hint style="info" %}
**SDK 3.x Origin 변경 안내**

2026년 8월 25일(화) 이후 업로드되는 SDK 3.x 번들부터, SDK 2.x에서 사용하던 Origin으로 서비스돼요.\
외부 서버와 통신하는 경우, 서버의 CORS 허용 Origin에 아래 Origin을 추가해 주세요.

* `https://<appName>.apps.tossmini.com` : 실제 서비스 환경
* `https://<appName>.private-apps.tossmini.com` : 콘솔 QR 테스트 환경
  {% endhint %}

SDK 3.x

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

\
SDK 1.x \~ 2.x

* `https://<appName>.apps.tossmini.com` : 실제 서비스 환경
* `https://<appName>.private-apps.tossmini.com` : 콘솔 QR 테스트 환경
* **App Transport Security(ATS) 설정 확인** — 샌드박스에서는 HTTP 요청이 허용되지만, 라이브 환경에서는 HTTPS만 허용돼요. HTTP 기반 API는 토스 앱에서 차단돼요.
* **iOS 서드파티 쿠키 차단 정책 확인** — iOS·iPadOS 13.4 이상에서는 서드파티 쿠키가 완전히 차단돼요. 쿠키 기반 로그인 대신 토큰 기반 인증 방식을 적용하세요.

</details>

<details>

<summary>토스앱에서 미니앱이 열리지 않아요.</summary>

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

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/guide/operation/toss.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.