开始使用

只按顺序整理了安装 SDK 并启动第一个构建所需的内容。

使用 Apps in Toss Unity SDK，无需单独配置 Vite 项目或实现 JS Bridge，就能将 Unity 项目移植为迷你应用。加载界面已默认包含在 SDK 中，首次交互耗时、帧停顿、错误·异常、内存警告等运行时事件会在无需用户代码的情况下自动收集（详情请参见 SDK 事件日志记录 注）。

安装 SDK

通过 Package Manager 安装

1. 在 Unity Editor 中 Window > Package Manager 打开
2. 左上角 + 点击按钮
3. Add package from git URL... 选择
4. 输入 Git URL：

https://github.com/toss/apps-in-toss-unity-sdk.git#release/v3.0.3

直接修改 manifest.json

项目的 Packages/manifest.json中添加依赖。

{
  "dependencies": {
    "im.toss.apps-in-toss-unity-sdk": "https://github.com/toss/apps-in-toss-unity-sdk.git#release/v3.0.3"
  }
}

支持的 Unity 版本

至少需要 Unity 2021.3，建议使用 Unity 6 及以上。支持 2021.3 之后的所有版本。

SDK 组成

Apps in Toss Unity SDK 提供了两个层级，以便在 WebGL 环境中使用平台 API。

• C# API 层 (Runtime/SDK/）—— AIT.* 将平台 API 封装成 C# 方法的形式。内部通过 DllImport("__Internal")在 WebGL 构建时与 JS 函数连接。
• JS Bridge (.jslib) — 在此定义了供 C# 调用的 JS 函数，真正与 Apps in Toss WebView SDK 通信的逻辑都在这里。

这两个层级都已包含在 SDK 中，无需自行编写代码。

安装 ref 管理

URL 末尾的 #... 部分 安装 ref。UPM 会原样获取这个 ref 指向的提交，因此这里写什么，就等于决定了“何时以及如何更新”。

选择 ref

ref 形式	示例	行为
不可变发布标签	#release/vX.Y.Z	永久固定到特定提交。保证可复现构建，并隔离于非预期更新之外
分支	#main	每当 HEAD 变动时，自动更新程序会检测变更并显示更新提示
预发布渠道	#beta, #beta-perf	会移动的分支。不会弹出自动更新提示，需要手动管理

推荐：服务部署请使用不可变发布标签。可用标签为 GitHub Releases中查看。

预发布渠道仅面向事先约定的试点对象提供。 Beta 渠道与 perf Beta 渠道。

将会移动的 ref 重新拉取到最新

UPM 会将 git 依赖锁定为 Packages/packages-lock.json中 提交哈希。 所以 #main即使像这样固定到会移动的 ref，只要重新打开 Unity 也不会更新。必须通过下面两种方式之一解除锁定。

• 在 Package Manager 中移除后重新添加 — 删除该包并用相同 URL 再次添加，ref 就会重新解析。最简单。
• 解除锁定 — Packages/packages-lock.json中 im.toss.apps-in-toss-unity-sdk 条目的 "hash" 值并保存后，Unity 会重新解析 ref。

切换到其他 ref

Packages/manifest.json中只需更改 URL 的 fragment 并保存。只要依赖字符串发生变化，UPM 就会从头重新 resolve 包，因此这种情况下无需使用上述解除锁定。

• 试点参与： #release/vX.Y.Z → #beta 或 #beta-perf
• 回到 stable： #beta → #release/vX.Y.Z

切回不可变发布标签后，自动更新程序会再次跟踪该 stable ref。

设置

安装 SDK 后，在 Unity Editor 菜单中 AIT > Configuration点击打开设置窗口。

设置	说明
应用 ID	从 Apps in Toss 平台获取的应用 ID。只能使用英文字母、数字和连字符，是设置窗口中 *显示的唯一必填项
显示名称	将在加载界面上显示的应用名称
版本	x.y.z 格式
基础颜色	品牌色。用于进度条等
图标 URL	将作为迷你应用图标显示的图片 URL。若输入， http:// 或 https://必须以

AIT 菜单

SDK 安装完成后，Unity Editor 顶部会新增 AIT 菜单。

菜单	说明
开发服务器	下面有 Start / Stop / Restart Server / Restart Server (server-only) 。 server-only表示只重启服务器而无需重新构建
Production Server	下面有 Start / Stop / Restart Server / Restart Server (server-only) 。 server-only表示只重启服务器而无需重新构建
构建并打包	WebGL 构建和 .ait 打包会一次性执行
Publish	生成的 .ait 文件上传到 Apps in Toss 平台。 Configuration中必须设置部署密钥
清理	webgl/, ait-build/ 删除构建产物文件夹
打开构建输出	打开保存构建产物的文件夹
重置加载界面	将加载界面恢复为 SDK 默认模板。详情请参见 加载画面自定义 参考
Configuration	打开迷你应用联动设置窗口，如应用 ID、显示名称等
Install Sentry SDK	安装 Sentry Unity SDK。详情请参见 Sentry 集成 参考
提交问题	打开提交问题情况的窗口
Check for Updates...	手动检查是否有新的 SDK 发布
Debug	汇集了用于调试的子菜单，如 SDK 状态初始化、WebGL 模板强制刷新等

Dev Server 与 Production Server，以及各构建配置的 devtools·压缩设置差异，请参见 构建配置文件已整理在其中。

第一次构建

所有构建入口都在 AIT 菜单中。各入口分别如何以何种方式构建，请参见 构建配置文件已整理在其中。

通过开发服务器确认

在开发阶段使用 Dev Server。 @apps-in-toss/devtoolsMock SDK 和面板会一同运行，无需 toss 应用即可在浏览器中通过 mock 验证平台 API 调用，并且可以在面板中直接控制 mock 状态。

1. AIT > 开发服务器 > Start Server 点击
2. Unity WebGL 构建会自动执行
3. 构建完成后，本地开发服务器会启动
4. 浏览器会自动打开，或访问控制台中显示的 URL

制作发布包

1. AIT > 构建并打包 点击
2. 构建完成后， ait-build/dist/中查看结果物

在真机上确认（Deploy Test）

若要在真机上确认无法通过浏览器 Mock 检查的实际 Toss 应用环境（摄像头、支付、广告等），请使用 Deploy (Test)。

1. AIT > Deploy (Test) 点击
2. 需要已设置部署密钥。 AIT > Configuration中输入
3. 增量构建后 ait deploy会部署到控制台 QR 测试环境（memo 中 [Test] 前缀会自动添加）
4. 部署完成后，在弹出的窗口中用 Toss App 扫描 QR，或通过 URL 访问后在真机上确认

发布到平台（Deploy Production）

若要面向真实用户展示，请先用干净构建重新部署，然后在控制台申请审核。

1. AIT > Deploy (Production) 点击（与 Deploy (Test) 相同，但使用干净构建 + memo [Production] 前缀）
2. 部署完成后，在弹出的窗口中点击“打开控制台”按钮，跳转到 Apps in Toss 控制台
3. 在控制台中对刚刚部署的构建申请审核/发布 — ait deploy 本身只会始终部署到控制台 QR 测试环境，真正发布只能通过这个控制台流程完成

SDK 使用示例

SDK API 使用 async/await 模式。 Awaitable与 Task 返回的是其中哪个、超时和错误代码如何处理，请参见 API 使用模式已整理在其中。

查询设备信息

using AppsInToss;
using UnityEngine;

public class GameManager : MonoBehaviour
{
    async void Start()
    {
        try
        {
            // 设备 ID 查询
            string deviceId = await AIT.GetDeviceId();
            Debug.Log($"设备 ID: {deviceId}");

            // 平台 OS 查询
            string os = await AIT.GetPlatformOS();
            Debug.Log($"平台: {os}");

            // 网络状态确认
            NetworkStatus status = await AIT.GetNetworkStatus();
            Debug.Log($"网络: {status}");
        }
        catch (AITException ex)
        {
            Debug.LogError($"API 调用失败：{ex.Message} (code: {ex.ErrorCode})");
        }
    }
}

支付请求

using AppsInToss;
using UnityEngine;
using System.Threading.Tasks;

public class PaymentManager : MonoBehaviour
{
    public async Task RequestPayment()
    {
        try
        {
            var options = new CheckoutPaymentOptions {
                PayToken = "your-pay-token"
            };

            CheckoutPaymentResult result = await AIT.CheckoutPayment(options);
            Debug.Log($"支付成功：{result.Success}");
        }
        catch (AITException ex)
        {
            Debug.LogError($"支付失败：{ex.Message}");
        }
    }
}

重要：应用内支付必须指定支付批准回调。若不指定，所有支付都会被视为支付失败。 API 使用模式请先阅读 的应用内支付部分。

触觉反馈

using AppsInToss;
using UnityEngine;

public class FeedbackManager : MonoBehaviour
{
    public async void VibrateDevice()
    {
        try
        {
            var options = new HapticFeedbackOptions {
                Type = HapticFeedbackType.Tap
            };

            await AIT.GenerateHapticFeedback(options);
            Debug.Log("已生成触觉反馈");
        }
        catch (AITException ex)
        {
            Debug.LogError($"触觉反馈失败: {ex.Message}");
        }
    }
}

测试

SDK API 只有在 WebGL 构建中才会真正通过桥接调用，而且即便如此，也大多只能在 Apps in Toss 应用环境中正常工作。Unity Editor 中只会返回 Editor mock 的默认值。详情请参见 API 使用模式中 Mock 部分。

使用沙箱应用确认本地构建的步骤，请参见 问题排查 文档中的“Dev Server 能用但 Production 不行”一节。

在最终上线前的验证中， .ait 使用文件上传测试。

1. AIT > 构建并打包以 .ait 创建文件。
2. Apps in Toss 控制台上传到。
3. 通过 QR 码运行迷你应用进行确认。

如果遇到卡住的地方， 问题排查 文档。

相关文档

• API 使用模式 — async/await、错误处理、Mock
• 构建配置文件 — 各构建入口的配置差异
• 构建自定义 — 修改 Web 入口、添加外部库
• 加载画面自定义 — 替换加载画面
• 问题排查 — 常见卡点与解决方法