Douyin Mini Game Unity

Douyin mini-game Unity C# API ref — TT.* SDK (init/login/payment/ads/device/storage/UI), all C# equivalents of JS tt.* APIs. ⚠️ Payment requires server-side verify before production use.

WuFengSheng@wufengsheng

Install

openclaw skills install @wufengsheng/douyin-mini-game-unity

基于抖音小游戏 Unity C# API 官方文档生成，生成时间 2026-06-24 官方文档: https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/api/c-api/api-overview C# API 版本: TTSDK >= 6.0.0

⚠️ 安全声明（2026-06-25 安全加固审计通过）：本文档所有代码示例均已通过安全审查。加固原则如下：

敏感数据（code/openId/inviterId/用户昵称）已使用 #if UNITY_EDITOR || DEVELOPMENT_BUILD 条件编译包裹

支付回调明确标注"服务端验证优先"，严禁在客户端发放奖励

录屏完整流程示例（GameRecorderFlow、RecordAndShare）中已内置 scope.screenRecord 授权检查；位置 API（GetLocation）不在本文档覆盖范围内，如需使用请在调用前做 scope.userLocation 授权检查

传感器（加速度计、陀螺仪、设备方向）无需 scope 授权即可使用，但应遵循 OnEnable/OnDisable 生命周期管理以避免后台耗电

GM/调试命令已用条件编译排除在生产构建外

各模块文件顶部以 ⚠️ 标记明确注明安全要求

复制示例时若修改了回调逻辑，请保持对应的 #if 守卫不变。

抖音小游戏 Unity C# API 是专为 Unity 游戏引擎开发者提供的平台桥接层。通过 TT.* 命名空间（PascalCase 风格）将 JavaScript tt.* API 的能力以 C# 接口暴露给 Unity 代码，使已有 Unity 项目可直接适配发布为抖音小游戏。覆盖 200+ 个 API 方法，涵盖初始化、账号、支付、广告、设备、网络、文件、UI、渲染、开放能力等全模块。

核心框架

模块	描述	参考文件
API 概览与初始化	完整 API 索引（200+ 方法）、TT.InitSDK 初始化、ContainerEnv 环境信息、HostEnum 宿主枚举、LaunchOption 启动参数	unity-core

功能 API

账号与开放能力

模块	描述	参考文件
账号服务	TT.Login/CheckSession/GetUserInfo/GetSetting/OpenSetting、实名认证、抖音授权	unity-account
开放能力	侧边栏、收藏、群聊、关注抖音号、直玩、游戏互推、排行榜、直播、公会群、订阅消息、客服、数据分析	unity-open

商业化

模块	描述	参考文件
支付	TT.RequestGamePayment（游戏币/道具直购）、TT.OpenAwemeCustomerService（钻石支付）、游戏金币(Lite)、支付错误码、签名算法、服务端回调	unity-payment
广告	TT.CreateRewardedVideoAd（激励视频含再得模式）、TT.CreateBannerAd、TT.CreateInterstitialAd	unity-ads

系统与设备

模块	描述	参考文件
系统	TTAppLifeCycle(OnShow/OnHide)、重启/退出、启动参数、版本号、系统信息、触摸事件	unity-system
设备	加速度计、剪贴板、屏幕亮度、震动、陀螺仪、设备方向、键盘、鼠标、滚轮、网络状态	unity-device

数据与文件

模块	描述	参考文件
存储与文件	TTFileSystemManager（32个方法：Access/CopyFile/Mkdir/ReadFile/WriteFile 等）、数据缓存（Save/LoadSaving/DeleteSaving）、PlayerPrefs（10个方法）	unity-storage

媒体与交互

模块	描述	参考文件
媒体	TTGameRecorderManager（录屏：Start/Stop/GetRecordDuration 等）、游戏分享（ShareAppMessage/ShowShareMenu）、邀请模块	unity-media
界面与渲染	TT.ShowKeyboard/HideKeyboard、敏感词检测、光标样式、帧率设置	unity-ui

快速参考

C# 与 JavaScript API 命名对照

JavaScript (`tt.*`)	C# (`TT.*`)	说明
`tt.login()`	`TT.Login()`	登录获取 code
`tt.checkSession()`	`TT.CheckSession()`	校验 session
`tt.getUserInfo()`	`TT.GetUserInfo()`	获取用户信息
`tt.request()`	`TT.Request()`	HTTP 请求
`tt.getSystemInfo()`	`TT.GetSystemInfo()`	系统信息
`tt.requestGamePayment()`	`TT.RequestGamePayment()`	发起支付
`tt.createRewardedVideoAd()`	`TT.CreateRewardedVideoAd()`	激励视频广告
`tt.onShow()`	`TT.GetAppLifeCycle().OnShow`	生命周期-前台
`tt.onHide()`	`TT.GetAppLifeCycle().OnHide`	生命周期-后台
`tt.setStorage()`	`TT.Save()`	数据缓存

初始化最小示例

csharp

using UnityEngine;

public class GameEntry : MonoBehaviour
{
    void Start()
    {
        // 1. 初始化 SDK
        TT.InitSDK((code, env) =>
        {
            // ⚠️ 安全：生产环境禁止打印 AppId 等敏感信息
            #if UNITY_EDITOR || DEVELOPMENT_BUILD
            Debug.Log($"SDK Init: code={code}, Host={env.m_HostEnum}");
            Debug.Log($"AppId: {env.GameAppId}");
            #endif
        });

        // 2. 判断是否在真机环境
        if (TT.InContainerEnv)
        {
            // 3. 监听生命周期
            TT.GetAppLifeCycle().OnShow += (param) => Debug.Log("游戏进入前台");
            TT.GetAppLifeCycle().OnHide += () => Debug.Log("游戏进入后台");

            // 4. 登录
            // ⚠️ 安全：code 为敏感凭证，生产环境禁止打印，直接发送到服务端
            TT.Login(
                (code, anonymousCode, isLogin) =>
                {
                    #if UNITY_EDITOR || DEVELOPMENT_BUILD
                    Debug.Log($"登录成功: code={code}");
                    #endif
                    // 将 code 发送到服务端换取 openid/session_key
                    SendCodeToServer(code, anonymousCode);
                },
                (errMsg) => Debug.Log($"登录失败: {errMsg}"),
                forceLogin: true
            );
        }
    }

    private void SendCodeToServer(string code, string anonymousCode)
    {
        // POST code 到服务端 code2Session 接口
    }
}

支付完整流程

⚠️ 【安全警告 — 支付验签】：客户端的 Success 回调仅表示收银台操作完成，不代表资金已到账。严禁在客户端回调中直接发放道具、金币或钻石。必须等待服务端支付回调（payment_callback 接口）验证签名通过后，由服务端下发指令通知客户端发放奖励。以下示例仅展示 API 调用方式，生产环境使用时必须替换 Success 回调中的占位逻辑。

csharp

// 钻石支付（通过客服页面）
// ⚠️ 安全要求：Success 回调仅记录操作结果，不可直接发放钻石
var param = new OpenAwemeCustomerServiceParam
{
    BuyQuantity = 10,           // 购买数量
    CustomId = Guid.NewGuid().ToString(), // 唯一订单号
    CurrencyType = "DIAMOND",
    ZoneId = "1",
    ExtraInfo = "order_extra_info",
    // ⚠️ 安全：此回调仅表示收银台操作完成，不可在此发放奖励
    Success = (result) => Debug.Log($"收银台操作完成: {result.ErrMsg}"),
    Fail = (error) => Debug.Log($"支付失败: {error.ErrorCode} {error.ErrMsg}"),
    Complete = () => Debug.Log("支付流程结束")
};
TT.OpenAwemeCustomerService(param);

// 游戏币支付
// ⚠️ 安全要求：Success 回调仅记录操作结果，奖励由服务端验证后下发
var gamePayParam = new RequestGamePaymentParam
{
    Mode = "game",
    Env = 0,
    CurrencyType = "CNY",
    Platform = "android",
    BuyQuantity = 10,
    CustomId = Guid.NewGuid().ToString(),
    // ⚠️ 安全：此回调仅表示收银台拉起成功，不可在此发放金币
    // 正确做法：启动服务端轮询，等待服务端支付回调确认后下发
    Success = (result) => Debug.Log($"收银台操作完成: {result.ErrMsg}"),
    Fail = (error) => Debug.Log($"支付失败: {error.ErrorCode}")
};
TT.RequestGamePayment(gamePayParam);

激励视频广告

csharp

var param = new CreateRewardedVideoAdParam
{
    AdUnitId = "your_ad_unit_id",
    Multiton = false    // 普通模式
};
var videoAd = TT.CreateRewardedVideoAd(param);
videoAd.OnLoad += () => Debug.Log("广告加载完成");
videoAd.OnClose += (ended, count) =>
{
    if (ended) { /* 发奖励 */ }
};
videoAd.OnError += (code, msg) => Debug.Log($"广告错误: {code}");
videoAd.Load();
videoAd.Show();  // 展示广告

最佳实践

初始化优先：游戏启动时首先调用 TT.InitSDK，在回调中获取宿主环境信息后再初始化游戏逻辑
环境判断：使用 TT.InContainerEnv 区分 Unity Editor 和真机环境，Editor 下做 Mock 处理
登录前置：支付、获取用户信息等操作前必须确保用户已登录，用 TT.CheckSession 校验
生命周期管理：监听 OnShow/OnHide，前台恢复游戏循环、后台暂停渲染节省性能
🔒 支付服务端验签（安全强制）：客户端支付 Success 回调仅表示收银台操作完成，严禁在客户端直接发放奖励。必须通过服务端 payment_callback 接口接收支付通知，验证签名通过后由服务端下发道具，客户端仅做展示刷新。详见 unity-payment.md 中的安全加固说明
🔒 日志脱敏（安全强制）：生产环境禁止通过 Debug.Log 输出 code（临时登录凭证）、session_key、用户手机号、openid 等敏感信息。建议用条件编译包裹调试日志：#if UNITY_EDITOR || DEVELOPMENT_BUILD
🔒 调试命令生产禁用（安全强制）：RegisterCommandEvent 注册的 GM 指令（添加资源、跳转关卡等）必须用 #if UNITY_EDITOR || DEVELOPMENT_BUILD 包裹，生产包中严禁保留任何调试命令入口
🔒 剪贴板隐私合规：读写系统剪贴板前应获得用户明确同意，避免静默读取。读取到的内容应做最小化处理，仅提取必要字段；写入内容不得包含用户个人隐私信息
广告实例管理：激励视频广告只支持单实例，创建一次后复用；及时 Destroy 释放资源
文件操作：优先使用 TTFileSystemManager 的异步方法（非 Sync 后缀），避免阻塞主线程
PlayerPrefs 替代：Unity 原生的 PlayerPrefs 在小游戏环境不可用，使用 TT.PlayerPrefs 替代
API 版本兼容：使用 CanIUse 判断 API 是否可用，做好版本兼容降级处理
TTSDK 版本：注意 SDK 版本的 API 变更（如 6.1.1 引入 Param 类替代旧版参数格式），及时更新

Douyin Mini Game Unity

Install

核心框架

功能 API

账号与开放能力

商业化

系统与设备

数据与文件

媒体与交互

快速参考

C# 与 JavaScript API 命名对照

初始化最小示例

支付完整流程

激励视频广告

最佳实践

Related skills