集成

Apps in Toss 小程序 基于 Web运行。若要把 Unity 游戏做成小程序，需要将项目 构建为 WebGL。通过 WebGL 构建，Unity 游戏会转换为可在浏览器中运行的形式，并可在 Apps in Toss 环境中作为小程序提供。

仅为 Unity 提供的 Apps in Toss Unity 包安装后，无需配置 Vite 项目或实现 JS Bridge，即可一次性处理从 WebGL 构建到小程序打包的全部流程。

---

为什么需要使用 Apps in Toss Unity SDK

使用 Apps in Toss Unity 包可以获得以下优势。

• 更短的移植周期：可以在无需单独配置 Vite 项目或实现 JS Bridge 的情况下，轻松快速地将 Unity 开发的游戏移植为 Apps in Toss 小程序。
• 更高的稳定性与用户体验：将加载时间缩短到 1/5 左右，提高小程序稳定性，并为用户提供更好的体验。
• 查看更多性能指标：可查看更丰富的游戏性能指标，如崩溃率、加载时间、FPS 等。
• 内置加载界面：加载界面已默认包含在 SDK 中，因此合作方无需另外配置加载界面。

实际应用案例：某款游戏在使用手动移植方式时，加载时间长达约 20 秒，导致用户流失严重，CS 咨询也激增。

切换到 Unity SDK 后，加载时间 1 秒，这个问题得到了大幅改善。

---

什么是 SDK 接入？

SDK 接入是指在 Unity 内自动处理 Apps in Toss 接入所需流程的方式。

• 用于 WebView SDK 接入的 JS Bridge已默认包含。
• 在 Unity 中 用 C# 代码调用 Apps in Toss API即可直接调用。
• 从 WebGL 构建到 .ait 文件生成都能一次性自动化。
• 崩溃率、加载时间、FPS 等游戏性能指标会自动收集。

如果用 Unity 开发小程序，建议以 Apps in Toss 提供的 Unity SDK 为基准进行开发。

手动接入

如果不使用 Apps in Toss Unity 包，而需要自己配置 WebGL 构建或实现 JS Bridge， 手动接入指南请参考。

---

安装 SDK

方法 1：Package Manager（推荐）

1. 在 Unity Editor 中 Window > Package Manager打开它。
2. 左上角 + 按钮，然后点击 Add package from git URL...。
3. 输入 Git URL 后 Install并安装。

https://github.com/toss/apps-in-toss-unity-sdk.git

版本锁定

如果要锁定特定版本， #release/v2.4.5请像这样使用 release 标签。发布列表请参见 GitHub Releases可在其中确认。

方法 2：直接修改 manifest.json

项目的 Packages/manifest.json 文件中也可以直接添加：

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

支持的 Unity 版本

• 最低版本: Unity 2021.3
• 推荐版本: Unity 6 及以上
• 支持 Unity 2021.3 之后的所有版本。

确认安装完成

如果安装正常完成：

• 在 Package Manager 列表中 AppsInToss SDK会显示出来。
• 在 Unity 菜单顶部 AIT 会新增一个项。
• Packages/Apps In Toss SDK/Runtime/SDK 路径下会 AIT.*.cs 文件被创建。

---

包组件

Apps in Toss Unity 包为了让你在 WebGL 环境中使用 Apps in Toss SDK， C# API 层和 JavaScript Bridge（.jslib） 这两部分一起提供。

C# API 封装层

这是一个提供给 Unity C# 代码直接调用 Apps in Toss 功能的 API。

• 将 Apps in Toss API 封装成 C# 方法，使用更方便。
• 内部通过 DllImport("__Internal")在 WebGL 构建时与 JS 函数连接。
• 无需单独编写 JavaScript，仅用 C# 代码即可接入 Apps in Toss。

JavaScript Bridge（.jslib）

.jslib 文件是在 Unity WebGL 环境中连接 C# 和 JavaScript 的桥梁。

• C# 中调用的 JS 函数都定义在这个文件里。
• 实际与 Apps in Toss WebView SDK 通信的逻辑也在这里处理。
• 还支持 JS → C# 调用，可构建双向消息传递结构。

---

AIT 菜单

安装 Apps in Toss Unity 包后，Unity Editor 顶部会新增 AIT 菜单。通过这个菜单，可以使用 WebGL 构建、打包、运行测试服务器等接入过程中所需的大部分功能。

菜单	说明
开发服务器	运行开发测试服务器。Mock 桥接已启用，可在本地浏览器中测试。
Production Server	使用生产环境设置运行本地服务器。可以进行与实际部署环境相似的测试。
构建并打包	WebGL 构建 + .ait 打包一次性完成。是最常用的选项。
Publish	.ait 将文件上传到 Apps in Toss 控制台。需要在 Configuration 中注册部署密钥。
清理	删除之前的构建产物。
打开构建输出	直接打开保存构建产物的文件夹。
Configuration	设置与 Apps in Toss 小程序接入相关的构建选项。
调试	可以查看日志或检查内部状态。

---

设置

安装 SDK 后，在 Unity Editor 菜单中 AIT > Configuration点击即可打开设置面板。

必填设置

设置	说明
应用 ID	在 Apps in Toss 控制台中注册的 appName必须相同
应用图标 URL	将显示为小程序图标的图片 URL（必填）
显示名称	将在加载界面上显示的应用名称
基础颜色	品牌色（用于进度条等）

• 应用 ID必须与在 Apps in Toss 控制台中注册的 appName相同。
• 图标在测试阶段可以不填，但正式发布时必须注册。
• 服务器设置中的 Granite、Vite 相关项在沙盒应用测试时使用。

请参考构建配置文档，了解各构建选项的详细设置。

---

第一次构建

1. 确认设置

1. AIT > Configuration 在菜单中确认设置。
2. 应用图标 URL请确认已填写（必填）。

2. 运行开发服务器

在开发阶段使用 Dev Server 模式：

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

3. 生产构建

若要生成发布构建：

1. AIT > 构建并打包 菜单。
2. 构建完成后 ait-build/dist/ 可以在文件夹中查看产物。

4. 发布

若要发布到 Apps in Toss 平台：

1. AIT > Publish 菜单。
2. 需要先设置部署密钥（在 Configuration 中设置）。

---

使用 SDK

安装 Apps in Toss Unity SDK 后，就可以在 C# 代码中直接 AIT.* 调用 API。无需自己编写 JS Bridge，仅用 Unity 代码即可使用 Apps in Toss 的各种功能。

Apps in Toss API 大多以异步（async）方式运行：

var result = await AIT.SomeApi(options);

• 成功时会返回对应 API 的结果模型。
• 失败时 继承自 AITException，因此现有的可能会发生异常，需要进行异常处理。

可在 Apps in Toss SDK 参考文档中查看全部可用的 AIT API 列表。WebView SDK 的 getDeviceId在 Unity SDK 中 AIT.GetDeviceId()像这样以 PascalCase 调用。

详细用法请参考 API 使用模式文档。

示例

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

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

            // 平台 OS 查询
            PlatformOS 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.Code})");
        }
    }

    // 触觉反馈示例
    public async void VibrateDevice()
    {
        try
        {
            var options = new GenerateHapticFeedbackOptions {
                style = "medium"
            };

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

查看示例代码

下面这些文件是用于 E2E 测试的示例代码，可查看应用内广告 / 应用内支付的实际使用方式。

• 应用内广告示例
• 应用内支付示例

---

测试

Apps in Toss AIT API 在普通浏览器环境中无法运行。 只有在 Apps in Toss 运行环境中才能使用该功能。

可测试的环境有两种：

1. 在沙盒应用中测试

这是为开发中功能验证提供的测试应用。可以运行 Unity WebGL 构建，并确认 AIT API 是否正常连接。

• 下载沙盒应用

2. 上传 .ait 文件后进行测试

1. 在 AIT 菜单中 构建并打包以 .ait 生成文件。
2. Apps in Toss 控制台上传到其中。
3. 通过二维码运行小程序。

详细方法请参考《在 Toss App 中测试》文档。