Unity项目接入抖音小游戏

在字节系 App 运行 Unity WebGL导出的 wasm 方案

1. 游戏接入判断

Unity版本： 2022.3.62f3c1（最稳定）

1.1 游戏包体大小改造

抖音小游戏随视频分发，尽量减少包体大小缩短加载时间，避免取消率过高。

Unity小包化方案：

• AB包按需下载
• Addressable Asset System
• Unity AutoStreaming方案

1.2 功能项评估及打包限制

游戏功能支持情况：

支持：

• Unity基础模块（动画、物理、AI、UI、音频）
• 渲染管线与接口
• 资源（Addressable、AssetBundle）加载
• Lua 脚本
• PureTS

限制：

• 网络系统：不支持 System.Net 接口，HTTP 使用 UnityWebRequest，WebSocket 信替代(如开源的 UnityWebSocket 插件)，UDP/TCP使用TT SDK适配
• 多线程：不支持多线程，使用异步代替
• 文件系统：目前支持 System.File，后续会禁止使用。应使用抖音小游戏 TT SDK 实现文件存储，大小限制为最大1G，适配插件已实现资源的自动缓存与更新
• 第三方插件：支持大部分插件，C#插件与非平台相关的C原生插件（源码方式存在），不支持非托管类型（C++编译）dll/so。项目依赖的必要插件有 Android/iOS 平台相关插件或 so/framework 原生插件，无法转换

1.3 打包调优

WebGL方案： 首包包体需小于100M

优秀数据参考：

• Native:包体20M WebGL:包体10M

WebGL方案调优：

• 使用分包工具，优化首包大小的 Wasm 分包工具
• 使用 ASTC 纹理压缩
• AB包加载，尽可能早使用Unload

2. 项目测试验证

2.1 打包发布流程

Step1. 抖音开发者平台申请获取 AppId

Step2. 安装准备

1. 抖音开发者工具
2. 面向字节平台打包工具（BGDT）

Bytegame -> ByteGameDevelop -> 安装 TTSDK

Step3. 打开Unity项目切换WebGL平台（Html5）

File -> BuildSetting -> WebGL -> Swicth platform -> Scenes in Build

WebGL功能支持限制

• 多线程：不支持，改用异步实现
• 第三方插件：不支持非托管类型
• 热更：不支持
• 网络：不支持System.Net接口
  • HTTP：使用 UnityWebRequest。
  • TCP：需替换成 WebSocket。可以使用 UnityWebSocket。
  • UDP：需替换成 StarkSDK 提供的接口。

Step4. 接入字节平台SDK（放在下一部分，测试验证先删除接入SDK相关）

Step5. 打包调试验证

注意

• 安全性考虑，不允许在项目中加入原生 Java 代码库
  构建工具入口： Bytegame -> TTSDK Tools -> Build Tool

配置项	说明
运行框架选择	WebGL
游戏AppId	开发者平台获取唯一ID
DebugSymbols	开发时选 External 或 Embedded，发布时通常关掉或使用外部保留符号文件
构建选项选择	与 Unity 提供的 BuildOption 选项一致，无特殊需求选择None即可
WebGL输出目录	最终构建文件的输出路径
是否采用旧格式打包	旧格式为zip压缩包，新包体格式：平台统一的小游戏服务链路，支持所有引擎类型 - 旧包体格式：主要产物内容在zip包文件中，game.json以及project.config.json负责项目相关配置 - 新包体格式：产物内容以及game.json,project.config.json 在同一文件目录中。其格式与普通小游戏类似 - 旧包体后续可能不在维护，建议使用新包体格式（非抖音系APP不兼容）
UnityHeap	设置WebAssembly的初始内存的大小
音频资源url	开发者在使用音频时如若出现问题可尝试此方案。为游戏资源CDN url前缀，目前主要是用在播放网络音频url文件时会用到。 - 仅支持wav、mp3、m4a、aac格式
复制音频文件	是否将工程中的音频文件复制出来。如果勾选，在构建WebGL成功后，会自动将工程中的音频文件复制到WebGL输出目录下的名为Assets子目录中。可以直接将该目录上传到CDN上
WebGL2（beta）	WebGL2.0
IOS高性能加模式	针对 iOS 的特殊优化模式（影响内存/线程/渲染行为），需要测试后开启以免兼容性问题。
Brotli压缩	使用Brotli压缩，可以将包体减小，但是打包速度会有所下降。未经过压缩的包只能用于发布测试版本，正式上线需勾选，否则会影响线上加载效率。
Profiling	是否在构建中保留性能分析信息。仅用于调试/分析，开启会增加包体与运行开销
预下载选项	- 文件列表：指定需要在启动前预下载的文件（manifest或关键资源） - 游戏资源CDN：指定游戏资源的 CDN 基地址 - 动态资源列表接口：输入一个后端 API 接口地址，运行时会请求该接口获取需要动态预下载的资源清单
ClearStreamingAssets	构建前是否清空项目 StreamingAssets
缓存资源域名	列出允许/推荐用于长期缓存资源的域名或 CDN 域
不缓存的文件	列出不应被长期缓存的文件
开发者工具路径	抖音开发者路径
调试流程：

构建WebGL -> …等待… -> 开发者工具发布（手机抖音扫码调试） -> 工程配置 -> Android WebGL

Step6. 发布上线运营（TODO）

3. 接入字节平台SDK

Step1. 申请开发者平台账号注册游戏选定引擎

Step2. 接入SDK

抖音 Unity 小游戏提供的 C# SDK 由原来的 StarkSDK.API 升级为 TT 的调用形式

TTSDK 使用指南（Unity）

本文档聚焦于在 Unity 项目中直接使用 TTSDK（抖音/字节跳动小游戏平台）的常用能力与示例，不包含旧版 StarkSDK 的迁移说明。

3.1 概览

• 目标： 在 Unity 中调用平台能力（初始化、登录/鉴权、存档、埋点、广告、IAP、传感器、网络等）。
• 前提： 已在抖音开放平台创建应用并获取 AppId；服务端具备与平台交互的能力（用于 token 交换、支付验签等）。

3.2. TTSDK 详细接入操作

3.2.1 获取 SDK 资源

下载渠道

• 访问抖音开放平台开发者工具页面
• 选择与项目Unity版本兼容的最新TTSDK版本
• 下载包含Unity Package、Android AAR、iOS Framework的完整SDK包

验证下载

• 检查下载文件是否包含所有必需组件
• 确认文件大小和完整性
• 记录SDK版本号以便问题排查

3.2.2 集成到 Unity 项目

导入SDK包

• 打开Unity项目
• 点击Assets菜单，选择Import Package下的Custom Package选项
• 选择下载的TTSDK .unitypackage文件
• 在弹出的导入窗口中确认所有文件都被选中
• 点击Import按钮完成导入

配置项目结构

• 确认Assets/Plugins/Android目录存在并包含AAR文件
• 确认iOS相关文件已正确放置
• 检查是否有任何导入错误或警告信息

验证集成结果

• 在Unity控制台查看是否有TTSDK相关的导入信息
• 尝试在脚本中引用TTSDK命名空间
• 运行项目检查是否出现编译错误

3.2.3 快速开始

1. 从平台或内部仓库获取官方 Unity 插件与原生库（Android AAR、iOS framework/Pod）。
2. 将 AAR 放入 Assets/Plugins/Android，将 iOS framework/Pod 集成到 Xcode/Podfile。
3. 在 Unity 中创建一个 TTSDKManager（单例）封装初始化、登录、回调处理与平台差异。

3.3 TTSDKManager 创建步骤

1. 在Unity项目中创建TTSDKManager.cs脚本文件

using System;
using UnityEngine;
// 添加TTSDK命名空间引用
using TTSDK; // 步骤3：引用TTSDK命名空间

public class TTSDKManager : MonoBehaviour {
    // 单例模式实现，确保全局唯一实例
    public static TTSDKManager Instance { get; private set; }

    // 在Inspector中配置的AppId参数
    [Header("抖音小游戏配置")]
    [SerializeField] private string appId = "your_app_id_here";

    // 在Awake方法中初始化SDK管理器，确保单例模式
    void Awake() {
        if (Instance == null) {
            Instance = this;
            DontDestroyOnLoad(gameObject); // 跨场景保持
            InitializeTTSDK(); // 初始化TTSDK
        } else {
            Destroy(gameObject); // 销毁重复实例
        }
    }

    // 步骤5：实现Init方法调用TT.InitSDK进行初始化
    public void InitSDK() {
        try {
            TT.InitSDK((int code, string msg) => {
                if (code == 0) {
                    Debug.Log("TTSDK 初始化成功");
                    // 初始化成功后的处理
                } else {
                    Debug.LogError($"TTSDK 初始化失败: {code}, {msg}");
                    // 处理初始化失败的情况
                }
            });
        } catch (Exception e) {
            Debug.LogError($"TTSDK 初始化异常: {e.Message}");
        }
    }

    // 步骤6：实现Login方法调用TT.Login进行用户登录
    public void Login(Action<bool, string> callback) {
        TT.Login((string resultJson) => {
            try {
                // 解析登录结果JSON
                var result = JsonUtility.FromJson<LoginResult>(resultJson);
                if (result.code == 0) {
                    callback?.Invoke(true, result.openId); // 登录成功
                } else {
                    callback?.Invoke(false, result.msg); // 登录失败
                }
            } catch (Exception e) {
                callback?.Invoke(false, $"解析失败: {e.Message}");
            }
        });
    }

    // 步骤7：添加数据保存和读取方法
    public void SaveData(string key, string jsonData, Action<bool> callback) {
        TT.Save(key, jsonData, (bool success) => {
            callback?.Invoke(success);
        });
    }

    public string LoadData(string key) {
        return TT.LoadSaving(key);
    }

    // 获取SDK版本信息
    public string GetSDKVersion() {
        return TT.TTSDKVersion;
    }
}

// 登录结果数据结构
[Serializable]
public class LoginResult {
    public int code;      // 返回码，0表示成功
    public string msg;    // 错误信息
    public string openId; // 用户OpenID
    public string token;  // 访问令牌
}

3.4 主要能力与示例

初始化与版本

• 初始化：调用TT.InitSDK方法，传入回调函数处理初始化结果
• 版本：通过TT.TTSDKVersion获取SDK版本，通过TT.GetTTContainerVersion获取容器版本

登录 / 鉴权

• 发起登录：调用TT.Login方法，传入回调函数获取临时凭证
• 要点：将授权码/临时token发到后端，后端用AppSecret跟平台换取长期凭证并进行用户校验

存档 / 数据保存

• 保存：调用TT.Save方法，传入存档槽位名称、JSON数据和保存结果回调
• 读取：调用TT.LoadSaving方法，传入存档槽位名称获取JSON数据
• 清理：调用TT.ClearAllSavings清空所有存档，TT.GetSavingDiskSize获取已用存储空间

埋点 / 分析

调用TT.ReportAnalytics方法，传入事件名称和包含事件参数的字典对象

广告

调用TT.LoadRewardAd加载激励广告，TT.ShowRewardAd显示激励广告，注意处理回调、失败和重复展示防护

IAP（支付）要点

• 流程：客户端请求后端下单 -> 后端与平台交互生成签名/参数 -> 客户端调用 TT 支付 -> 支付结果回传后端二次校验 -> 发货。
• 所有验签与金额校验必须在服务端完成。

网络 / UDP / WebSocket（WebGL）

• 在 WebGL 环境，优先使用 TT 提供的封装接口（CreateUDPSocket / Send / OnMessage 等），并在目标运行环境测试行为。

设备能力

• 震动：TT.Vibrate(...)
• 剪贴板：TT.SetClipboardData(...) / TT.GetClipboardData()
• 陀螺仪 / 加速度：TT.StartGyroscope(...) / TT.StartAccelerometer(...)

音频与播放

• 优先使用 Unity AudioSource；平台音频接口用于获取或播放平台托管音频文件。

调试

• 开启内置Toast：调用TT.EnableTTSDKDebugToast传入true开启调试提示
• 注册命令事件：调用TT.RegisterCommandEvent注册调试命令监听器

3.5 Android / iOS 简要配置片段

Android 配置

在AndroidManifest.xml中添加网络权限和TTActivity配置

iOS 配置

在Info.plist中添加相机、麦克风权限描述和URL Scheme配置

3.6 安全与最佳实践

• 切勿在客户端保存 AppSecret 或私钥；服务端负责 token 交换、验签与敏感调用。
• 关键回调与支付结果需要幂等与重试保护。
• 上线前在目标设备/网络环境充分测试（WebGL、WebGL2、Brotli、CDN、跨域、Heap 大小等）。

3.7 参考

• 官方 TTSDK 迁移与 API 文档
• C#SDK接入文档