开发指南
一、能力介绍
桌面触达包含 快捷方式、桌面小组件（widegt）、日历等，旨在通过系统及厂商能力，拓展用户回端渠道，并提供差异化信息、权益展示的能力，提高运营能力。若用户已接入其他淘宝小游戏的widget，添加后将进行替换。
技术接入widget会自动接入淘侧提供的widget添加教程页，游戏方只需要提交widget素材、进行技术接入、做好游戏内入口。
二、接入流程
1. 生成widget素材
需要在技术接入前提前完成素材提交，联系小二 @饭饭 @摆锤 进行widget素材配置。请提交直角素材，建议素材中强调游戏权益、游戏道具等元素。
widget素材规范请参考： ?widget素材规范.png
组件素材可下载： ?互动WIDGET 设计参考.sketch
2. 技术接入示例
前置确认：请先确认游戏是否获得widget对应权限包，在开发者后台应用管理中进入消费者端小游戏-小游戏开发-小游戏开发权限，确认是否已获得【淘宝终端触达权限包】；若显示状态为可申请，请先申请该权限包权限。
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);
}
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 唤起半屏教程页 |
3. 游戏内入口
游戏可选择合适的点位，通过发放权限与游戏内奖励，教育用户添加桌面widget并进行回访，如：任务列表、首页活动。
类型 |
示例 |
任务列表 |
|
首页活动 |
|
4. 渠道识别能力
玩家回访游戏时，游戏方可通过该渠道识别API识别用户来源。
若识别用户从widget回访，判断该「全部频道」回访任务、活动完成，发放游戏对应奖励。
API文档 |
备注 |
桌面widget的渠道标识参数为WIDGET |
游戏上线前可通过拼接调试码链接或预览码的链接，加上参数hdkf_from=widget来mock widget回访链路，测试发奖。
注：添加参数时请按照URL拼接参数的技术规范，根据实际情况使用?或者&符号进行拼接。
