GameAction API

GameAction API

用于向平台上报单局游戏（round / stage / level）生命周期的方法集合。SDK 记录的动作会被平台用于数据分析与数据报表处理。所有调用都是 fire-and-forget，不会等待响应。

TudadaSDK.gameAction 命名空间下提供 3 个方法：

• start(options?) — 一局开始
• complete(options) — 一局正常通关
• exit(options) — 一局异常结束（放弃 / 超时）

---

start(options?)

通知游戏已开始一局。所有选项均为可选。

选项：

参数	类型	必填	说明
payload.round	number	-	回合编号
payload.stage	number	-	关卡编号
payload.level	number	-	等级编号
additionalPayload	string	-	自由元数据

// 示例 1：无参调用
TudadaSDK.gameAction.start();

// 示例 2：附带 stage 信息
TudadaSDK.gameAction.start({
  payload: { stage: 3 },
});

// 示例 3：附带自由元数据
TudadaSDK.gameAction.start({
  payload: { round: 1, stage: 3, level: 5 },
  additionalPayload: JSON.stringify({ tutorial: true }),
});

---

complete(options)

通知游戏已正常通关一局。result 与 playTime 必填。

选项：

参数	类型	必填	说明
payload.result	'WIN' | 'LOSE' | 'DRAW' | 'DONE'	✅	结束结果
payload.playTime	number	✅	一局时长 (ms)
payload.score	number	-	得分
payload.round	number	-	回合编号
payload.stage	number	-	关卡编号
payload.level	number	-	等级编号
additionalPayload	string	-	自由元数据

TudadaSDK.gameAction.complete({
  payload: {
    result: 'WIN',
    playTime: 12345,
    score: 9000,
    stage: 3,
  },
});

---

exit(options)

通知游戏未正常完成而结束一局（玩家放弃、超时等）。playTime 与 reason 必填。

选项：

参数	类型	必填	说明
payload.playTime	number	✅	一局时长 (ms)
payload.reason	'TIMEOUT' | 'ABANDONED'	✅	结束原因
additionalPayload	string	-	自由元数据

// 玩家放弃
TudadaSDK.gameAction.exit({
  payload: { playTime: 4500, reason: 'ABANDONED' },
});

// 超时
TudadaSDK.gameAction.exit({
  payload: { playTime: 60000, reason: 'TIMEOUT' },
});

提示

exit() 由游戏代码在判定一局结束的时点显式调用，与页面 unload（关闭 WebView）无关。