> 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 ### 1. Create the app bundle file An app bundle is `.ait` a file with the extension, and it is the packaged result of the built project. Run the command below to generate the app bundle. When the build is finished, in the project root directory `.ait` a 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 uncompressed can be uploaded. Including all resources such as images, sound, and video may exceed the size limit, so manage resource files separately from the build. We recommend managing resources like this. * Include only the minimum resources essential for running the app in the bundle. * Configure large resources to be downloaded from external storage or a CDN. * Applying a progressive download approach (Lazy Loading) for additional resources improves the user experience. {% hint style="info" %} **App bundle size policy** * Only app bundles up to 100 MB uncompressed can be uploaded. * Including all resources may exceed the size limit, so manage resource files separately from the build. {% endhint %} #### 2-1. Test by uploading the app bundle in the console and using a QR code 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 successfully. `npm run build`If it is not a bundle created with , or if the project structure is not correct, app bundle compilation will fail and it won't be uploaded. After uploading the app bundle, press the 'Test' button to view the QR code for Toss app testing in the console. Scanning the QR code launches the mini app in the Toss app. QR code testing can be run only if all of the conditions below 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.
#### 2-2. Use CI/CD commands You can upload the app bundle via the CLI without accessing the console. To automatically upload with CI/CD commands, SDK v1.4.0 or later is required. If you're 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. > Access path: Select workspace → 'Keys' in the left menu
Run the command below to upload the app bundle. If the upload succeeds, you can check the test app scheme. ``` npx ait deploy --api-key {API key} ``` If you register the API key, you won't need to enter it repeatedly. ``` npx ait token add npx ait deploy ``` `-m` When uploading a bundle with the -m option, you can also leave a memo. ``` npx ait deploy -m "release notes" ``` Use 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 (between 10 and 300 seconds) | *** ### 3. Test features `intoss://` The scheme can only be accessed after the app is officially released. Feature testing before release must be done with the test scheme (QR code) generated during upload. #### Check the deploymentId in the QR code Each 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 a subpath is applied: ``` intoss-private://appsintoss/path/pathpath?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec ``` When query parameters are applied (queryParams must be URL-encoded): ``` intoss-private://appsintoss?_deploymentId=0198c000-68c3-7d2b-0000-2c00000005ec&queryParams=%7B%22categoryKey%22%3A%22 ``` *** ### Frequently Asked Questions
A white screen appears on iOS. If it works properly in the sandbox but shows a white screen in the Toss app, check the items below in order. 1. **Detect and monitor errors with Sentry** — Sometimes a runtime error occurs but isn't immediately visible. Collect errors with Sentry and 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 and cause a white screen. * Optimize the build file by reducing resource size such as images and fonts. * Apply a split-loading structure so that only the files needed at first are loaded initially and the remaining resources are loaded sequentially. * Check whether there are unnecessary object creations or memory leaks.
Communication doesn't work in the Toss app. * **Check CORS settings** — To communicate with the server from the mini app, you need to add the mini app Origin to the server's allowed CORS Origins. The Origin that must be allowed depends on the SDK version and the date applied. {% hint style="info" %} **Guide to SDK 3.x Origin changes** Starting with SDK 3.x bundles uploaded after Tuesday, August 25, 2026, the service will use the Origin used in SDK 2.x.\ If you communicate with an external server, add the following Origin to the server's allowed CORS Origins. * `https://.apps.tossmini.com` : Production environment * `https://.private-apps.tossmini.com` : Console QR testing environment {% endhint %} SDK 3.x * `https://.web.tossmini.com` : Production environment * `https://.private-web.tossmini.com` : Console QR testing environment \ SDK 1.x \~ 2.x * `https://.apps.tossmini.com` : Production environment * `https://.private-apps.tossmini.com` : Console QR testing 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 the 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.
The mini app doesn't open in the Toss app. Errors may occur in earlier versions of the Toss app. Please test in the latest version of the Toss app.
--- # 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=&goal= ``` `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.