It doesn’t have to be perfect. Build your mini app for a chance to win up to KRW 3 million.
Ctrlk
SupportCommunityConsole
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Test a mini app

Upload the app bundle (.ait) file, and you can perform final testing in the Toss app with the generated test app scheme.

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.

npm run build
pnpm build
yarn build

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.

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.

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 buildIf 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.

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

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

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

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

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 deploymentIdis issued. In the test scheme, _deploymentIdis a required parameter.

Test by applying path and query to the scheme

When applying a sub path:

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

Frequently asked questions

A white screen appears on iOS.

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

  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.

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 CORS allowed origins. The allowed origin depends on the SDK version and the effective date.

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

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.

The mini app doesn't open in the Toss app.

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

PreviousRegister a mini app
NextLaunch a mini app