TikTok 小游戏适配器

TikTok 小游戏适配器通过 TTMinis 全局对象调用 TikTok 平台 API，提供登录、授权、广告（激励视频、Banner、插屏）、分享、侧边栏、桌面快捷方式、入口任务等功能。

类定义

import { TiktokSdk } from "@lingames/clever-sdk/src/platformMini/TiktokSdk.js";

const sdk = new TiktokSdk(platform, project_id, game_id);

• 全局对象: TTMinis
• 继承: CleverSdk

初始化

interface ttInitialize {
    sdk_login_url?: string;
}

await sdk.initialize({
    sdk_login_url: "https://api.salesagent.cc/game-analyzer/player/login"
});

登录

const data = await sdk.login();

登录流程:

1. 调用 TTMinis.game.login() 获取临时登录凭证 code
2. 将 code 连同 platform、project_id 发送到 SDK 登录服务器
3. 服务器返回 session_key，SDK 自动保存

参考: TikTok 登录

授权登录

支持指定 scope 的授权登录，适用于需要额外用户信息的场景。

const data = await sdk.authorize("user.info");

• scope 可选，指定授权范围（如 user.info）
• 若平台不支持 authorize API，会抛出异常

激励视频广告

interface ttCreateRewardedVideoAd {
    adUnitId?: string;  // 通用广告单元 ID
    ttUnitId?: string;  // TikTok 专用广告 ID
}

const reward = await sdk.playRewardedVideo({
    ttUnitId: "your_tt_ad_unit_id"
});
// reward.isEnded === true 时发放奖励

广告实例复用: SDK 内部会缓存广告实例，当 adUnitId 变化时自动重新创建。

参考: TikTok 激励视频

Banner 广告

interface ttCreateBannerAd {
    adUnitId: string;      // 广告单元 ID
    adIntervals?: number;  // 自动刷新间隔（秒），>= 30
    style?: BannerStyle;   // 广告样式
}

await sdk.createBannerAd({
    adUnitId: "banner_id",
    adIntervals: 30,
    style: { left: 0, top: 100, width: 300, height: 50 }
});
await sdk.showBannerAd();
await sdk.hideBannerAd();
await sdk.destroyBannerAd();

参考: TikTok Banner 广告

插屏广告

interface ttCreateInterstitialAd {
    adUnitId?: string;  // 通用广告单元 ID
    ttUnitId?: string;  // TikTok 专用广告 ID
}

const reward = await sdk.showInterstitialAd({
    ttUnitId: "your_interstitial_ad_unit_id"
});
// reward.isEnded === true 表示展示成功

参考: TikTok 插屏广告

分享

interface ttShareAppMessage {
    title?: string;         // 转发标题
    description?: string;   // 分享文案
    imageUrl?: string;      // 转发图片链接
    query?: string;         // 查询字符串
    imageUrlId?: string;    // 审核通过的图片编号
    toCurrentGroup?: boolean;
    path?: string;
}

const success = await sdk.shareAppMessage({
    title: "分享标题",
    description: "分享描述",
    imageUrl: "https://example.com/share.png"
});

参考: TikTok 分享

侧边栏检测

interface CheckSceneResult {
    isSupport: boolean;  // 是否支持侧边栏
    isScene: boolean;    // 当前是否在侧边栏场景中
}

const result = await sdk.checkScene();
// result.isSupport === true && result.isScene === true 表示从侧边栏进入

• 若平台不支持 checkScene API，返回 { isSupport: false, isScene: false }

参考: TikTok 侧边栏

桌面快捷方式

添加到桌面

await sdk.addShortcut({
    // 平台特定参数
});

• 若平台不支持 addShortcut API，返回 false

检查快捷方式奖励

const status = await sdk.checkShortcut();
// 或
const status = await sdk.getShortcutMissionReward();

// status.isSupport — 是否支持该功能
// status.canReceiveReward — 是否可以领取奖励

• checkShortcut() 实际调用 getShortcutMissionReward()
• 若平台不支持，返回 { isSupport: false, canReceiveReward: false }

入口任务

启动入口任务

const success = await sdk.startEntranceMission();

• 若平台不支持，返回 false

获取入口任务奖励

const status = await sdk.getEntranceMissionReward();
// status.isSupport — 是否支持该功能
// status.canReceiveReward — 是否可以领取奖励

• 若平台不支持，返回 { isSupport: false, canReceiveReward: false }

API 能力检测

const supported = sdk.canIUse("game.login");

• 检测当前 TikTok 宿主版本是否支持指定 API
• 返回 boolean

设为常用

await sdk.addCommonUse();

8. 中间事件回传（TikTok 小游戏）

TikTok 适配器重写了 reportEvent，直接通过 TTMinis.game.request 发送事件到上报服务器：

await sdk.reportEvent("event_id", { key: "value" });

TikTok 平台支持回传小游戏中间事件，帮助广告模型更好地理解用户行为，提升广告投放效果。

根据 TikTok 官方文档，回传有效的中间事件可使广告支出回报率（ROAS）提升 10-20%。

8.1 支持的标准事件

事件类型	枚举值	说明
游戏加载完成	TiktokGameEvent.LOADING_COMPLETE	玩家完成资源加载或进入首页
完成关卡	TiktokGameEvent.COMPLETE_SECTION	玩家完成指定关卡或玩法
获取奖励	TiktokGameEvent.GAIN_CREDITS	玩家获取游戏内虚拟货币/积分
玩家离开游戏	TiktokGameEvent.USER_LEAVE	玩家主动或被动退出

8.2 上报方式

通过 reportEvent 方法上报，在 data 中传入 event_type 字段指定标准化事件类型：

import { TiktokGameEvent } from "@lingames/clever-sdk/models";

// 游戏加载完成
(window as any).mySdk.reportEvent("event-xxx", {
    event_type: TiktokGameEvent.LOADING_COMPLETE,
    complete_time: Date.now(),
});

// 完成关卡
(window as any).mySdk.reportEvent("event-xxx", {
    event_type: TiktokGameEvent.COMPLETE_SECTION,
    section_type: 0,          // 0=主线关卡
    main_section_no: 5,       // 主线关卡序号
    section_name: "沙漠遗迹",   // 关卡名称（可选）
    section_id: 105,          // 关卡 ID（可选）
    section_sum: 12,          // 已完成关卡总数（可选）
    section_value: 0,         // 0=高价值（可选）
});

// 获取奖励
(window as any).mySdk.reportEvent("event-xxx", {
    event_type: TiktokGameEvent.GAIN_CREDITS,
    value: 500,
    token_type: 0,            // 0=一级货币（付费），1=二级货币
    token_id: "diamond",
});

// 玩家离开游戏
(window as any).mySdk.reportEvent("event-xxx", {
    event_type: TiktokGameEvent.USER_LEAVE,
    leave_time: Date.now(),
    leave_reason: 1,          // 1=主动退出，2=kill App，见文档
});

8.3 重要说明

• 双通道上报：每个 reportEvent 调用同时走两条通道：
  1. HTTP POST 到通用事件端点（游戏后台数据分析）
  2. TikTok 原生 TTMinis.game.reportEvent API（广告模型优化）
• id vs event_type：id 是游戏内部自定义的事件标识（如 "event-xxx"），event_type 是平台标准事件类型。两者互不冲突，各司其职。
• 向后兼容：不传 event_type 的事件仍然正常工作，仅走 HTTP 通道。
• 版本要求：TikTok 原生回传需要客户端 40.9.0 及以上版本，SDK 会自动检测兼容性。
• 类型安全：根据传入的 event_type，TypeScript 会自动校验对应事件的必填参数，编译期即可发现参数缺失。