> 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)
App in Toss does not provide a separate Toss app for development. Instead, **a dedicated sandbox app**can be used to set up a development and testing environment.
{% hint style="info" %}
**Please be sure to check**
Before launching the service, you must complete feature verification in the sandbox app. Even if you finish testing in the sandbox app, your submission may be rejected during release review if it violates the guidelines.
Currently, version 3.x does not provide a sandbox app. Instead, you can develop in a browser through the devtools installed together.
{% endhint %}
***
### What is the sandbox app?
App in Toss provides partner services within the Toss app **App-in-App** format. Instead of a separate Toss app for development, **a sandbox app dedicated to development and QA**can be used for integration testing.
After installing the sandbox app, start development in the order below.
1. Environment setup
2. Install the sandbox app
3. Log in → Select an app → Access the scheme (URL)
#### Supported OS versions
| Category | Minimum version |
| -------- | --------------- |
| Android | Android 7 |
| iOS | iOS 16 |
{% hint style="info" %}
**App Transport Security (ATS)**
To prevent violations of 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 and later, **third-party cookies are completely blocked**. If you implement cookie-based login on a partner domain rather than an App in Toss domain, it will not work properly. **Please use an alternative authentication method such as token-based authentication**.
{% 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 need to additionally install iOS 15 or later components. When the window below appears, select iOS and install it.
**1-3. Install Xcode Command Line Tools**
Xcode Command Line Tools must **be the same version as the Xcode app itself** .
**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. Check the version of Command Line Tools in the \[Locations] tab.
**1-4. Run the simulator**
1. In the Xcode top menu, 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**
[Install it from the Android Studio installation link](https://developer.android.com/studio?hl=ko).
**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 click OK to install it.
**1-3. Set environment variables**
`adb`You need to set environment variables to use
{% 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 and `SystemPropertiesAdvanced`type it in and press Enter.
**2. Open the environment variables menu**
In the \[System Properties] window, select the \[Advanced] tab and 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 variables were 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 by searching online.
{% 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**
After connecting the PC and device with a USB cable, check the connection status with the command below.
```sh
adb devices
# List of devices attached
# R3CTA0BMCPK device
```
If the device ID appears under "List of devices attached," the connection was successful.
If the device ID does not appear,
* **check whether USB debugging is enabled**: \[Settings] > \[Developer options] > \[USB debugging] is turned on.
* **Restart the ADB server**: `adb kill-server` then `adb devices`check again.
**1-5. Set up the emulator**
> ⚠️ For debugging and QA, it is recommended to use **a physical device**.
After running Android Studio, go to \[Virtual Device Manager] in the right menu and click the \[+] button to add an emulator.
{% hint style="info" %}
**Galaxy S23 specs reference**
* Display: 6.1 inches
* Operating system: Supported from API 33
{% endhint %}
If you proceed in the order \[Pixel 8a] > \[VanillaIceCream (API 35)] > \[Set AVD Name], the emulator setup is complete.
The added emulator can be launched by pressing 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**please.
| 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 | |
| QR code link: 샌드박스/id6745618667 | | |
| | | |
#### Install on iOS
**Simulator**
Drag and drop the downloaded sandbox app file **onto the simulator screen**to install it. Once installation is complete, the app will appear on the simulator home screen. Please wait a moment until installation finishes.
**Physical device**
Install from the App Store using the QR code in the table above.
#### Install on Android
Both the physical device and emulator use the same APK file.
**Install with Android Studio**
1. Check that the connected device appears in the \[Device Manager] menu on the right in 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 using adb commands**
```sh
# After moving to the folder containing the APK file, run
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 the app in the console](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/console-workspace)please check.
{% hint style="info" %}
**Please use a personal account**
If you have signed up for Toss Business, **please log in with your personal account.** If you use a shared account, login may fail or the session may end frequently. If it is difficult to use a personal account, please contact us via Channel Talk.
{% endhint %}
#### 2. Select an app
The app list in your workspace will be displayed. **App to test**please select it.
#### 3. Toss authentication
Registered in the console **Toss account**to verify your identity. On the **smartphone with the Toss app installed**open the push notification and complete verification.
#### 4. Access via scheme (URL)
If you enter the scheme to access, the mini app will launch.
```
intoss://{appName}
```
***
### 4. Run the mini app
#### Run in the iOS simulator
1. Launch the sandbox app.
2. Enter the scheme and press the "Open Scheme" button. Example: `intoss://kingtoss`
\[Watch video]\(../../resources/development/local-server/local-develop-ios-sim-example.mp4)
#### Run on a real iOS device
You need to be on the same Wi‑Fi network as the local server.
1. When running the sandbox app **"Local Network"** when the permission request appears, **"Allow"** button.
2. On the server address input screen, enter the local server IP address and save it.
* On macOS, `ipconfig getifaddr en0` you can check the IP address with the command.
3. Press the "Open Scheme" button.
4. At the top of the screen, `Bundling {n}%...`appears, the connection is successful.
How to manually allow the "Local Network" permission
1. In the iPhone \[Settings] app, **"App in Toss"** search for it and go to it.
2. **"Local Network"** turn on the option.
#### Run on an Android emulator or real device
1. Connect the PC and device with a USB cable.
2. `adb` Connect the port with the command.
```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. Enter the scheme in the sandbox app and press the Run button. Example: `intoss://kingtoss`
\[Watch video]\(../../resources/development/local-server/local-develop-android-example.mp4)
Commonly used adb commands
```sh
# Disconnect
adb kill-server
# Connect a port
adb reverse tcp:8081 tcp:8081
adb reverse tcp:5173 tcp:5173
# Check the connection status
adb reverse --list
```
***
### Testable features
Features not supported in the sandbox should be tested in the Toss app using the QR code under Console 'Release' [Toss app](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/toss)please test there.
| Feature | Whether testing is possible |
| -------------------------- | -------------------------------------------- |
| Toss login | ✅ Available |
| User identifier issuance | ✅ Available (however, mock data is returned) |
| Toss Pay | ✅ Available |
| In-app purchases | ✅ Available |
| Game profile & leaderboard | ✅ Available |
| Analytics | ❌ Not available |
| Share 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 **Developer login**please proceed.
If you get logged out, sandbox testing won't work smoothly.
I'm trying to test Toss login but it isn't working.
Sandbox **Developer login**Please do it first.
If login is not done first, Toss login testing may not work smoothly.
The Toss login terms screen doesn't appear.
If you don't log in to the sandbox as a developer, **the Toss login terms screen will not appear.**
Please test using the QR code in the console.
The sandbox app isn't working.
The sandbox app is updated frequently. If you see an error, **please update to the latest version.**
***
### Troubleshooting
A `Can't 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 is running
},
```
The Metro development server is open, but the `Something went wrong for a moment` message appears
You may not be properly connected to the development server. Disconnect \`adb\` and reconnect ports 8081 and 5173.
A Not Found error occurs on the PC web
Port 8081 is for recognition inside the sandbox. A Not Found error occurs on the PC web.
---
# 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.