WARNING

模块名：GameHelper.ZFBAddHome

支付宝渠道必备模块，SDK 默认包含。业务层统一调用 GameHelper，不要直接调用 my.xxx。

能力概览

能力	SDK 模块	业务接入内容
设首 / 复访	GameHelper.ZFBAddHome	任务 UI、跳转与发奖
生命周期 / 转化埋点	GameHelper.GameBizReport	加载完成、进入游玩、创角
增量行为 / 游戏中心事件	GameHelper.ZFBReportGame	按运营要求调用
添加到桌面	GameHelper.AddDesk	引导加桌与发奖
游戏圈入口	GameHelper.GameClub	主界面展示入口
礼包（含激励礼包）	GameHelper.LiBao	监听、发奖与领取上报

设首和复访

接入前请阅读支付宝的设首与复访说明，并由策划确定任务 UI、奖励与发放频次。

初始化任务类型

SDK 初始化后调用 getAddHomeResult。成功回调返回 true 表示已经设首，可展示复访任务；返回 false 表示未设首。

GameHelper.ZFBAddHome.getAddHomeResult({
  success: (alreadyAddHome) => {
    if (alreadyAddHome) {
      // 已设首：展示复访任务
    } else {
      // 未设首：展示设首任务
    }
  },
  fail: () => {},
});

完成设首与复访任务

GameHelper.ZFBAddHome.jumpToAddHome({
  success: () => {
    // 用户完成设首，发放奖励
  },
  fail: () => {},
});

GameHelper.ZFBAddHome.jumpToRevisit({
  // debugMode: true, // 未上架时仅供调试，正式包必须移除或设为 false
  success: () => {
    // 用户从游戏中心回流，发放复访奖励
  },
  fail: () => {},
});

WARNING

未上架应用不会显示在游戏中心的“最近使用”中。测试阶段可传 debugMode: true，按引导进入游戏中心后直接返回游戏；正式包必须删除该参数或设为 false。应用上线后仍需完整验证一次复访流程。

设首与复访事件

需求方要求接入时，通过 reportCustomEvent 上报：

GameHelper.ZFBAddHome.reportCustomEvent(
  GameHelper.ZFBAddHome.TASK_EVENT_NAME.SetIconExpo,
);

时机	SDK 枚举
展示 / 点击设首入口	SetIconExpo / SetIconClick
展示设首面板 / 点击任务按钮	SetPanelExpo / SetPanelClick
领取设首奖励成功	SetPrizeReceive
展示 / 点击复访入口	ReIconExpo / ReIconClick
展示复访面板 / 点击前往复访	RePanelExpo / RePanelClick
领取复访奖励成功	RePrizeReceive

生命周期数据回传

该能力对应支付宝的数据回传指引，调用时机影响加载率、创角率和登录率。SDK 在首次登录成功（LOGIN_FINISH）后自动上报授权完成，业务无需调用。

接口	调用时机	注意
reportLoadingCompleted()	资源加载、热更、连服完成；有选服时在选服页或自动进入主场景后	同一生命周期只成功上报一次
reportGameCharacterCreated(initial)	创角成功；无角色概念的 IAA 玩法可不调用	initial 必须为 boolean
reportGamePlay()	玩家已可体验核心内容	历史接过 my.reportGamePlay 的项目应整体迁移到本接口

GameHelper.GameBizReport.reportLoadingCompleted();
GameHelper.GameBizReport.reportGameCharacterCreated(true);
GameHelper.GameBizReport.reportGamePlay();

增量行为与游戏中心事件

接入前先与需求方确认游戏行为编码，研发不要自行创建 actionCode 或 eventId。

GameHelper.ZFBReportGame.reportGameAction({
  actionCode: "GAME_LEVEL_PASS",
  success: () => {},
  fail: () => {},
});

GameHelper.ZFBReportGame.reportGamecenterEvent({
  eventId: "YOUR_EVENT_ID",
  success: () => {},
  fail: () => {},
});

添加到桌面

GameHelper.AddDesk.checkIsAdd((isAdd) => {
  // false：支持加桌接口，可展示引导；true：已添加或当前环境不支持
  if (!isAdd) {
    // 展示“加桌领奖”入口
  }
});

GameHelper.AddDesk.addDesk((ok) => {
  if (ok) {
    // 发放加桌奖励
  }
});

• 支付宝侧依赖 checkShortcut / addShortcut；不支持时 SDK 会按“已添加”处理，避免误引导。
• 加桌失败时 SDK 可能调用 showAuthGuide({ authType: 'SHORTCUT' }) 引导授权。
• 发奖规则由业务层控制。

游戏圈

对应支付宝游戏圈介绍与 my.createGameClubButton。

if (GameHelper.GameClub.isSupported()) {
  GameHelper.GameClub.show({
    type: GameHelper.GameClub.BUTTON_TYPE.IMAGE,
    icon: GameHelper.GameClub.ICON.BLUE,
    style: { x: 0, y: 200, width: 80, height: 80 },
    success: () => {},
    fail: () => {},
  });
}

// 切换场景时隐藏原生按钮
GameHelper.GameClub.hide();

style.x/y 以 Canvas 中心为锚点；传入 width/height 后，x/y 表示按钮中心。支小宝等不支持游戏圈的环境应隐藏自研入口。

礼包（含激励礼包）

支持游戏圈礼包和激励广告下单礼包。

function onGift(goodsList, id) {
  // 按 goodsList 中的 Id / Num 发放道具
  GameHelper.LiBao.reportRecordStatus({
    id,
    completion: (successList) => {
      console.log("领取状态上报成功", successList);
    },
  });
}

GameHelper.LiBao.onLiBaoFound(onGift);

注册后 SDK 会自动查询一次；若登录未完成，会等待 LOGIN_FINISH。激励视频完整播放或中途关闭时，SDK 都会自动执行 checkLiBao。

GameHelper.LiBao.checkLiBao({
  completion: (goodsList, id) => {
    // 发奖
    return true;
  },
  autoReport: false,
});

字段	含义
Id	道具 ID；激励下单礼包的 Id/Num 可能不准确，可通过 propertyType === "alipay_gift_pack" 识别并按固定礼包发奖
Num	数量
bizId	订单或资产 ID
spaceCode	激励下单广告位
propertyType	礼包类型，例如 alipay_gift_pack

DANGER

发奖成功后必须调用 reportRecordStatus，否则可能重复发奖或导致平台状态异常。查询约有 4 秒频控；上报失败时 SDK 最多重试 3 次。