> 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). # 测试应用（沙盒） ## 测试应用（沙盒） App in Toss 不会单独提供用于开发的 Toss 应用。相反， **专用沙盒应用**可通过它来构建开发·测试环境。 {% hint style="info" %} **请务必确认** 在正式服务上线前，必须在沙盒应用中完成功能验证。即使已在沙盒应用中完成测试，如果在上线审核中发现违反指南的内容，也可能被驳回。 目前 3.x 版本不提供沙盒应用。相反，可以通过同时安装的 devtools 在浏览器中进行开发。 {% endhint %} *** ### 什么是沙盒应用？ App 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 会被完全阻止**。如果在非 App in Toss 域名的合作伙伴域名中实现基于 Cookie 的登录，将无法正常工作。 **请使用基于令牌等替代认证方式**。 {% 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`要使用 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 Name 设置] 的顺序进行即可完成模拟器设置。 新增的模拟器可在 \[Virtual Device Manager] 中点击播放按钮运行。 *** ### 2. 安装沙盒应用 沙盒应用会不时更新。若看到错误， **更新到最新版本**。 | 分类 | 构建号 | 下载 | | ------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------- | | 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 | | | 二维码链接: 샌드박스/id6745618667 | | | | | | | #### 在 iOS 上安装 **模拟器** 将下载的沙盒应用文件 **拖放到模拟器界面**。安装完成后，应用会显示在模拟器主屏幕上。请稍等至安装完成。 **真机** 请通过上表中的二维码在应用商店安装。 #### 在 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. 点击“打开 Schema”按钮。 4. 在屏幕顶部 `Bundling {n}%...`出现时即连接成功。
手动允许“本地网络”权限的方法 1. 在 iPhone 的 \[设置] 应用中 **“App 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 {设备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 命令 ```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 网页上出现 Not Found 错误 8081 端口是用于在沙盒内识别的端口。在 PC 网页上会出现 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.