> 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/landing-page/landing-page-en/development/test/sandbox.md). # Test app (sandbox) ## Test app (sandbox) Apps in Toss does not provide a separate Toss app for development. Instead **dedicated sandbox app**you can use it to set up your development and testing environment. {% hint style="info" %} **Please make sure to check** Before releasing to production, you must complete feature verification in the sandbox app. Even if you finish testing in the sandbox app, your submission may be rejected during launch review if there are any guideline violations. The current 3.x version does not provide a sandbox app. Instead, you can develop in a browser through the devtools installed together. {% endhint %} *** ### What is the sandbox app? Apps in Toss provides partner services inside the Toss app **App-in-App** format. Instead of a separate Toss app for development, **dedicated sandbox app for development and QA**you can run integration tests through it. After installing the sandbox app, start development in the order below. 1. Environment setup 2. Install the sandbox app 3. Login → Select an app → Access scheme (URL) #### Supported OS versions | Category | Minimum version | | -------- | --------------- | | Android | Android 7 | | iOS | iOS 16 | {% hint style="info" %} **App Transport Security (ATS)** To prevent violating the App Transport Security (ATS) policy, **HTTP communication is allowed in the sandbox app**. However, in the live environment, **only HTTPS is supported**so HTTP-based features work properly only in the sandbox. {% endhint %} *** ### 1. Set up the environment #### iOS environment setup To test in the iOS simulator, **Xcode**is required. {% hint style="info" %} **iOS third-party cookie blocking policy** On iOS/iPadOS 13.4 or later, **third-party cookies are completely blocked**. If you implement cookie-based login on a partner domain that is not an Apps in Toss domain, it will not work properly. **Alternative authentication methods such as token-based ones**should be used. {% endhint %} **1-1. Install Xcode** [Download the latest version of Xcode](https://apps.apple.com/kr/app/xcode/id497799835?mt=12)and install it from the Mac App Store. **1-2. Install iOS components** If you installed Xcode for the first time, you also need to install iOS 15 or later components. If a window like the one below appears, select iOS and install it. **1-3. Install Xcode Command Line Tools** Xcode Command Line Tools must **have the same version as the main Xcode app** . **Check the Xcode version** 1. Open Xcode and click \[Xcode] > \[About Xcode] in the top menu. 2. Check the version shown on the screen. **Check the Xcode Command Line Tools version** 1. In Xcode, click \[Xcode] > \[Settings]. 2. In the \[Locations] tab, check the version of the Command Line Tools item. **1-4. Run the simulator** 1. In the top menu of Xcode, select \[Xcode] > \[Open Developer Tool] > \[Simulator]. 2. Make sure you can use iOS 15 or later.
If the simulator is not visible, 1. open the Simulator app. 2. Click \[File] > \[Open Simulator] in the top menu. 3. Select the device you want on iOS 15 or later.
*** #### Android environment setup To run React Native in an Android environment, **Android SDK**and [`adb`(Android Debug Bridge)](https://developer.android.com/tools/adb?hl=ko)is required. **1-1. Install Android Studio** [Android Studio installation link](https://developer.android.com/studio?hl=ko)and install it. **1-2. Install Android SDK Command-line Tools** 1. In Android Studio, click \[Android Studio] > \[Settings] in the top menu. 2. Select \[Languages & Frameworks] > \[Android SDK]. 3. In the \[SDK Tools] tab, check "Android SDK Command-line Tools" and press OK to install it. **1-3. Set environment variables** `adb`To use it, you need to set environment variables. {% tabs %} {% tab title="macOS" %} ```bash # Add this to .zshrc or .bashrc. export ANDROID_HOME=~/Library/Android/sdk export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools ``` {% endtab %} {% endtabs %}
Set Windows environment variables **1. Open the Run prompt** `Windows` + `R` Press the key to open the Run window, `SystemPropertiesAdvanced`type it, and press Enter. **2. Open the Environment Variables menu** In the \[System Properties] window, select the \[Advanced] tab, then click the \[Environment Variables] button at the bottom. **3. Edit Path in User variables** In the User variables section, `Path` select the variable and click \[Edit]. `Path` If the variable does not exist, click \[New] and set the name to `Path`. **4. Add the Android SDK path** In the edit window, click \[New] and add the following path. `{username}`Replace it with your current Windows user account name. `C:\Users\{username}\AppData\Local\Android\sdk\platform-tools`
Check whether the environment variable has been registered correctly with the command below. ```sh adb version # Android Debug Bridge version 1.0.41 ``` **1-4. Connect a device** **Enable Developer options** {% hint style="info" %} The method for enabling Developer options may vary by device manufacturer. Check the manufacturer-specific guide for your device through an internet search. {% endhint %} For Galaxy devices, enable it as follows. 1. Open the \[Settings] app 2. Go to \[About phone] > \[Software information] 3. Tap the \[Build number] item repeatedly and quickly **Enable USB debugging** 1. Go to \[Settings] > \[Developer options]. 2. Enable \[USB debugging]. **Connect the PC and device** Connect the PC and device with a USB cable, then check the connection status with the command below. ```sh adb devices # List of devices attached # R3CTA0BMCPK device ``` If a device ID appears under "List of devices attached", the connection was successful.
If a device ID does not appear, * **Check USB debugging is enabled**: Confirm that \[Settings] > \[Developer options] > \[USB debugging] is turned on. * **Restart ADB server**: `adb kill-server` After running it, `adb devices`check again.
**1-5. Set up the emulator** > ⚠️ For debugging and QA, we recommend using **a physical device**whenever possible. After running Android Studio, add an emulator by clicking \[Virtual Device Manager] > \[+ button] in the right menu. {% hint style="info" %} **Galaxy S23 specs reference** * Display: 6.1 inches * OS: supported from API 33 {% endhint %} If you proceed in the order \[Pixel 8a] > \[VanillaIceCream (API 35)] > \[Set AVD Name], the emulator setup is complete. You can run the added emulator by clicking the play button in \[Virtual Device Manager]. *** ### 2. Install the sandbox app The sandbox app is updated frequently. If you see an error, **update to the latest version**. {% hint style="info" %} The current 3.x version does not provide a sandbox app. Instead, you can develop in a browser through the devtools installed together. The sandbox app below can be used in version 2.x. {% endhint %} | Category | Build number | Download | | --------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Android | 2026-05-21 | [Download](https://static.toss.im/appsintoss/rn-miniapp-real-release-protected.zip) | | iOS (simulator) | 2026-06-02 | [Download](https://static.toss.im/appsintoss/apps-in-toss-sandbox-202606022149.zip) | | iOS (physical device) | 2026-03-11 | ![](https://679554798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGK6CDpIZXnm3aqLRTFjB%2Fuploads%2FC7oJ6TQO5H7EdMZgCoD9%2Fapp-in-toss-sandbox-qr.png?alt=media\&token=c2933af2-16a2-47e0-86e4-8dbb28948b32) | #### Install on iOS **Simulator** Download the sandbox app file **and drag and drop it onto the simulator screen**. Once installation is complete, the app will appear on the simulator home screen. Please wait a moment until installation is complete. **Physical device** Install from the App Store using the QR code in the table above. #### Install on Android Both the physical device and the emulator use the same APK file. **Install with Android Studio** 1. Check whether the connected device appears in the \[Device Manager] menu on the right side of Android Studio. 2. Click the \[Start Mirroring] button to display the device screen in Android Studio. 3. Drag the downloaded APK file onto the device screen to install it. **Install with adb command** ```sh # Run after moving to the folder containing the APK file adb install -r -t {filename} # Example adb install -r -t apssintoss-debug.apk ``` *** ### 3. Use the sandbox app #### 1. Developer login Log in with the Toss Business account used in the console. If you need to sign up for Toss Business, [register an app in the console](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/console-workspace)and check it. {% hint style="info" %} **Please use a personal account** Please log in with a personal account registered with Toss Business. **with a personal account enrolled in Toss Business.** If you use a shared account, login may fail or sessions may frequently end. If it is difficult to use a personal account, please contact us via Channel Talk. {% endhint %} #### 2. Select an app The list of apps in the workspace you belong to will be displayed. **The app to test**select it. #### 3. Toss authentication registered in the console **Toss account**to proceed with identity verification. On the smartphone **with the Toss app installed for that account**, open the push notification to complete verification. #### 4. Access via scheme (URL) Enter the scheme to access, and the mini app will launch. ``` intoss://{appName} ``` *** ### 4. Run the mini app #### Run it in the iOS simulator 1. Launch the sandbox app. 2. Enter the scheme and click the "Open Scheme" button. Example: `intoss://kingtoss` \[Watch video]\(../../resources/development/local-server/local-develop-ios-sim-example.mp4) #### Run it on an iOS physical device You must be connected to the same Wi-Fi as the local server. 1. When launching the sandbox app, **"Local Network"** if a permission request appears, **"Allow"** tap the button. 2. On the server address input screen, enter the local server IP address and save it. * On macOS, `ipconfig getifaddr en0` can be used to check the IP address. 3. Tap the "Open Scheme" button. 4. At the top of the screen, `Bundling {n}%...`if it is displayed, the connection was successful.
How to manually allow the "Local Network" permission 1. In the iPhone \[Settings] app, **"Apps in Toss"** search for it and go there. 2. **"Local Network"** turn on the option.
#### Run it on an Android emulator or physical device 1. Connect the PC and device with a USB cable. 2. `adb` Connect the ports with the command below. ```sh adb reverse tcp:8081 tcp:8081 adb reverse tcp:5173 tcp:5173 ``` To connect a specific device, `-s` add the option. ```sh adb -s {deviceId} reverse tcp:8081 tcp:8081 adb -s {deviceId} reverse tcp:5173 tcp:5173 ``` 3. In the sandbox app, enter the scheme and click the run button. Example: `intoss://kingtoss` \[Watch video]\(../../resources/development/local-server/local-develop-android-example.mp4)
Frequently used adb commands ```sh # Disconnect adb kill-server # Connect ports adb reverse tcp:8081 tcp:8081 adb reverse tcp:5173 tcp:5173 # Check connection status adb reverse --list ```
*** ### Testable features For features not supported in the sandbox, please test them in the Toss app using the QR code in console's 'Launch' section. [Toss app](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/toss)and test there. | Feature | Testability | | ----------------------------- | ----------------------------------- | | Toss Login | ✅ Available | | Issue user identification key | ✅ Available (mock data is returned) | | Toss Pay | ✅ Available | | In-app payment | ✅ Available | | Game profile & leaderboard | ✅ Available | | Analytics | ❌ Not available | | Shared rewards | ❌ Not available | | In-app ads | ❌ Not available | | Landscape version game | ❌ Not available | | Share navigation bar | ❌ Not available | *** ### Frequently asked questions
Testing in the sandbox isn't going well. Sandbox **Please complete the developer login**. If the login expires, sandbox testing will not work smoothly.
I'm trying to test Toss Login, but it's not working well. Sandbox **Please complete the developer login**Please complete it first . If login is not done first, Toss Login testing may not work smoothly.
The Toss Login terms screen does not appear. If you do not log in as a sandbox developer, **the Toss Login terms screen will not be displayed.** Please test using the QR code in the console.
The sandbox app doesn't work. The sandbox app is updated frequently. If you see an error, **update it to the latest version.**
*** ### Troubleshooting
The `Unable to connect to server` error occurs (Android) Add \`--host\` to \`web.commands\` in \`granite.config.ts\`, then run the service to check the host address. ```ts web: { commands: { dev: 'vite --host', // add --host build: 'tsc -b && vite build', }, }, ``` After checking the host address, `web.host`enter it. ```ts web: { host: 'x.x.x.x', // host address where the service runs }, ```
The Metro development server is open, but the message "There was a temporary problem" appears It may be a problem where you are not properly connected to the development server. Disconnect \`adb\` and try reconnecting ports 8081 and 5173.
A Not Found error occurs on the PC web Port 8081 is for recognition inside the sandbox. On the PC web, a Not Found error occurs.
--- # 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/landing-page/landing-page-en/development/test/sandbox.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.