SDK对接文档

主题

WARNING

💡 Unity Tiktok小游戏

准备工作： ​

更新ZMYSDK包管理器到最新

切换TikTok小游戏，并导入小游戏插件




导入配置 ​

WARNING

💡 需要切 WebGL 平台

导入游戏配置 ​




Debug 模式的开启或关闭

发最后一个正式包时，一定要取消 DebugMode

TikTok 平台功能接入 ​

WARNING

💡 本节能力中，必须接入的只有“添加到桌面”和“从侧边栏启动”。订阅消息、渠道内分享均为按需接入；其他广告、埋点接入请参考接口说明。

  • 需求细节、交互、以及调试方法参考官方文档: TikTok小游戏一站式接入指南2.0

  • 官方文档为js API，对接Unity TikTok（TikTokFunction）插件后，调用C# 包装后的接口；

  • 复访能力API 必须是tiktok 41.0.0 及以上才能使用，所以调用相关api必须要先使用CanIUseXXXX接口判断，否则会报错；TikTokFunction包装有进行兜底，unity游戏可以直接调用不报错，但是CanIUseXXXX接口可以作为是否开启此复访能力界面交互的依据；比如如果CanXXXX返回false ，添加桌面不可用，不显示交互按钮。

必须接入功能 ​

复访能力-添加到桌面 ​

Csharp
//判断添加到桌面接口是否可用； 官方接口TTMinis.game.canIUse("addShortcut")
TIKTOKMsg.Instance.CanIUseAddShortcut()；

//添加到桌面；官方接口 TTMinis.addShortcut
TIKTOKMsg.Instance.AddShortcut(() =>
{
    LogUI.Log("add shortcut success");
}, () =>
{
    LogUI.Log("add shortcut failed");
});

//判断“判读用户是否可以领取添加到桌面奖励”接口是否可用； 官方接口TTMinis.game.canIUse("getShortcutMissionReward")
TIKTOKMsg.Instance.CanIUseGetShortcutMissionReward()；

// 判读用户是否可以领取添加到桌面奖励；官方接口TTMinis.getShortcutMissionReward
TIKTOKMsg.Instance.GetShortcutMissionReward((value) =>
{
    LogUI.Log("GetShortcutMissionReward success : " + value);//value： bool类型
}, () =>
{
    LogUI.Log("GetShortcutMissionReward failed");
});

复访能力-从侧边栏启动 ​

Csharp
//判断跳转到侧边栏界面是否可用； 官方接口TTMinis.game.canIUse("startEntranceMission")
TIKTOKMsg.Instance.CanStartEntranceMission()；

//跳转 Tiktok 个人主页侧边栏，引导复访；官方接口 TTMinis.startEntranceMission
TIKTOKMsg.Instance.StartEntranceMission(() =>
{
    LogUI.Log("StartEntrance success");
}, () =>
{
    LogUI.Log("StartEntrance failed");
});

//判断“判断用户是否可以领取完成复访教育任务奖励”接口是否可用； 官方接口TTMinis.game.canIUse("getEntranceMissionReward")
TIKTOKMsg.Instance.CanGetEntranceMissionReward()；

// 判断用户是否可以领取完成复访教育任务奖励；官方接口TTMinis.getEntranceMissionReward
TIKTOKMsg.Instance.GetEntranceMissionReward((value) =>
{
    LogUI.Log("GetEntranceMissionReward success : " + value);
}, () =>
{
    LogUI.Log("GetEntranceMissionReward failed");
});

按需接入功能 ​

订阅消息 ​

TikTok 渠道订阅消息用于在用户授权后，通过延迟消息触达用户，并在用户点击 TikTok Inbox 的 Minis 消息进入游戏后读取启动参数。接入前需要先确认以下事项：

  1. 联系相关平台同学，将测试账号 uid 加入 TT 订阅消息能力白名单。uid 获取方式：在 TikTok App 的“设置与隐私”中滑到最底部，连续点击 App 版本信息，即可点击复制 userId 等内容。
  2. 确认测试账号已加入 TT 小游戏预览白名单，否则可能无法通过预览码进入测试小游戏。
  3. 确认后台已经配置好订阅模板 ID 和模板参数。测试 Demo 中使用的模板 ID 示例为 10006。
  4. data 字典中的 key 需要和服务端/模板配置保持一致，TT 模板参数通常使用 s_ 前缀字段，例如 { "s_task", "unity测试任务" }。
  5. 确认 SDK 登录流程已完成。appId、openId、lang 等字段由 SDK 自动补充，游戏层不需要传。

订阅消息开白和 TT 小游戏预览测试白名单不是同一个能力，需要分别确认。模板可参考官方文档确认使用的模板及对应参数：【可对外】Tiktok小游戏 Inbox 消息盒子 接入文档。TikTok 官方此能力在内测阶段，官方文档可能频繁改动，使用时请进入官方文档确认模板是否符合预期。

拉起订阅授权 ​

接口：

csharp
XYX.RequestSubscribe(string tmplId);
XYX.RequestSubscribe(
    string tmplId,
    Action<Dictionary<string, string>> success,
    Action<int> fail
);
XYX.RequestSubscribe(
    string[] tmplIds,
    Action<Dictionary<string, string>> success,
    Action<int> fail
);

TT 渠道内部会调用 TTMinis.game.requestSubscribeMessage。TT 是按小游戏维度订阅，不按具体模板订阅，因此 tmplId 在 TT 渠道下主要用于兼容微信/抖音接口签名，实际 JS 接口不会使用模板 ID，TikTok 渠道可以传空字符串。

csharp
XYX.RequestSubscribe("",
    data =>
    {
        LogUI.Log("Submessage RequestSubscribe data : " + data);
    },
    error =>
    {
        LogUI.Log("Submessage RequestSubscribe failed : " + error);
    });

创建延迟订阅消息 ​

接口：

csharp
XYX.SubmessageAdd(
    string templateId,
    string sceneId,
    long timeStamp,
    Dictionary<string, string> templateData,
    Action<bool, string> callback = null
);

参数说明：

参数说明
templateId订阅模板 ID。
sceneId业务场景 ID。同一用户下，templateId + sceneId 用于定位一条延迟消息。TikTok 官方没有 sceneId 概念，游戏可按业务场景自行定义和维护。
timeStamp13 位 Unix 毫秒时间戳，表示指定发送时间。
templateData模板内容参数。
callback创建结果回调，success=true 表示上报成功。

发送时间为 3 分钟后的时间戳示例：

csharp
long delayTime = DateTimeOffset.UtcNow.AddMinutes(3).ToUnixTimeMilliseconds();

调用示例：

csharp
long delayTime = DateTimeOffset.UtcNow.AddMinutes(3).ToUnixTimeMilliseconds();

XYX.SubmessageAdd(
    "10006",
    "TaskProcess",
    delayTime,
    new Dictionary<string, string>
    {
        { "s_task", "unity测试任务" },
        { "minis_path", "/?level=2&coins=100" }
    },
    (success, msg) =>
    {
        LogUI.Log("SubmessageAdd success : " + success + " msg : " + msg);
    });

删除延迟订阅消息 ​

接口：

csharp
XYX.SubmessageDelete(
    string templateId,
    string sceneId,
    Action<bool, string> callback = null
);

删除尚未发送的延迟消息，定位条件与创建一致：同一用户下通过 templateId + sceneId 定位消息。适用于任务提前完成、体力提前恢复、奖励已领取等不再需要提醒的场景。

csharp
XYX.SubmessageDelete(
    "10006",
    "TaskProcess",
    (success, msg) =>
    {
        LogUI.Log("SubmessageDelete success : " + success + " msg : " + msg);
    });

查询订阅状态 ​

接口：

csharp
XYX.SubmessageSubscriptionQuery(
    Action<bool, XYXSubmessageSubscriptionStatus, string> callback = null
);

查询当前登录用户在 TT 渠道下的订阅状态。TT 客户端 SDK 暂未直接提供对应查询接口，因此 SDK 内部会通过服务器转发查询。SDK 层会自动补充 appId 和 openId，游戏层不需要传入参数。

回调参数说明：

参数说明
success接口是否调用成功。true 表示服务端返回 code == "0"。
status订阅状态数据。失败或返回为空时可能为 null。
msg结果信息。成功时通常为 success，失败时为错误信息。

XYXSubmessageSubscriptionStatus 字段说明：

csharp
public class XYXSubmessageSubscriptionStatus
{
    public bool is_eligible;
    public bool is_subscribed;
}
字段含义
is_eligible用户当前是否满足 TT 订阅消息相关条件，具体含义以 TT 官方文档为准。
is_subscribed用户当前是否已订阅。

调用示例：

csharp
XYX.SubmessageSubscriptionQuery((success, status, msg) =>
{
    string statusLog = status == null
        ? "null"
        : "is_eligible:" + status.is_eligible + " is_subscribed:" + status.is_subscribed;

    LogUI.Log("SubmessageSubscriptionQuery success : " + success
        + " msg : " + msg
        + " status : " + statusLog);
});

点击消息携带启动参数 ​

创建延迟消息时，游戏层可以在 data 字典中额外传入 minis_path：

csharp
{ "minis_path", "/?level=2&coins=100" }

服务端发送消息时可使用 minis_path 作为点击消息后的跳转路径。用户点击 TT Inbox 消息进入游戏后，游戏可以通过启动参数读取这些信息，并自行设计交互，例如打开指定页面、定位任务或展示奖励弹窗。

csharp
XYXLaunchOption option = XYX.GetLaunchOption();

if (option != null && option.query != null)
{
    foreach (var item in option.query)
    {
        LogUI.Log("Launch query: " + item.Key + "=" + item.Value);
    }
}

如果传入 { "minis_path", "/?level=2&coins=100" }，点击消息进入游戏后，通常可以从 option.query 中读取到 level=2、coins=100 等参数，具体以 TT 启动参数实际返回为准。

启动参数接口 ​

获取原始场景字符串：

csharp
XYX.GetLaunchScene((string scene) =>
{
    LogUI.Log("GetLaunchScene Scene str: " + scene);
});

TT 返回示例：

text
minis_link

获取通用场景枚举：

csharp
XYX.GetLaunchScene((LaunchScene scene) =>
{
    LogUI.Log("GetLaunchScene LaunchScene: " + scene);
});

当前通用枚举包括：

csharp
LaunchScene.None
LaunchScene.Side
LaunchScene.DesktopShortcut
LaunchScene.Feed

如果 TT 返回的场景无法映射到现有枚举，会返回 LaunchScene.None。

获取完整启动参数：

csharp
XYXLaunchOption option = XYX.GetLaunchOption();

LogUI.Log("Scene: " + option.scene_str);
LogUI.Log("Query count: " + option.query?.Count);

XYXLaunchOption 字段说明：

csharp
public class XYXLaunchOption
{
    public string scene_str;
    public LaunchScene scene;
    public string path;
    public Dictionary<string, string> query;
    public XYXLaunchType launchType;
}
字段类型说明
scene_strstringTikTok SDK 返回的原始启动场景字符串。
sceneLaunchSceneSDK 映射后的通用启动场景枚举。
pathstring本次启动路径，例如 pages/index/index。
queryDictionary<string, string>启动参数键值对；无参数时可能为 null 或空字典。
launchTypeXYXLaunchType本次启动类型：Cold（冷启动）或 Hot（热启动）。

推荐测试流程 ​

  1. 使用测试账号进入 TT 小游戏预览包。
  2. 点击 Demo 中的 RequestSubscribe 按钮，确认能拉起 TT 订阅面板。
  3. 用户点击同意订阅。
  4. 点击 SubmessageAdd，创建一条 3 分钟后的延迟消息。
  5. 等待到点，确认 TikTok Inbox 的 Minis 频道收到消息。
  6. 点击消息进入游戏。
  7. 调用 XYX.GetLaunchOption()，确认能读取到启动参数。
  8. 再次点击 SubmessageAdd 后，点击 SubmessageDelete，确认对应消息不会再发送。
  9. 使用相同 templateId + sceneId 重复上报，确认覆盖逻辑符合预期。

注意事项 ​

  • delayTime 必须是 13 位 Unix 毫秒时间戳，不需要传时区。
  • appId、openId、lang 由 SDK 层自动补充，游戏层不要传。
  • TT 渠道订阅不按模板 ID 授权，RequestSubscribe 的模板 ID 只是兼容参数。
  • sceneId + templateId 应保持业务唯一性，便于覆盖和删除。
  • data 字典中的模板字段必须和模板配置一致。
  • 如需点击消息进入游戏后携带业务参数，建议通过 minis_path 传递。

TikTok 渠道内分享 ​

TikTok 渠道可以向好友发送游戏分享卡片，并在分享链接中携带业务参数。标题、描述和图片目前由 TikTok 后台配置，游戏传入的对应参数暂不生效，建议传空字符串。

接口：

csharp
XYX.ShareAppFirendInvite(XYX.ShareAppFirendInviteParams shareParams);
XYX.OnShareFinish(Action<bool> callback);

建议先注册分享结果回调，再发起分享：

csharp
using System.Collections.Generic;

XYX.OnShareFinish(success =>
{
    Debug.Log("OnShareFinish success: " + success);
});

XYX.ShareAppFirendInvite(new XYX.ShareAppFirendInviteParams
{
    title = "",
    content = "",
    imgFile = "",
    userNickName = "",
    templateId = "2",
    extraParams = new Dictionary<string, string>
    {
        { "level", "10" },
        { "score", "5000" }
    }
});

ShareAppFirendInviteParams 参数说明：

字段类型说明
titlestring分享标题；TikTok 当前使用后台配置的游戏名，建议传空字符串。
contentstring分享描述；TikTok 当前使用后台配置的游戏描述，建议传空字符串。
imgFilestring分享图片；TikTok 当前使用后台配置的游戏图标，建议传空字符串。
userNickNamestring邀请人的昵称，不需要在分享中携带昵称时传空字符串。
templateIdstringTikTok 分享卡片模板类型，支持 "1" 或 "2"。
extraParamsDictionary<string, string>点击分享进入游戏时携带的参数；不需要自定义参数时可传 null 或空字典。

分享结果回调中的 success=true 表示分享成功，success=false 表示分享失败。如果只需要普通分享、不做助力、挑战或奖励交互，可以不处理后续启动参数。

获取分享启动参数 ​

通过分享卡片进入游戏后，可以使用以下接口监听冷启动和热启动，并从 query 中读取分享时传入的 extraParams：

csharp
public static void RegisterLaunchListener(
    Action<XYXLaunchType, XYXLaunchOption> callback
);

public static void UnregisterLaunchListener();
启动类型回调时机
Cold小游戏从完全关闭状态首次打开，在 SDK 初始化完成后回调一次。
Hot小游戏未完全关闭，用户每次从后台切回前台时回调。

游戏层注册一次监听即可，并在对象销毁时注销：

csharp
using UnityEngine;
using XYXCommon;

public class TikTokShareLaunch : MonoBehaviour
{
    private void Start()
    {
        XYX.RegisterLaunchListener(OnLaunchCallback);
    }

    private void OnDestroy()
    {
        XYX.UnregisterLaunchListener();
    }

    private void OnLaunchCallback(XYXLaunchType type, XYXLaunchOption option)
    {
        if (option?.query == null)
        {
            return;
        }

        if (option.query.TryGetValue("level", out string levelText)
            && int.TryParse(levelText, out int level))
        {
            Debug.Log("Launch type: " + type + ", level: " + level);
        }
    }
}

WARNING

TikTok 平台热启动时，底层 TT.GetLaunchOptionsSync() 仍可能返回冷启动的旧值。需要处理分享回流、助力或挑战等热启动场景时，必须从 RegisterLaunchListener 的回调参数读取最新的 scene、path 和 query。

如果只需要获取当前启动信息快照，也可以调用：

csharp
XYXLaunchOption option = XYX.GetLaunchOption();

如果只需要读取某一个参数，也可以使用 XYX.cs 提供的便捷接口：

csharp
if (XYX.TryGetLaunchQuery_GetParam("level", out string level))
{
    Debug.Log("Launch level: " + level);
}

分享交互注意事项 ​

  • query 可能为 null 或空字典，读取前必须判空并校验字段。
  • 分享参数应尽量简短；关卡、分数等数值使用 TryParse，不要直接信任客户端参数。
  • 助力、奖励、防刷等关键逻辑应由服务端校验。建议使用唯一 share_id，并按 share_id + 点击用户 uid 做幂等控制。

TikTok 事件上报 ​

  • 游戏可玩（游戏加载完成时上报）（必接）：
Csharp
TIKTOKMsg.Instance.GameCanPlayTTReport();
  • 以下事件非必接，根据项目实际情况选择上报。

通用上报接口：

Csharp
TIKTOKMsg.Instance.TikTokEventReport(string eventName, string jsonString);

gain_credits、spend_credits 在 C# 中直接使用通用接口会报错，请分别使用以下 API：

Csharp
TIKTOKMsg.Instance.TTReportGainPointEvent(string jsonString);
TIKTOKMsg.Instance.TTReportSpendPointEvent(string jsonString);

上报状态可搜索日志 tag：[tiktokEventReport]

以完成关卡 complete_section 为例：

Csharp
using Newtonsoft.Json.Linq;

JObject obj = new JObject();
obj["section_type"] = "0";
obj["main_section_no"] = 1;
obj["section_value"] = 0;
obj["section_name"] = "主线关卡1";
obj["section_id"] = 1;
obj["section_sum"] = 1;

TIKTOKMsg.Instance.TikTokEventReport("complete_section", obj.ToString());

事件概览 ​

Event Name事件名称上报时机/定义
create_role创建角色玩家创建角色时上报；如果游戏没有创建角色流程，或注册账号等于创建角色，则注册后延迟 1s 上报。
create_group创建战队玩家创建战队或团队时上报。
join_group加入战队玩家加入战队或团队时上报。
achieve_level达到等级玩家达到指定等级时上报；重要等级节点可使用 level_value=0 标记高价值等级。
unlock_achievement解锁成就玩家完成指定成就并解锁时上报。
complete_section完成关卡玩家完成指定关卡或玩法时上报。
gain_credits获取奖励玩家获得可在游戏内使用的货币或积分时上报。
spend_credits消耗奖励玩家在游戏内消耗货币或积分时上报。

参数说明 ​

Event Name参数类型/要求说明
create_rolegamerole_idstring角色 ID。
create_rolegamerole_sumint角色总数。
create_groupunion_idstring组织编号。
join_groupunion_idstring组织编号。
achieve_levellevelint当前等级。
achieve_levellevel_valueint，可选枚举：0 高价值，1 低价值建议将数值压力卡点、封印等级等重要等级标记为高价值。
achieve_levelitem_typeint 枚举：0 主人物，1 角色，2 宠物，3 VIP 等级主人物为最高维度等级，如玩家等级、账号等级，必传；每个枚举最多回传一位最高等级标的。
achieve_levelitem_idstring升级目标 ID；基于 item_type 传对应的主人物、角色、宠物或装备 ID。
unlock_achievementachievement_typestring 枚举：0 付费类，1 其他成就类型。
unlock_achievementachievement_sumint玩家当前已达成的总成就数。
unlock_achievementachievement_idstring成就 ID。
complete_sectionsection_typestring 枚举：0 主线关卡，1 活动关卡，2 挑战关卡关卡类型；主线关卡最重要，必传。
complete_sectionmain_section_noint主线关卡序号，仅主线关卡使用；例如主线关卡 1 的序号为 1，主线关卡必传。
complete_sectionsection_valueint，可选枚举：0 高价值，1 低价值建议将数值压力关卡、高难度关卡等重要关卡标记为高价值。
complete_sectionsection_namestring关卡在游戏中的名称。
complete_sectionsection_idint关卡 ID。
complete_sectionsection_sumint玩家已完成关卡总数。
gain_creditsvalueint虚拟货币或积分数量。
gain_creditstoken_typeint，必选枚举：0 一级货币，1 二级货币0 表示必须付费获得的主要货币；1 表示可通过付费货币兑换、看广告等方式获得的二级货币。
gain_creditstoken_idstring货币或积分 ID，例如金子、银子、钻石、星琼等；上报游戏内一种主要货币即可。
spend_creditspvalueint虚拟货币或积分数量。
spend_creditstoken_typeint 枚举：0 一级货币，1 二级货币0 表示必须付费获得的主要货币；1 表示可通过付费货币兑换、观看广告等方式获得的二级货币。
spend_creditstoken_idstring货币或积分 ID，例如金子、钻石、星琼等。

功能组件 ​

Tiktok WEBGL 下面的输入 InputField 会失效 ​

可以动态添加组件 XYX.InputFieldAdapter(inputField.gameObject);

构建与调试 ​

构建 ​

Unity 菜单栏选择：TikTokGame => Build Minigame


Wasm 分包前检查 ​

进行 Unity Wasm 分包前，先完成以下检查：

  1. 执行 ttmg login，确认命令行账号登录成功。
  2. 登录账号必须拥有 TikTok 后台的代码包上传、删除权限。只有预览测试权限的 testUser 账号权限不足，需要由发布同学邀请账号加入对应组织并授予后台权限。
  3. 打开分包工具后先切换到“项目概览”，确认项目名称、描述等信息正常显示，再开始分包。
  4. 截至 2026-07-15，TikTok 官方仅支持使用 US 地区账号进行分包。账号地区由注册时选择的地区决定；地区不确定且无法分包时，需改用明确注册为 US 地区的账号。
  5. 如果账号之前可以正常分包，后来无故失败：先确认 ttmg 已更新到最新版并重新登录；仍未恢复时，清除 TikTok App 缓存，重新登录 App 后再次扫码分包。

WARNING

预览白名单、订阅消息白名单和代码包管理权限是三套不同权限。能扫码进入预览包，不代表账号具备 Wasm 分包所需的后台权限。

调试 ​

需要对账号先授权，这里请找我方运营同学授权

官方文档

1. 安装前置依赖 ​

命令行工具

shell

npm install @ttmg/cli -g --registry=https://registry.npmjs.org/

ttmg -v

下载客户端

  • iOS：App Store 下载最新的 TikTok 应用

  • Android：Google Play 下载最新的 TikTok 应用

2. 完成账号登录 ​

登录客户端

使用账号密码登录 TikTok

TT Account oncall自助排查

命令行登录 ​

使用平台注册的账号和密码完成本地 CLI 的登录，非必须，但涉及到代码上传、查看项目详情以及 unity wasm 分包等能力时需要登录后才可进行。为确保后续功能的顺利运行，建议您优先完成账号登录，再进行后续的调试操作。

ttmg login

本地扫码调试


发布 ​

官方文档

上传 .zip 文件。未压缩文件大小不得超过 200 MB。文件上传后，将进行安全扫描。请确保文件符合要求后再上传。



合法域名处理 ​

什么是合法域名 ​

在小程序后台的开发设置中， 有一处配置。合法域名的地方。

其中将域名分为几个大类，我们重点关注 request，socket，download。

request 就是常规的 http 请求，get,post。

socket 请求 webgl 使用 wss 域名

download 就是我们的 cdn 地址。这里有一点需要注意，cdn 地址除了配置到 download 中，还需要配置到 request 中

为什么要配置这个 ​

小游戏严格限制了请求的地址信息，只有配置上的地址 才能成功的进行访问。所有的配置的域名都是要求经过备案的，否则无法配置。

哪些需要配置 ​

联系对应得运营，在后台进行添加：

所有的 域名 不带端口的 配置到域名级，带端口的请求需要带上端口，举个例子

C#
原始  https://log.328vip.com/stat/index/initV2
配置  https://log.328vip.com

带端口的
原始  https://pay.wedobest.com.cn:8449/xxx/bbb/ccc
配置  https://pay.wedobest.com.cn:8449

Tiktok QA ​