全端经营能力（选接）

全端经营能力是抖音为小游戏开发者打造的「小游戏 → 原生APP」用户导流与数据互通的解决方案。通过该能力，用户在抖音小游戏内完成轻度体验后，可被引导下载游戏APP，并实现双端的用户身份、游戏资产互通。了解更多内容请阅读《【抖音小游戏全端经营】产品接入手册》 (opens new window)。

核心优势

• 小游戏拉新 + APP深度经营：小游戏负责低成本获客，APP负责提供更好的游玩体验和更高的付费留存，双端配合经营提升用户长期LTV收益。
• 抖音内直接下载：用户无需跳转到应用商店，在抖音内即可直接下载安装APP。
• 双端数据互通：通过统一的抖音登录，用户在小游戏和APP中获得相同的 openid，实现游戏进度、道具、权益等资产的无缝同步。
• 平台一站式能力：登录、实名认证、支付等核心页面由平台统一提供，开发者通过SDK调用即可；退款入口需开发者自行放置并调用平台SDK接口；防沉迷限充由平台兜底，限玩能力可选择平台实现或游戏自行实现。

适用范围

• 仅支持 Android 系统 + 抖音主端，iOS 及其他客户端暂不支持。
• 仅支持抖音登录，小游戏和APP必须都使用抖音登录，不支持手机号、游客或其他第三方登录方式。
• 该能力目前处于定向邀请测试阶段，需联系抖音直客/运营开通白名单。

交互流程

整体链路为「小游戏内引导 → 下载APP → APP登录互通 → 资产同步」，小游戏负责前半段（引导和下载），后半段涉及APP客户端、全端经营原生SDK、游戏服务端及SDK服务端等多方协作，不在该小游戏接入文档介绍范围内，请参考《全端经营能力SDK接入指引》 (opens new window)。

阶段	操作	说明
1	小游戏内调用 sdkInstance.checkDownloadGiftEnabled	检查当前用户是否满足全端互通条件（平台策略判断），success 回调触发即表示允许互通
2	游戏侧展示「下载APP领礼包」入口	仅在上一步返回成功时展示入口，入口的位置和样式由游戏侧自行设计（如礼包图标、弹窗等）
3	用户点击入口，调用 sdkInstance.showDownloadGift	平台拉起半屏弹窗，展示礼包信息和下载按钮
4	用户点击下载	在抖音内直接下载APK并安装，无需跳转应用商店
5	用户打开APP → 抖音登录 → 实名认证	APP侧需接入全端经营SDK，通过抖音登录获取相同 openid 实现身份映射
6	平台自动发放下载礼包	通过 Webhook 通知开发者服务端完成礼包发放

接入前置条件

在接入全端经营能力之前，需先完成以下准备工作：

1. 在抖音小游戏后台（抖音开放平台 (opens new window) > 能力 > 能力中心 > 运营能力 > 全端经营-App）完成移动应用注册与白名单开通；
2. 在巨量引擎工作台 (opens new window)（资产 > 应用管理中心 > 安卓应用）完成APK包上传，并与小游戏建立绑定关系；
3. 在抖音小游戏后台配置下载礼包，获取礼包ID（giftId）；
4. APP侧完成全端经营能力SDK (opens new window)的接入（包括登录、支付、退款、防沉迷等能力）；
5. 服务端完成礼包发货 Webhook 对接。

注意，上述各步骤的详细操作指引，请参考《【抖音小游戏全端经营】产品接入手册》 (opens new window)。

API说明

获取全端经营APP下载信息

接口说明

用于检查当前用户是否满足全端互通条件（2.3.0 版本新增）。调用后若触发 success 回调，表示该用户允许互通，此时可在游戏内展示「下载APP领礼包」入口；若触发 fail 回调，则不应展示入口。

sdkInstance.checkDownloadGiftEnabled(options);

注意事项

• 全端经营能力依赖平台开白，未开白的游戏调用相关接口会返回失败；
• 目前平台要求仅对付费用户展示全端经营入口，一般可在付费用户每日登录时以及用户每次付费后进行请求。一个用户可以多次请求，但由于平台存在 AB 实验策略，同一用户的请求结果可能会变化，属于正常现象；
• 游戏付费数据存在约 2 秒左右延迟，用户付费后立即请求可能返回失败，建议延迟约 2 秒再请求，或首次请求失败后再请求一次；
• 当用户设备系统或客户端不支持该能力时（如 iOS、非抖音主端），调用该接口将直接触发 fail 回调函数并返回失败信息；若用户抖音版本过低导致该接口不存在，同样会触发 fail 回调函数并返回失败信息。

调用时机

建议在以下时机调用该接口：

时机	说明
付费用户每日登录时	检查用户是否满足互通条件，满足则展示入口
用户每次付费后约 2 秒	首次付费的用户可能刚满足条件，延迟 2 秒可避免因付费数据延迟导致的误判

参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
giftId	string	是	--	礼包ID，在抖音小游戏后台创建礼包后获取
success	function	否	--	接口调用成功的回调函数，触发即表示允许用户互通
fail	function	否	--	接口调用失败的回调函数
complete	function	否	--	接口调用结束的回调函数，成功或失败均会调用

返回值说明

WARNING

返回值格式：JSON 格式。

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

常见失败错误码（通过 code 字段返回）：

错误码	错误信息	说明
10302	The feature is not available in current operating system	系统不支持
10301	The feature is not supported in app	宿主不支持
10401	platform server	服务端返回错误
10401	request fail	网络请求失败
20000	user blocked by policy	用户策略屏蔽，命中 x 天内不能更换 giftId 的策略时会有额外说明
20001	game blocked by policy	游戏策略屏蔽，命中 x 天内不能更换 giftId 的策略时会有额外说明
20002	The gift does not exist or is out of stock	礼包不存在或库存不够，命中 x 天内不能更换 giftId 的策略时会有额外说明
20003	no game app package exist	游戏包不存在，命中 x 天内不能更换 giftId 的策略时会有额外说明
20004	request parameter error	参数错误，命中 x 天内不能更换 giftId 的策略时会有额外说明
20005	giftId is empty	礼包ID为空

示例代码

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

// 获取全端经营APP下载信息
sdkInstance.checkDownloadGiftEnabled({
  giftId: "yourGiftId", // 礼包ID，在抖音小游戏后台创建礼包后获取
  success: function(response) {
    console.log(response); // 触发此回调表示该用户允许互通，可在游戏内展示「下载APP领礼包」入口（具体入口位置、样式由游戏侧自行设计）
  },
  fail: function(error) {
    console.log(error.message); // 当前用户不满足条件或能力不可用，不展示入口
  },
  complete: function(result) {
    // do something here...
  }
});

拉起APP下载页

接口说明

用于拉起全端经营APP下载半屏弹窗页（2.3.0 版本新增）。弹窗页面由平台提供，包含礼包信息展示和下载按钮，会自动关联小游戏在巨量应用管理平台绑定的APP包体完成下载引导。

sdkInstance.showDownloadGift(options);

注意事项

• 调用此接口前，必须先调用 sdkInstance.checkDownloadGiftEnabled(options) 接口确认用户是否满足互通条件，否则可能出现用户看到弹窗但无法下载的问题；
• 当用户设备系统或客户端不支持该能力时（如 iOS、非抖音主端），调用该接口将直接触发 fail 回调函数并返回失败信息；若用户抖音版本过低导致该接口不存在，将直接弹出升级提示，不触发任何回调。

参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
giftId	string	是	--	礼包ID，在抖音小游戏后台创建礼包后获取
success	function	否	--	接口调用成功的回调函数
fail	function	否	--	接口调用失败的回调函数
complete	function	否	--	接口调用结束的回调函数，成功或失败均会调用

返回值说明

WARNING

返回值格式：JSON 格式。

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

常见失败错误码（通过 code 字段返回）：

错误码	错误信息	说明
10302	The feature is not available in current operating system	系统不支持
10301	The feature is not supported in app	宿主不支持
10401	platform server	服务端返回错误
10401	request fail	网络请求失败
21000	feed game not in foreground	处于feed流中，请在真正进入游戏后再调用
20000	internal error: open popup window failed	打开弹窗失败
20000	user blocked by policy	用户策略屏蔽，命中 x 天内不能更换 giftId 的策略时会有额外说明
20001	game blocked by policy	游戏策略屏蔽，命中 x 天内不能更换 giftId 的策略时会有额外说明
20002	The gift does not exist or is out of stock	礼包不存在或库存不够，命中 x 天内不能更换 giftId 的策略时会有额外说明
20003	no game app package exist	游戏包不存在，命中 x 天内不能更换 giftId 的策略时会有额外说明
20004	request parameter error	参数错误，命中 x 天内不能更换 giftId 的策略时会有额外说明
20005	giftId is empty	礼包ID为空

示例代码

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

// 拉起全端经营APP下载半屏页
sdkInstance.showDownloadGift({
  giftId: "yourGiftId", // 礼包ID，在抖音小游戏后台创建礼包后获取
  success: function(response) {
    console.log(response); // 拉起APP下载半屏页成功
  },
  fail: function(error) {
    console.log(error);
    sdkInstance.modal.message(error.message);
  },
  complete: function(result) {
    // do something here...
  }
});

获取APP下载进度

接口说明

用于获取全端经营APP当前的下载进度和状态信息（2.3.0 版本新增，此接口为可选接入）。

sdkInstance.getDownloadGiftStatus(options);

注意事项

• 小游戏启动后，用户需先点击进入下载落地页后，开发者才能获取最新下载进度。

参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
success	function	否	--	接口调用成功的回调函数
fail	function	否	--	接口调用失败的回调函数
complete	function	否	--	接口调用结束的回调函数，成功或失败均会调用

返回值说明

WARNING

返回值格式：JSON 格式。

选项	类型	说明
code	number	响应状态码，为 0 时表示接口调用成功，其他非 0 状态码均表示接口调用失败
data	object[] / null	接口调用成功时返回下载状态数据，失败时返回 null
data[n].giftId	string	仅有下载或者安装的礼包时才会返回
data[n].status	string	当前下载状态： idle - 空闲状态 download_active - 下载中 download_paused - 下载暂停 download_failed - 下载失败 download_finished - 下载完成 installed - 安装完成
data[n].progress	number	下载进度，取值 0-100，仅在 status 为 download_active 时返回
message	string	接口调用成功或失败时的相应描述信息

常见失败错误码（通过 code 字段返回）：

错误码	错误信息	说明
10302	The feature is not available in current operating system	系统不支持
10301	The feature is not supported in app	宿主不支持

示例代码

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

// 获取全端经营APP下载进度
sdkInstance.getDownloadGiftStatus({
  success: function(response) {
    console.log(response.data) // 数组格式

    console.log(response.data[n].giftId); // 仅有下载或者安装的礼包时才会返回
    console.log(response.data[n].status); // 当前下载状态：idle / download_active / download_paused / download_failed / download_finished / installed
    console.log(response.data[n].progress); // 下载进度：0-100，仅在 status 为 download_active 时返回
  },
  fail: function(error) {
    console.log(error);
    sdkInstance.modal.message(error.message);
  }
});

监听APP下载进度变化事件

接口说明

用于监听全端经营APP下载进度变化事件，当下载状态或进度发生变化时会触发回调通知（2.3.0 版本新增，此接口为可选接入）。

sdkInstance.onDownloadGiftStatusChange(callback);

参数说明

参数说明如下表所示：

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

返回值说明

WARNING

返回值格式：JSON 格式。

选项	类型	说明
code	number	响应状态码，为 0 时表示接口调用成功，其他非 0 状态码均表示接口调用失败
data	object / null	接口调用成功时返回下载状态变化数据，失败时返回 null
data.giftId	string	礼包ID
data.status	string	当前下载状态： idle - 空闲状态 download_active - 下载中 download_paused - 下载暂停 download_failed - 下载失败 download_finished - 下载完成 installed - 安装完成
data.progress	number	下载进度，取值 0-100
message	string	接口调用成功或失败时的相应描述信息

示例代码

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

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

  console.log(response.data.giftId); // 礼包ID
  console.log(response.data.status); // 当前下载状态：idle / download_active / download_paused / download_failed / download_finished / installed
  console.log(response.data.progress); // 下载进度：0-100

  // 根据下载状态做出适当响应
  switch(response.data.status) {
    case "download_active":
      console.log("下载中，进度：" + response.data.progress + "%");
      break;
    case "download_paused":
      console.log("下载暂停");
      break;
    case "download_finished":
      console.log("下载完成，等待安装");
      break;
    case "download_failed":
      console.log("下载失败");
      break;
    case "installed":
      console.log("安装完成");
      break;
  }
};

// 启动监听，监听APP下载进度变化事件
sdkInstance.onDownloadGiftStatusChange(downloadGiftStatusChangeCallcak);

// 不再需要时取消监听（可选）
// sdkInstance.offDownloadGiftStatusChange(downloadGiftStatusChangeCallcak);

取消监听APP下载进度变化事件

接口说明

用于取消监听全端经营APP下载进度变化事件（2.3.0 版本新增，此接口为可选接入）。

sdkInstance.offDownloadGiftStatusChange(callback);

参数说明

参数说明如下表所示：

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

返回值说明

无

示例代码

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

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

  console.log(response.data.giftId); // 礼包ID
  console.log(response.data.status); // 当前下载状态：idle / download_active / download_paused / download_failed / download_finished / installed
  console.log(response.data.progress); // 下载进度：0-100

  // 根据下载状态做出适当响应
  switch(response.data.status) {
    case "download_active":
      console.log("下载中，进度：" + response.data.progress + "%");
      break;
    case "download_paused":
      console.log("下载暂停");
      break;
    case "download_finished":
      console.log("下载完成，等待安装");
      break;
    case "download_failed":
      console.log("下载失败");
      break;
    case "installed":
      console.log("安装完成");
      break;
  }
};

sdkInstance.onDownloadGiftStatusChange(downloadGiftStatusChangeCallcak); // 注册事件监听
sdkInstance.offDownloadGiftStatusChange(downloadGiftStatusChangeCallcak); // 取消事件监听
sdkInstance.offDownloadGiftStatusChange(); // 取消所有事件监听

完整接入示例

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

// 礼包ID，在抖音小游戏后台创建礼包后获取
const giftId = "yourGiftId";

// 第一步，检查当前用户是否满足全端互通条件
sdkInstance.checkDownloadGiftEnabled({
  giftId: giftId,
  success: function(response) {
    console.log("当前用户满足全端互通条件");

    // 第二步，在游戏内展示「下载APP领礼包」入口；注意：入口位置和样式由游戏侧自行设计，以下为伪代码
    showDownloadGiftButton({
      onClick: function() {
        // 第三步：用户点击入口后，拉起平台提供的下载半屏弹窗
        sdkInstance.showDownloadGift({
          giftId: giftId,
          success: function(response) {
            console.log("拉起APP下载页成功");
          },
          fail: function(error) {
            console.log("拉起APP下载页失败");
            console.log(error.message);
          },
          complete: function(result) {
            // do something here...
          }
        });
      }
    });
  },
  fail: function(error) {
    console.log("当前用户不满足条件，不展示入口");
    console.log(error.message);
  },
  complete: function(result) {
    // do something here...
  }
});

相关文档

文档	说明
《抖音小游戏全端经营产品接入手册》	全端经营能力的完整产品接入流程，包含后台开通、APK上传、礼包配置、测试验证等全流程
《全端经营能力SDK接入指引》	全端经营SDK的技术接入文档，包含小游戏端 JSAPI、APP端原生SDK（Android/Unity）的接入说明