> 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-zh/development/test/sandbox.md). # 测试应用（沙盒） ## 测试应用（沙盒） Apps in Toss 不会单独提供开发用的 Toss 应用。相反 **专用沙盒应用**可通过它构建开发·测试环境。 {% hint style="info" %} **请务必确认** 在正式上线前，必须在沙盒应用中完成功能验证。即使已在沙盒应用中完成测试，如果在上线审核中发现违反指南的内容，也可能会被驳回。 目前 3.x 版本未提供沙盒应用。相反，可通过随附安装的 devtools 在浏览器中进行开发。 {% endhint %} *** ### 什么是沙盒应用？ Apps in Toss 会在 Toss 应用内将合作方的服务以 **App-in-App** 的形式提供。无需单独的开发用 Toss 应用， **开发·QA 专用沙盒应用**可通过它进行联调测试。 安装沙盒应用后，请按以下顺序开始开发。 1. 环境设置 2. 安装沙盒应用 3. 登录 → 选择应用 → 访问 scheme(URL) #### 支持的 OS 版本 | 区分 | 最低版本 | | ------- | --------- | | Android | Android 7 | | iOS | iOS 16 | {% hint style="info" %} **App Transport Security (ATS)** 为避免违反 App Transport Security (ATS) 政策 **沙盒应用中允许 http 通信**。但在正式环境中 **仅支持 https**，因此基于 http 的功能仅会在沙盒中正常运行。 {% endhint %} *** ### 1. 进行环境设置 #### iOS 环境设置 若要在 iOS 模拟器中测试 **Xcode**，则需要它。 {% hint style="info" %} **iOS 的第三方 Cookie 阻止政策** 在 iOS/iPadOS 13.4 及以上版本中， **第三方 Cookie 会被完全阻止**。如果在非 Apps in Toss 域名的合作方域名中实现基于 Cookie 的登录，将无法正常运行。 **请应用基于 Token 等替代认证方式**。 {% endhint %} **1-1. 安装 Xcode** [下载 Xcode 最新版本](https://apps.apple.com/kr/app/xcode/id497799835?mt=12)后，请在 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）](https://developer.android.com/tools/adb?hl=ko)，则需要它。 **1-1. 安装 Android Studio** [在 Android Studio 安装链接](https://developer.android.com/studio?hl=ko)中进行安装。 **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`要使用它，需要设置环境变量。 {% tabs %} {% tab title="macOS" %} ```bash # 请添加到 .zshrc 或 .bashrc 中。 export ANDROID_HOME=~/Library/Android/sdk export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools ``` {% endtab %} {% endtabs %}
设置 Windows 环境变量 **1. 打开运行提示** `Windows` + `R` 按键打开运行窗口，并 `SystemPropertiesAdvanced`输入后按 Enter。 **2. 进入环境变量菜单** 在 \[系统属性] 窗口中选择 \[高级] 标签，然后点击底部的 \[环境变量] 按钮。 **3. 在用户变量中编辑 Path** 在用户变量部分中 `Path` 变量后点击 \[编辑] 按钮。 `Path` 如果没有该变量，请点击 \[新建] 按钮并将名称 `Path`设置为 Path。 **4. 添加 Android SDK 路径** 在编辑窗口中点击 \[新建] 按钮，添加以下路径。 `{用户名}`请替换为当前 Windows 用户账户名后输入。 `C:\Users\{用户名}\AppData\Local\Android\sdk\platform-tools`
请通过以下命令确认环境变量是否已正确注册。 ```sh adb version # Android Debug Bridge version 1.0.41 ``` **1-4. 连接设备** **启用开发者选项** {% hint style="info" %} 根据设备制造商不同，启用开发者选项的方法也可能不同。请通过网络搜索确认你所使用设备的厂商指南。 {% endhint %} 以 Galaxy 设备为例，按如下方式启用。 1. 打开 \[设置] 应用 2. 进入 \[关于手机] > \[软件信息] 菜单 3. 快速多次点击 \[版本号] 项目 **启用 USB 调试** 1. 进入 \[设置] > \[开发者选项] 菜单。 2. 启用 \[USB 调试] 项目。 **连接 PC 和设备** 使用 USB 线连接 PC 和设备后，通过以下命令确认连接状态。 ```sh 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] > \[+ 按钮] 以添加模拟器。 {% hint style="info" %} **Galaxy S23 规格参考** * 显示屏：6.1 英寸 * 操作系统：从 API 33 起支持 {% endhint %} 按 \[Pixel 8a] > \[VanillaIceCream (API 35)] > \[设置 AVD 名称] 的顺序进行即可完成模拟器设置。 新增的模拟器可以在 \[Virtual Device Manager] 中点击播放按钮运行。 *** ### 2. 安装沙盒应用 沙盒应用会不时更新。若看到错误， **更新到最新版本**。 {% hint style="info" %} 目前 3.x 版本未提供沙盒应用。相反，可通过随附安装的 devtools 在浏览器中进行开发。 以下沙盒应用可在 2.x 版本中使用。 {% endhint %} | 区分 | 构建号 | 下载 | | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Android | 2026-05-21 | [下载](https://static.toss.im/appsintoss/rn-miniapp-real-release-protected.zip) | | iOS（模拟器） | 2026-06-02 | [下载](https://static.toss.im/appsintoss/apps-in-toss-sandbox-202606022149.zip) | | iOS（真机） | 2026-03-11 | ![](https://601356694-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) | #### 安装到 iOS **模拟器** 将下载的沙盒应用文件 **拖放到模拟器界面**即可。安装完成后，应用会显示在模拟器主屏幕上。请稍等片刻直到安装完成。 **真机** 请通过上表中的二维码在 App Store 中安装。 #### 安装到 Android 真机和模拟器都使用相同的 APK 文件。 **通过 Android Studio 安装** 1. 请确认 Android Studio 右侧菜单 \[Device Manager] 中是否显示已连接的设备。 2. 点击 \[Start Mirroring] 按钮，将设备屏幕显示到 Android Studio 中。 3. 将下载的 APK 文件拖到设备屏幕上进行安装。 **通过 adb 命令安装** ```sh # 进入 APK 文件所在文件夹后执行 adb install -r -t {文件名} # 示例 adb install -r -t apssintoss-debug.apk ``` *** ### 3. 使用沙盒应用 #### 1. 开发者登录 请使用控制台中使用的 Toss Business 账号登录。如果需要注册 Toss Business， [请在控制台中注册应用](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/console-workspace)请查看。 {% hint style="info" %} **请使用个人账号** 已注册 Toss Business 的 **请使用个人账号登录。** 如果使用共享账号，可能会出现登录失败或会话频繁结束的情况。若难以使用个人账号，请通过 ChannelTalk 联系我们。 {% endhint %} #### 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` 使用命令连接端口。 ```sh adb reverse tcp:8081 tcp:8081 adb reverse tcp:5173 tcp:5173 ``` 若要连接特定设备， `-s` 请添加该选项。 ```sh adb -s {디바이스아이디} reverse tcp:8081 tcp:8081 adb -s {디바이스아이디} reverse tcp:5173 tcp:5173 ``` 3. 在沙盒应用中输入 scheme，然后点击执行按钮。例： `intoss://kingtoss` \[查看视频]\(../../resources/development/local-server/local-develop-android-example.mp4)
常用 adb 命令 ```sh # 断开连接 adb kill-server # 连接端口 adb reverse tcp:8081 tcp:8081 adb reverse tcp:5173 tcp:5173 # 确认连接状态 adb reverse --list ```
*** ### 可测试的功能 沙盒不支持的功能，请通过控制台“发布”中的二维码 [Toss 应用](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/toss)中进行测试。 | 功能 | 是否可测试 | | ---------- | ----------------- | | Toss 登录 | ✅ 可 | | 用户识别键发放 | ✅ 可（但会返回 mock 数据） | | Toss Pay | ✅ 可 | | 应用内支付 | ✅ 可 | | 游戏资料 & 排行榜 | ✅ 可 | | 分析 | ❌ 不可 | | 分享奖励 | ❌ 不可 | | 应用内广告 | ❌ 不可 | | 横屏版游戏 | ❌ 不可 | | 分享导航栏 | ❌ 不可 | *** ### 常见问题
在沙盒中测试进展不顺利。 沙盒 **开发者登录**请先进行。 如果登录状态失效，沙盒测试将无法顺利运行。
进行 Toss 登录测试时不顺利。 沙盒 **开发者登录**请先进行。 如果未先登录，Toss 登录测试可能无法正常运行。
不显示 Toss 登录条款页面。 如果不进行沙盒开发者登录， **就不会显示 Toss 登录条款页面。** 请通过控制台内的二维码进行测试。
沙盒应用无法使用。 沙盒应用会不定期更新。若出现错误， **请更新到最新版本。**
*** ### 故障排查
出现“无法连接到服务器”错误（Android） 在 \`granite.config.ts\` 的 \`web.commands\` 中添加 \`--host\` 后运行服务，以确认主机地址。 ```ts web: { commands: { dev: 'vite --host', // 添加 --host build: 'tsc -b && vite build', }, }, ``` 确认主机地址后 `web.host`请输入。 ```ts web: { host: 'x.x.x.x', // 服务运行的主机地址 }, ```
Metro 开发服务器已打开，但显示“暂时出了点问题”消息 可能是未正确连接开发服务器。请断开 \`adb\` 连接，并重新连接 8081、5173 端口。
在 PC Web 上出现 Not Found 错误 8081 端口是用于在沙盒内识别的端口。在 PC Web 上会出现 Not Found 错误。
--- # 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-zh/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.