Test app (sandbox)

Test app (sandbox)

Apps in Toss does not provide a separate Toss app for development. Instead dedicated sandbox appyou can use it to set up your development and testing environment.

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.

---

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 QAyou 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

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 supportedso HTTP-based features work properly only in the sandbox.

---

1. Set up the environment

iOS environment setup

To test in the iOS simulator, Xcodeis required.

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 onesshould be used.

1-1. Install Xcode

Download the latest version of Xcodeand 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 SDKand adb(Android Debug Bridge)is required.

1-1. Install Android Studio

Android Studio installation linkand 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

adbTo use it, you need to set environment variables.

macOS

# 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

Set Windows environment variables

1. Open the Run prompt

Windows + R Press the key to open the Run window, SystemPropertiesAdvancedtype 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.

adb version
# Android Debug Bridge version 1.0.41

1-4. Connect a device

Enable Developer options

The method for enabling Developer options may vary by device manufacturer. Check the manufacturer-specific guide for your device through an internet search.

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.

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 devicescheck again.

1-5. Set up the emulator

⚠️ For debugging and QA, we recommend using a physical devicewhenever possible.

After running Android Studio, add an emulator by clicking [Virtual Device Manager] > [+ button] in the right menu.

Galaxy S23 specs reference

• Display: 6.1 inches
• OS: supported from API 33

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.

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.

Category	Build number	Download
Android	2026-05-21	Download
iOS (simulator)	2026-06-02	Download
iOS (physical device)	2026-03-11

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

# 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 consoleand check it.

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.

2. Select an app

The list of apps in the workspace you belong to will be displayed. The app to testselect it.

3. Toss authentication

registered in the console Toss accountto 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.

   adb reverse tcp:8081 tcp:8081
   adb reverse tcp:5173 tcp:5173

   To connect a specific device, -s add the option.

   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

# 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 appand 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 loginPlease 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.

web: {
  commands: {
    dev: 'vite --host', // add --host
    build: 'tsc -b && vite build',
  },
},

After checking the host address, web.hostenter it.

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.