开放平台V2文档

# 推荐流游戏直出能力-复访版

推荐流游戏直出能力，是抖音为小游戏开发者打造的场景化用户召回&获客的解决方案，其中复访版服务于用户召回场景。了解更多内容请阅读抖音小游戏官方文档《推荐流游戏直出能力-复访版接入指南》 (opens new window)。

# 核心优势

  • 高价值信息触达：以游戏内的高价值信息作为历史玩家召回的抓手，利用游戏进程中不同场景下的重点信息进行高效触达。
  • 无缝衔接体验：基于小游戏容器预加载能力，将预加载完成的游戏在推荐流中分发给用户，实现抖音推荐流无缝进入游戏的交互体验。

# 示例介绍

用户抖音上玩小游戏 用户玩游戏过程中体力耗尽后退出游戏，用户刷抖音 游戏离线恢复体力，体力恢复后用户刷到游戏推荐卡片，提示用户游戏体力恢复 用户点击游戏推荐卡片直接进入游戏游玩

# 接入收益

  • 活跃用户留存：活跃用户次日留存10%；活跃用户7日留存25%。
  • 新增付费用户留存：新增付费用户次日留存5%；新增付费用户7日留存8%。

# 接入流程简述

# 接入流程介绍

# 接入申请

登录《抖音开放平台控制台》 (opens new window)后台，完成以下操作：

  • Step 1：点击「能力」-「能力中心」；
  • Step 2：进入「运营能力」模块，点击「推荐流直出游戏」；
  • Step 3：进入「推荐流游戏直出能力」页面，选择「复访能力」页签；
  • Step 4：了解相关内容后，点击「开始接入」，即开始复访接入流程。

# 方案设计

# 竖屏游戏设计规范

游戏画布规范

  • 游戏画面作为背景，平台交互框架置于顶层。平台交互框架包括游戏名称、文案、「继续游戏/立即去玩」按钮等；
  • 开发者需把牵引用户的核心内容展示在「画布信息区」，更能吸引用户点击转化。
设计规范 游戏原画 效果示例

# 横屏游戏设计规范

游戏画面展示规范

  • 推荐流直出容器会将游戏画面裁切为4:3画面尺寸，中间部分作为推荐流展示的游戏画面；
  • 开发者需把牵引用户的核心内容集中在中间的4:3画面尺寸中，避免平台裁切丢失信息。
设计规范 游戏原画 效果示例

游戏原画16:9尺寸

⬇️

推荐流直出容器裁切为4:3尺寸

游戏画布规范

  • 画布展示区域：画面尺寸左侧宽度2/3，高度4/5区域；
  • 游戏角色主体：展示在画面左侧1/3区域，高度为画面高度的65%；
  • 游戏对话气泡：展示在画面左侧2/3区域，高度为画面高度80%，避开游戏主要行动按钮（开始游戏）；
  • 游戏角色展示半身像，角色主体与对话气泡需添加投影；
  • 游戏画面叠加40%不透明度#000000蒙层。
设计规范 游戏原画 效果示例

# 方案提报

  • Step 1：选择需要通过「推荐流直出游戏」能力提醒的信息场景；
  • Step 2：在对应场景下，配置文案信息和上传UI图片；
    1）游戏内的订阅文案及订阅授权弹窗UI图片
    2）在抖音推荐流展示的文案+UI（含游戏内的气泡提醒）
  • Step 3：配置完成后，可提交审核；
  • Step 4：方案审核通过后，平台将会自动生成 Content_id；
  • Step 5：点击「下一步」进入下一流程。

# API接入

# 整体技术架构

1、采用「开发者服务器接入」方式；
a）潜在风险：高峰期会有高并发流量查询用户就绪场景
b）建议方案：接入服务端托管能力；进行完备的性能测试，并在接入配置中评估&填写最高能承载的查询QPS
2、通过「获取启动信息」API能力，判断用户是否从推荐流直出启动，进而进行就绪场景的游戏场景加载；
3、游戏客户端完成对应就绪场景加载完成后，需调用「上报加载完成时机」API进行加载完成事件上报，否则游戏不会在用户的抖音推荐流中展示。

# 关键API调用时序

# 联调测试

# 测试设备信息配置

  • Step 1：点击「前往开通」可跳转至通用调试设备管理页面添加测试设备；
  • Step 2：使用抖音扫描屏幕二维码完成设备信息的添加。

# 进入测试模式进行调试

  • Step 1：选择要测试的方案，配置测试模式所需环境，点击「生成二维码」按钮，可生成测试入口二维码；
  • Step 2：测试用户游玩小游戏，让游戏场景处于就绪状态后，使用抖音扫描屏幕二维码进入测试模式；
  • Step 3：根据测试模式内弹窗指引完成能力接入调试，无法刷到直玩卡的问题平台会有弹窗提示，开发者可以根据提示进行定位。

# 测试报告检查

# 测试报告检查及确认

  • Step 1：完成测试验证后，平台将会自动生成测试用例报告；
  • Step 2：开发者需根据实际的测试情况，勾选确认已完成该测试项的测试；
  • Step 3：测试报告检查确认完成后，可进入下一步。

# 发布线上小流量验证

# 发布线上小流量验证

  • Step 1：测试报告确认完成后，可自助发起「线上小流量验证」；
  • Step 2：小流量验证期为7个自然日；
  • Step 3：小流量验证主要检查上线后用户对游戏的实际反馈，当用户的正CTR、负CTR满足准入要求后可全量上线。

# 小流量验证结果

  • Step 1：验证信息：正CTR、负CTR；
  • Step 2：标准：正CTR高于及格线，负CTR低于水位线。

# 功能全量上线

# 小流量验证通过后，申请推全

  • Step 1：小流量验证通过后，点击「申请推全」按钮即可申请全量上线；
  • Step 2：审核通过后，将自动全量，后续可直接查看该游戏的数据效果。

# API说明

# 查询订阅状态

# 接口说明

用于查询用户直玩订阅的授权状态。

sdkInstance.checkFeedSubscribeStatus(options);

最低基础库版本要求

若用户客户端基础库版本低于 3.34.0，调用 sdkInstance.checkFeedSubscribeStatus(options) 接口将直接触发失败回调函数，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）！

注意事项

直玩订阅能力仅支持抖音、抖音Lite，且必须在登录后才能调用；本接口存在频控限制，需要注意调用场景和频率。

# 参数说明

参数说明如下表所示：

选项 类型 必填 默认值 说明
type string 是 -- 订阅推荐流的类型，目前仅支持 play 直玩场景
allScene boolean 否 false 是否为全场景订阅
scene number 否 --

订阅的场景ID（非全场景下必传）

  • 1 - 离线收益场景
  • 2 - 体力恢复场景
  • 3 - 重要事件掉落
success function 否 -- 接口调用成功的回调函数
fail function 否 -- 接口调用失败的回调函数
complete function 否 -- 接口调用完成的回调函数，成功或失败均会调用

# 返回值说明

WARNING

返回值格式：JSON 格式。

选项 类型 说明
code number 响应状态码，为 0 时表示接口调用成功，其他非 0 状态码均表示接口调用失败
data object / null 接口调用成功时返回查询结果，接口调用失败时返回 null
    data.status boolean 为 true 时表示已经订阅，为 false 时表示尚未订阅
message string 接口调用成功或失败时的相应描述信息

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 若用户客户端基础库版本低于 3.34.0，调用此接口将直接触发失败回调函数，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）
sdkInstance.checkFeedSubscribeStatus({
  type: "play",
  scene: 1,
  success: function(response) {
    console.log(response.data.status); // 是否已经订阅：true 表示已经订阅，false 表示尚未订阅
  },
  fail: function(error) {
    sdkInstance.modal.message(error.message);
  },
  complete: function(result) {
    // do something here...
  }
});

# 订阅

# 接口说明

用于向用户请求授权，允许游戏在满足一定的条件后出现在推荐流中。

sdkInstance.subscribeFeedMessage(options);

最低基础库版本要求

若用户客户端基础库版本低于 3.34.0，调用 sdkInstance.subscribeFeedMessage(options) 接口将中断用户当前操作并弹出升级提示，不会报错！

注意事项

直玩订阅能力仅支持抖音、抖音Lite，且必须在登录后才能调用；本接口存在频控限制，需要注意调用场景和频率；全场景订阅必须要由用户点击触发，也就是只能在 tt.onTouchEnd 的回调里面同步调用该API。

# 参数说明

参数说明如下表所示：

选项 类型 必填 默认值 说明
type string 是 -- 订阅推荐流的类型，目前仅支持 play 直玩场景
allScene boolean 否 false 是否为全场景订阅
scene number 否 --

订阅的场景ID（非全场景下必传）

  • 1 - 离线收益场景
  • 2 - 体力恢复场景
  • 3 - 重要事件掉落
contentIds string[] 否 -- 自定义提醒文案的 contentId 数组（非全场景下必传）；contentId 在抖音开放平台控制台申请开通直玩能力后可获取
success function 否 -- 接口调用成功的回调函数
fail function 否 -- 接口调用失败的回调函数
complete function 否 -- 接口调用完成的回调函数，成功或失败均会调用

# 返回值说明

WARNING

返回值格式：JSON 格式。

选项 类型 说明
code number 响应状态码，为 0 时表示接口调用成功，其他非 0 状态码均表示接口调用失败
data object / null 接口调用成功时返回订阅结果，接口调用失败时返回 null
    data.success boolean 为 true 时表示订阅成功，为 false 时表示订阅失败
message string 接口调用成功或失败时的相应描述信息

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 若用户客户端基础库版本低于 3.34.0，调用此接口将中断用户当前操作并弹出升级提示，不会报错！
sdkInstance.subscribeFeedMessage({
  type: "play",
  scene: 1,
  contentIds: ["CONTENT12345678", "CONTENT23456789"],
  success: function(response) {
    console.log(response.data.success); // 是否订阅成功：true 表示订阅成功，false 表示订阅失败
  },
  fail: function(error) {
    sdkInstance.modal.message(error.message);
  },
  complete: function(result) {
    // do something here...
  }
});

# 获取启动信息

# 接口说明

用于获取游戏启动参数、启动场景值，以及自定义信息等，从而判断当前游戏启动是否是推荐流直出场景，并自动加载到相关的游戏场景。

const launchOptions = sdkInstance.getLaunchOptionsSync();

# 返回值说明

注意

返回值格式：JSON 格式。

选项 类型 说明
scene string 启动场景值，推荐流直出场景后四位为 3041，例如：023041（前两位为可变的数字）；判断后四位是 3041 即可确认为推荐流直出场景
query object 启动参数，包含复访版相关的场景信息
    query.feed_game_scene number

游戏场景类型：

  • 1 - 离线收益场景
  • 2 - 体力恢复场景
  • 3 - 重要事件掉落
    query.feed_game_content_id string 本次启动对应的内容ID，在抖音开放平台控制台申请开通复访能力后可获取
    query.feed_game_channel number

渠道标识：

  • 1 - 复访用户
  • 2 - 获客用户
    query.feed_game_extra string 游戏自定义扩展信息，可通过推荐流直出游戏能力SPI接入文档接口的 extra 字段进行赋值

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 获取游戏启动参数、启动场景值，以及自定义信息等
const launchOptions = sdkInstance.getLaunchOptionsSync();

// 判断是否为推荐流直出场景（后四位为3041）
if (launchOptions.scene && launchOptions.scene.slice(-4) === "3041") {
  console.log("从推荐流直出场景启动");
  console.log("场景类型：", launchOptions.query.feed_game_scene); // 1：离线收益，2：体力恢复，3：重要事件掉落
  console.log("内容ID：", launchOptions.query.feed_game_content_id);
  console.log("渠道标识：", launchOptions.query.feed_game_channel); // 1：复访用户，2：获客用户

  // 游戏侧上报预启动数据（用户无感知阶段），注意：这是一段伪代码，具体由开发者自行实现
  reportData("preboot");

  // 启动监听，等待用户真实进入游戏
  // 详见下方“监听进入/退出小游戏事件”接口
}

# 上报加载完成时机

# 接口说明

游戏客户端完成对应游戏场景加载后，需调用此接口进行加载完成事件上报，否则游戏不会在用户的抖音推荐流中展示。

sdkInstance.reportScene(options);

最低基础库版本要求

若用户客户端基础库版本低于 2.88.0，调用 sdkInstance.reportScene(options) 接口将直接触发失败回调函数，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）！

# 参数说明

参数说明如下表所示：

选项 类型 必填 默认值 说明
sceneId number 是 -- 场景ID，固定为 7001，标识游戏场景加载完成，达到用户可交互状态
costTime number 否 0 场景耗时，单位ms
dimension object 否 {} 自定义维度数据，只支持能够通过 JSON.stringify 序列化的对象，且序列化后长度不超过 1024 个字符 ​
metric object 否 {} 自定义指标数据，只支持能够通过 JSON.stringify 序列化的对象，且序列化后长度不超过 1024 个字符 ​
success function 否 -- 接口调用成功的回调函数
fail function 否 -- 接口调用失败的回调函数
complete function 否 -- 接口调用完成的回调函数，成功或失败均会调用

# 返回值说明

WARNING

返回值格式：JSON 格式。

选项 类型 说明
code number 响应状态码，为 0 时表示接口调用成功，其他非 0 状态码均表示接口调用失败
data object / null 接口调用成功时返回开发者上报的原始数据，接口调用失败时返回 null
message string 接口调用成功或失败时的相应描述信息

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 若用户客户端基础库版本低于 2.88.0，调用此接口将直接触发失败回调函数，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）
sdkInstance.reportScene({
  sceneId: 7001,
  costTime: 1260,
  dimension: {
    d1: "2.1.0" // value仅支持传入string类型；若value表示boolean值，请将值处理为"0"、"1"进行上报；若value表示number值，请将值转换为string类型进行上报
  },
  metric: {
    m1: "546" // value仅支持传入数值且需要转换为string类型进行上报
  },
  success: function(response) {
    console.log(response.data); // 开发者上报的原始数据
  },
  fail: function(error) {
    console.log(error);
  },
  complete: function(result) {
    // do something here...
  }
});

# 监听进入/退出小游戏事件

# 接口说明

用于监听用户从推荐流进入/退出小游戏事件，帮助开发者识别用户是否真实启动游戏（即是否为真实活跃用户）。

sdkInstance.onFeedStatusChange(callback);

最低基础库版本要求

若用户客户端基础库版本低于 3.59.0，调用 sdkInstance.onFeedStatusChange(callback) 接口将直接触发回调函数，并返回失败信息，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）！

# 参数说明

参数说明如下表所示：

选项 类型 必填 默认值 说明
callback function 是 -- 事件回调函数

# 返回值说明

WARNING

返回值格式：JSON 格式。

选项 类型 说明
code number 响应状态码，为 0 时表示接口调用成功，其他非 0 状态码均表示接口调用失败
data object / null 接口调用成功时返回事件结果，接口调用失败时返回 null
    data.type string 为 feedEnter 时表示从推荐流进入小游戏，为 feedExit 时表示退出小游戏回到推荐流
message string 接口调用成功或失败时的相应描述信息

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 获取游戏启动参数、启动场景值，以及自定义信息等
const launchOptions = sdkInstance.getLaunchOptionsSync();

// 判断是否为推荐流直出场景（后四位为3041）
if (launchOptions.scene && launchOptions.scene.slice(-4) === "3041") {
  console.log("从推荐流直出场景启动");
  console.log("场景类型：", launchOptions.query.feed_game_scene); // 1：离线收益，2：体力恢复，3：重要事件掉落
  console.log("内容ID：", launchOptions.query.feed_game_content_id);
  console.log("渠道标识：", launchOptions.query.feed_game_channel); // 1：复访用户，2：获客用户

  // 游戏侧上报预启动数据（用户无感知阶段），注意：这是一段伪代码，具体由开发者自行实现
  reportData("preboot");

  // 标记用户是否首次真实进入游戏
  let firstEnter = true;

  // 用户进入/退出小游戏事件
  const feedStatusChangeCallback = function(response) {
    // code 非 0 时表示接口调用失败
    if (response.code !== 0) {
      return;
    }

    // 用户首次从推荐流进入游戏（点击“立即去玩”后触发）
    if (firstEnter && response.data.type === "feedEnter") {
      console.log("用户真实进入游戏，此时可计为活跃用户");

      // 
      firstEnter = false;

      // 游戏侧上报用户活跃数据（此时用户已经真实进入游戏），注意：这是一段伪代码，具体由开发者自行实现
      reportData("activity");

      // 根据场景类型，跳转到对应的游戏场景
      const scene = launchOptions.query.feed_game_scene;

      switch(scene) {
        case 1:
          console.log("进入离线收益场景"); // 跳转到离线收益领取页面
          break;
        case 2:
          console.log("进入体力恢复场景"); // 跳转到体力恢复提示页面
          break;
        case 3:
          console.log("进入重要事件掉落场景"); // 跳转到重要事件提醒页面
          break;
      }
    }

    // 用户退出小游戏回到推荐流
    if (response.data.type === "feedExit") {
      console.log("用户退出小游戏回到推荐流"); // 可以在这里做一些清理工作或统计
    }
  };

  // 启动监听，监听用户进入/退出事件
  sdkInstance.onFeedStatusChange(feedStatusChangeCallback);

  // // 游戏结束时取消监听（可选）
  // sdkInstance.offFeedStatusChange(feedStatusChangeCallback);
}

# 取消监听进入/退出小游戏事件

# 接口说明

用于取消监听用户从推荐流进入/退出小游戏事件。

sdkInstance.offFeedStatusChange(callback);

最低基础库版本要求

若用户客户端基础库版本低于 3.59.0，调用 sdkInstance.offFeedStatusChange(callback) 接口将直接触发回调函数，并返回失败信息，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）！

# 参数说明

参数说明如下表所示：

选项 类型 必填 默认值 说明
callback function 否 -- 通过 onFeedStatusChange 绑定的事件回调函数，不传时将取消所有事件监听

# 返回值说明

无

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 定义事件回调函数
const feedStatusChangeCallback = function(response) {
  // code 非 0 时表示接口调用失败
  if (response.code !== 0) {
    return;
  }

  console.log(response.data.type); // 动作类型：feedEnter 表示从推荐流进入小游戏，feedExit 表示退出小游戏回到推荐流
};

// 若用户客户端基础库版本低于 3.59.0，调用下列接口将直接触发回调函数，并返回失败信息，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）
sdkInstance.onFeedStatusChange(feedStatusChangeCallback); // 注册事件监听
sdkInstance.offFeedStatusChange(feedStatusChangeCallback); // 取消事件监听

# 开发者数据分析指引

注意

如果开发者有自建的用户数据分析能力，需接入本能力；如果没有自建的用户数据分析能力，则无需接入！

在推荐流游戏直出场景，分为两个启动阶段：

1、「直玩预启动」阶段：用户无感知，此时用户还未真实进入游戏。
2、「直玩点击启动」阶段：用户刷到直玩卡并且点击“立即去玩”，此时用户已真实进入游戏，可计算为真实活跃。

为了帮助开发者更好地识别用户处于哪个启动阶段，是否有真实进入游戏，进而校准用户活跃相关统计数据。平台提供了用户在「直玩预启动」和「直玩点击启动」两个转化行为的开发者感知能力。

Last Updated: 2025/11/24 14:25:33

← 订阅消息（选接） →