> 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/en/operation/toss.md).

# Test a mini app

Upload the app bundle (.ait) file and use the generated test app scheme to perform final testing in the Toss app.

### 1. Create an app bundle file

An app bundle is `.ait` a file with the .ait extension, and it is the result of packaging a built project. Run the command below to create an app bundle. When the build is complete, in the project root directory `<service name>.ait` the file will be created.

{% 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. Test in the Toss app

There are two ways to upload an app bundle and test it in the Toss app.

1. Upload directly from the console and test with a QR code
2. Automatic upload with CI/CD commands

Only app bundles up to 100 MB after extraction can be uploaded. If you include all resources such as images, sounds, and videos, you may exceed the size limit, so manage resource files separately from the build.

We recommend managing resources like this.

* Include only the minimum resources required to run the app in the bundle.
* Configure large resources to be downloaded from external storage or a CDN.
* Applying lazy loading for additional resources improves the user experience.

{% hint style="info" %}
**App bundle size policy**

* Only app bundles up to 100 MB after extraction can be uploaded.
* If you include all resources, you may exceed the size limit, so manage resource files separately from the build.
  {% endhint %}

#### 2-1. Upload the app bundle from the console and test with QR

First, upload the app bundle (`.ait`) file to the console. You must complete testing at least once before you can request review.

> **Is the app bundle file not uploading?**
>
> Please check whether the app was built properly. `npm run build`If it wasn't created with that command or the project structure is not correct, app bundle compilation will fail and it won't be uploaded.

After uploading the app bundle, click the 'Test' button to view the Toss app test QR code in the console. Scanning the QR code will launch the mini app in the Toss app.

QR code testing can run only when all of the following conditions are met.

* You must be logged in to the Toss app.
* You must be a workspace member.
* Only users aged 19 or older can test.

<figure><img src="https://941686070-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://941686070-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. Use CI/CD commands

You can upload the app bundle via CLI without accessing the console.

To upload automatically with CI/CD commands, SDK v1.4.0 or later is required. If you are using an earlier version, please upgrade the SDK first.

First, issue an API key in the console. You can set access permissions for the entire app or for a specific app.

> Path: Select a workspace → 'Keys' in the left menu

<figure><img src="https://941686070-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://941686070-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>

Run the command below to upload the app bundle. If the upload succeeds, you can check the app scheme for testing.

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

If you register an API key in advance, you don't have to enter it repeatedly.

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

`-m` When uploading a bundle with the option, you can include a memo as well.

```
npx ait deploy -m "release notes"
```

Try using the commands below as needed.

| Command                                                          | Purpose                                                                      |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| npx ait token --help                                             | View help                                                                    |
| npx ait token add \[workspace name] \[API key]                   | Register token                                                               |
| npx ait token remove \[workspace name]                           | Delete registered token                                                      |
| npx ait deploy \[workspace name] \[API key]                      | Upload bundle                                                                |
| npx ait deploy \[workspace name] \[API key] --timeout \[seconds] | Set the maximum wait time for checking deployment status (10 to 300 seconds) |

***

### 3. Test features

`intoss://` The scheme can be accessed only after the app is officially released. Feature testing before release must be done with the test scheme (QR code) created during upload.

#### Check deploymentId in the QR code

Every time you upload an app bundle, a new `deploymentId`is issued. In the test scheme, `_deploymentId`is a required parameter.

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

#### Test by applying path and query to the scheme

When applying a sub path:

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

When applying query parameters (queryParams must be URL-encoded):

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

***

### Frequently asked questions

<details>

<summary>A white screen appears on iOS.</summary>

If it works normally in the sandbox but a white screen appears in the Toss app, check the items below in order.

1. **Detect and monitor errors with Sentry** — There are cases where a runtime error occurs but isn't noticed right away. Collect errors with Sentry to track issues that occur in real user environments. [Sentry setup guide](https://developers-apps-in-toss.toss.im/ai-vibe-coding/integration/sentry#id-1.-sentry)
2. **Check memory and resource usage** — In the Toss app, memory constraints may prevent the app from rendering properly, resulting in a white screen.
   * Optimize the build file by reducing resource sizes such as images and fonts.
   * Apply a split-loading structure so that only the files that are absolutely necessary are loaded first, and the remaining resources are loaded sequentially.
   * Check for unnecessary object creation or memory leaks.

</details>

<details>

<summary>Communication doesn't work in the Toss app.</summary>

* **Check CORS settings** — To communicate with the server from the mini app, you need to add the mini app origin to the server's CORS allowed origins. The allowed origin depends on the SDK version and the effective date.

{% hint style="info" %}
**SDK 3.x origin change guide**

Starting with SDK 3.x bundles uploaded after Tue, August 25, 2026, they are served using the origin used in SDK 2.x.\
If you communicate with an external server, add the origin below to the server's CORS allowed origins.

* `https://<appName>.apps.tossmini.com` : real service environment
* `https://<appName>.private-apps.tossmini.com` : console QR test environment
  {% endhint %}

SDK 3.x

* `https://<appName>.web.tossmini.com` : real service environment
* `https://<appName>.private-web.tossmini.com` : console QR test environment

\
SDK 1.x \~ 2.x

* `https://<appName>.apps.tossmini.com` : real service environment
* `https://<appName>.private-apps.tossmini.com` : console QR test environment
* **Check App Transport Security (ATS) settings** — HTTP requests are allowed in the sandbox, but only HTTPS is allowed in the live environment. HTTP-based APIs are blocked in the Toss app.
* **Check iOS third-party cookie blocking policy** — On iOS and iPadOS 13.4 or later, third-party cookies are completely blocked. Use token-based authentication instead of cookie-based login.

</details>

<details>

<summary>The mini app doesn't open in the Toss app.</summary>

Errors may occur in older versions of the Toss app. Please test using the latest version of the Toss app.

</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/en/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.