文档中心 > 开发指南

widget回访指引

更新时间：2026/03/12 访问次数：5563

一、能力介绍
二、接入流程
FAQ

一、能力介绍

桌面触达包含 快捷方式、桌面小组件（widegt）、日历等，旨在通过系统及厂商能力，拓展用户回端渠道，并提供差异化信息、权益展示的能力，提高运营能力。若用户已接入其他淘宝小游戏的widget，添加后将进行替换。

技术接入widget会自动接入淘侧提供的widget添加教程页，游戏方只需要提交widget素材、进行技术接入、做好游戏内入口。

注意：高性能模式下，不建议接入widget回访，会存在添加失败情况。

二、接入流程

1. 生成widget素材

需要在技术接入前提前完成素材提交，联系小二 @乐乐提交widget素材。请提交直角素材，建议素材中强调游戏权益、游戏道具等元素。提交后需要小二侧进行配置，请确认已经配置完成后再继续接入。

widget素材规范请参考： ?widget素材规范.png

组件素材可下载： ?互动WIDGET 设计参考.sketch

2. 技术接入示例

前置确认：请先确认游戏是否获得widget对应权限包，在开发者后台应用管理中进入消费者端小游戏-小游戏开发-小游戏开发权限，确认是否已获得【淘宝终端触达权限包】；若显示状态为可申请，请先申请该权限包权限。

// async await 实现示例
async function installWidget() {
  try {
    const widgetInstance = await my.tb.createWidgetInstance({
      id: 219,
      typeId: "gameCenterMini",
    });
    const res = await widgetInstance.getInstallInfo({ guideFrom: xxxx });
    if (res?.available) {
      // 拉起widget安装引导页
      widgetInstance.install({ guideFrom: xxxx });
    }
  } catch (error) {
    console.log("error", error);
  }
}

// .then 调用链实现示例
function installWidget() {
  my.tb
    .createWidgetInstance({ id: 219, typeId: "gameCenterMini" })
    .then((widgetInstance) => {
      widgetInstance.getInstallInfo({ guideFrom: xxxx }).then((res) => {
        if (res?.available) {
          // 拉起widget安装引导页
          widgetInstance.install({ guideFrom: xxxx });
        }
      }).catch( err => {
        console.log('处理获取信息错误', err);
      });
    })
    .catch(err => {
        console.log('处理初始化错误', err);
    });
}

API	async / sync	入参	返回值	说明
createWidgetInstance	async	{ id: 219， typeId: "gameCenterMini" }	widget实例	创建widget实例
getInstallInfo	async	{ guideFrom: 游戏对应的appid }	{ available: boolean, widgetInfo: { isInstalled: boolean, addApiAvailable: boolean, appVersionAvailable: boolean, systemVersionAvailable: boolean, } }	获取安装信息 ① available 【根据当前触达策略、环境，判断是否允许添加】 — ps：建议根据该字段控制是否展示添加入口 ② widgetInfo 【小组件相关信息】 — isInstalled【当前设备下小组件是否已安装】 — addApiAvailable【是否支持一键添加】 — appVersionAvailable 【app 版本是否满足要求】 — systemVersionAvailable【系统版本是否满足要求】
install	async	{ guideFrom: 游戏对应的appid， installSuccessCallback?: () => void }	无	①installSuccessCallback【安卓一键添加成功回调】 ② 表现： — 安卓支持一键添加则直接触发添加弹窗，否则唤起半屏教程页 — iOS 唤起半屏教程页