测试 App（沙盒）

测试应用（沙盒）

Apps in Toss 不会单独提供用于开发的 Toss 应用。相反 专用沙盒应用可通过其构建开发·测试环境。

请务必确认

在正式上线前，必须在沙盒应用中完成功能验证。即使已在沙盒应用中完成测试，若上线审核发现有违反指南的内容，也可能被驳回。

目前 3.x 版本不提供沙盒应用。相反，可通过随附安装的 devtools 在浏览器中开发。

---

什么是沙盒应用？

Apps in Toss 会在 Toss 应用内将合作伙伴的服务 应用内应用（App-in-App） 形式提供。无需单独的开发用 Toss 应用， 开发·QA 专用沙盒应用可通过其进行联调测试。

安装沙盒应用后，请按以下顺序开始开发。

1. 环境设置
2. 安装沙盒应用
3. 登录 → 选择应用 → 访问 Scheme(URL)

支持的 OS 版本

分类	最低版本
Android	Android 7
iOS	iOS 16

App Transport Security (ATS)

为防止违反 App Transport Security(ATS) 政策 沙盒应用中允许 http 通信。但在正式环境中 仅支持 https，因此基于 http 的功能只能在沙盒中正常工作。

---

1. 设置环境

iOS 环境设置

若要在 iOS 模拟器中测试， Xcode是必需的。

iOS 的第三方 Cookie 阻止政策

在 iOS/iPadOS 13.4 及以上版本中， 第三方 Cookie 会被完全阻止。如果在非 Apps in Toss 域名的合作伙伴域名中实现基于 Cookie 的登录，将无法正常工作。 基于令牌等替代认证方式请采用。

1-1. 安装 Xcode

下载最新版本的 Xcode请点击并在 Mac App Store 中安装。

1-2. 安装 iOS 组件

首次安装 Xcode 时，需要额外安装 iOS 15 及以上的组件。若出现如下窗口，请选择 iOS 并安装。

1-3. 安装 Xcode Command Line Tools

Xcode Command Line Tools 的版本必须与 Xcode 本体一致 。

确认 Xcode 版本

1. 打开 Xcode，然后在顶部菜单中点击 [Xcode] > [About Xcode]。
2. 请确认屏幕上显示的版本。

确认 Xcode Command Line Tools 版本

1. 在 Xcode 中点击 [Xcode] > [Settings]。
2. 在 [Locations] 选项卡中确认 Command Line Tools 项的版本。

1-4. 运行模拟器

1. 在 Xcode 顶部菜单中选择 [Xcode] > [Open Developer Tool] > [Simulator]。
2. 请确认是否可以使用 iOS 15 及以上版本。

如果看不到模拟器，

1. 请打开 Simulator 应用。
2. 在顶部菜单中点击 [File] > [Open Simulator]。
3. 在 iOS 15 及以上版本中选择所需设备。

---

Android 环境设置

若要在 Android 环境中运行 React Native， Android SDK和 adb（Android Debug Bridge）是必需的。

1-1. 安装 Android Studio

Android Studio 安装链接请通过此处安装。

1-2. 安装 Android SDK Command-line Tools

1. 在 Android Studio 中点击顶部菜单 [Android Studio] > [Settings]。
2. 请选择 [Languages & Frameworks] > [Android SDK]。
3. 在 [SDK Tools] 选项卡中勾选 “Android SDK Command-line Tools”，然后点击 OK 安装。

1-3. 设置环境变量

adb若要使用它，需要设置环境变量。

macOS

# 请添加到 .zshrc 或 .bashrc 中。
export ANDROID_HOME=~/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools

Windows 环境变量设置

1. 打开运行提示

Windows + R 键打开运行窗口， SystemPropertiesAdvanced输入后按 Enter。

2. 进入环境变量菜单

在 [系统属性] 窗口中选择 [高级] 选项卡，然后点击下方的 [环境变量] 按钮。

3. 在用户变量中编辑 Path

在用户变量区域中， Path 选择该变量后点击 [编辑] 按钮。 Path 如果没有该变量，请点击 [新建] 按钮并将名称 Path设为。

4. 添加 Android SDK 路径

在编辑窗口中点击 [新建] 按钮，添加以下路径。 {用户名}请替换为当前 Windows 用户账户名后输入。

C:\Users\{用户名}\AppData\Local\Android\sdk\platform-tools

请通过以下命令确认环境变量是否已正确注册。

adb version
# Android Debug Bridge version 1.0.41

1-4. 连接设备

启用开发者选项

不同设备厂商启用开发者选项的方法可能不同。请通过互联网搜索确认所用设备的厂商指南。

以 Galaxy 设备为例，按如下方式启用。

1. 打开 [设置] 应用
2. 进入 [关于手机] > [软件信息] 菜单
3. 快速多次点击 [版本号] 项

启用 USB 调试

1. 进入 [设置] > [开发者选项] 菜单。
2. 启用 [USB 调试] 项。

连接 PC 与设备

用 USB 数据线连接 PC 和设备后，通过以下命令确认连接状态。

adb devices
# List of devices attached
# R3CTA0BMCPK  device

如果在“List of devices attached”下显示设备 ID，就表示连接成功。

如果未显示设备 ID，

• 确认已启用 USB 调试：确认 [设置] > [开发者选项] > [USB 调试] 已开启。
• 重启 ADB 服务器: adb kill-server 执行后 adb devices再确认。

1-5. 设置模拟器

⚠️ 调试和 QA 尽可能 真机上进行，建议这样做。

启动 Android Studio 后，在右侧菜单中点击 [Virtual Device Manager] > [+ 按钮] 添加模拟器。

Galaxy S23 规格参考

• 显示屏：6.1 英寸
• 操作系统：从 API 33 起支持

按 [Pixel 8a] > [VanillaIceCream (API 35)] > [AVD Name 设置] 的顺序进行，即可完成模拟器设置。

新增的模拟器可在 [Virtual Device Manager] 中点击播放按钮启动。

---

2. 安装沙盒应用

沙盒应用会不定期更新。若看到错误， 更新到最新版本。

分类	版本号	下载
Android	2026-05-21	下载
iOS（模拟器）	2026-06-02	下载
iOS（真机）	2026-03-11
二维码链接：https://apps.apple.com/kr/app/Apps in Toss 沙盒/id6745618667

在 iOS 上安装

模拟器

将下载的沙盒应用文件 拖放到模拟器屏幕即可。安装完成后，应用会显示在模拟器主屏幕上。请稍候，直到安装完成。

真机

请通过上表的二维码在 App Store 中安装。

在 Android 上安装

真机和模拟器都使用同一个 APK 文件。

通过 Android Studio 安装

1. 请确认 Android Studio 右侧菜单 [Device Manager] 中是否显示已连接设备。
2. 点击 [Start Mirroring] 按钮，将设备屏幕显示到 Android Studio。
3. 将下载的 APK 文件拖到设备屏幕上进行安装。

通过 adb 命令安装

# 进入包含 APK 文件的文件夹后执行
adb install -r -t {文件名}

# 示例
adb install -r -t apssintoss-debug.apk

---

3. 使用沙盒应用

1. 开发者登录

请使用在控制台中使用的 Toss Business 账户登录。若需要注册 Toss Business， 在控制台中注册应用请查看。

请使用个人账户

已注册 Toss Business 的 请使用个人账户登录。 如果使用公共账户，可能会出现登录失败或会话频繁结束的情况。若难以使用个人账户，请通过 Channel Talk 联系我们。

2. 选择应用

所属工作区的应用列表会显示出来。 要测试的应用请选择。

3. Toss 认证

在控制台注册的 Toss 账户进行身份验证。该账户的 安装了 Toss 应用的智能手机请在其中打开推送完成认证。

4. 通过 Scheme(URL) 访问

输入要访问的 Scheme 后，迷你应用将启动。

intoss://{appName}

---

4. 运行迷你应用

在 iOS 模拟器中运行

1. 请启动沙盒应用。
2. 输入 Scheme 后点击“打开 scheme”按钮。例如： intoss://kingtoss

[观看视频](../../resources/development/local-server/local-develop-ios-sim-example.mp4)

在 iOS 真机中运行

需要连接到与本地服务器相同的 Wi‑Fi。

1. 运行沙盒应用时 “本地网络” 若显示权限请求， “允许” 按钮。
2. 在服务器地址输入页面中输入本地服务器 IP 地址并保存。

   • 在 macOS 中， ipconfig getifaddr en0 可以通过该命令确认 IP 地址。
3. 点击“打开 scheme”按钮。
4. 在屏幕顶部 Bundling {n}%...显示时，就表示连接成功。

手动允许“本地网络”权限的方法

1. 在 iPhone 的 [设置] 应用中 “Apps in Toss” 搜索并进入。
2. “本地网络” 请打开该选项。

在 Android 模拟器或真机中运行

1. 用 USB 数据线连接 PC 和设备。
2. adb 通过命令连接端口。

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

   若要连接特定设备， -s 请添加该选项。

   adb -s {设备ID} reverse tcp:8081 tcp:8081
   adb -s {设备ID} reverse tcp:5173 tcp:5173

3. 在沙盒应用中输入 Scheme 并点击运行按钮。例如： intoss://kingtoss

[观看视频](../../resources/development/local-server/local-develop-android-example.mp4)

常用 adb 命令

# 断开连接
adb kill-server

# 连接端口
adb reverse tcp:8081 tcp:8081
adb reverse tcp:5173 tcp:5173

# 确认连接状态
adb reverse --list

---

可测试的功能

沙盒不支持的功能，请通过控制台“发布”中的二维码 Toss 应用进行测试。

功能	是否可测试
Toss 登录	✅ 可以
用户标识键发放	✅ 可以（但会返回 mock 数据）
Toss Pay	✅ 可以
应用内购买	✅ 可以
游戏资料与排行榜	✅ 可以
分析	❌ 不可以
分享奖励	❌ 不可以
应用内广告	❌ 不可以
横屏版游戏	❌ 不可以
共享导航栏	❌ 不可以

---

常见问题

在沙盒中测试进展不顺利。

沙盒 开发者登录请进行。

如果登录失效，沙盒测试将无法顺利运行。

Toss 登录测试进展不顺利。

沙盒 开发者登录请先进行。

如果未先完成登录，Toss 登录测试可能无法顺利运行。

Toss 登录条款页面没有弹出。

如果不进行沙盒开发者登录， Toss 登录条款页面不会显示。

请通过控制台内的二维码进行测试。

沙盒应用不好用。

沙盒应用会不定期更新。若看到错误， 请更新到最新版本。

---

故障排查

发生“无法连接到服务器”错误（Android）

在 `granite.config.ts` 的 `web.commands` 中添加 `--host` 后运行服务并确认主机地址。

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

确认主机地址后 web.host输入。

web: {
  host: 'x.x.x.x', // 服务运行的主机地址
},

Metro 开发服务器已打开，但显示“暂时出现了问题”消息

可能是未正确连接到开发服务器的问题。请断开 `adb` 连接，然后重新连接 8081、5173 端口。

PC 网页端出现 Not Found 错误

8081 端口是用于在沙盒内识别的端口。在 PC 网页端会出现 Not Found 错误。