# 推荐流游戏直出能力-获客版

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

# 核心优势

拉新流量阵地：获客版将抖音大盘用户的游戏偏好数据融入推荐算法，让接入直玩获客的游戏获得更广阔的拉新流量阵地。
无缝体验衔接：基于小游戏容器预加载能力，将预加载完成的游戏在推荐流中分发给用户，实现抖音推荐流无缝进入游戏的交互体验。

# 示例介绍

用户刷抖音	获客卡片展现	用户点击进入游戏	开启新手剧情

# 接入收益

新增激活人群：新增激活总人数贡献占比27.5%。
新增激活收入：新增激活总收入贡献占比16.8%。

# 接入流程简述

# 接入流程介绍

# 接入申请

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

# 方案设计

# 竖屏游戏设计规范

游戏画布规范

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

设计规范	游戏原画	效果示例

# 横屏游戏设计规范

游戏画面展示规范

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

设计规范	游戏原画	效果示例
	游戏原画16:9尺寸 ⬇️ 推荐流直出容器裁切为4:3尺寸

设计规范

游戏原画

效果示例

游戏原画16:9尺寸

⬇️

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

游戏画布规范

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

设计规范	游戏原画	效果示例

# 方案提报

Step 1：开发者上传用于获客拉新的游戏首帧画面图片及文案，用于平台审核方案；
Step 2：完成方案上传后，点击「提交审核」，整体的图片与文案将会进入审核；
Step 3：审核通过后点击「下一步」。

# API接入

# 整体技术架构

1、抖音推荐流向用户分发游戏直玩卡时，抖音在后台自动预加载游戏进程，此处建议开发者开发游戏保护机制，游戏保护机制可查看下文的《风险提示（推荐接入）》；
2、游戏客户端完成游戏场景加载完成后，需调用「上报加载完成时机」API进行加载完成事件上报，否则游戏不会在用户的抖音推荐流中展示；
3、当用户滑到直玩卡时，游戏前台展示并进入交互流程。

# 关键API调用时序

Step 1：接入「获取启动信息」API能力；
Step 2：接入「上报加载完成时机」API能力；
Step 3：接入「监听进入/退出小游戏事件」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说明

# 获取启动信息

# 接口说明

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

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，登录《抖音开放平台控制台》后台，进入「数据」-「性能分析」-「启动性能」-「启动场景配置」模块，添加游戏的自定义启动场景，游戏每次启动只可以上报一次
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、用户点击进入游戏后，开发者侧应静默完成用户注册，并实现游戏进程的继承和延续。

# 开发者数据分析指引

注意

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

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

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

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

← 添加到桌面（选接）推荐流游戏直出能力-复访版 →