游戏模块
本页介绍如何通过 Playol SDK 对接游戏核心行为事件（如加载、运行、暂停）、同步排行榜与成就数据。适用于所有基于 JS 的 H5 游戏，无需引入第三方框架或自建后端。
Playol SDK 提供一套完整的游戏行为上报机制，用于支持平台的用户行为分析、排行榜、成就系统等。调用方式简单、自动关联玩家身份，所有数据自动同步至平台，无需开发者手动构建后端数据库。游戏开发者只需专注于业务逻辑，接入成本极低，适合所有基于 JavaScript 的 Web 游戏场景。
📌 一、使用场景
- 在 游戏资源加载页 中埋点加载起止行为，便于分析“页面加载效率”和“用户流失点”；
- 上报用户在游戏内的运行行为（进入、暂停等），平台可用于优化广告策略或行为分析；
- 同步用户的得分、成就等数据，平台据此生成排行榜、奖励成就；
- 所有行为均与当前登录用户自动绑定，支持 多端同步、断点续玩、跨设备云记录。
🧩 二、方法与调用方式
🌀 页面资源加载阶段（Loading）
loadingStart()
标记“游戏资源开始加载”——仅用于游戏尚未进入的加载页场景。
此方法用于标记从页面打开开始进入游戏资源加载环节的时间节点，主要用于分析加载耗时、加载期间流失等指标。
window.playolSDK.game.loadingStart()loadingStop()
标记“游戏资源加载完成”——游戏正式进入运行前的时间点。
window.playolSDK.game.loadingStop()📌 说明：
- 不应在每个关卡加载时调用，仅用于页面首次加载进入游戏前的场景；
- 在加载界面展示完毕、游戏准备好运行前立即调用
loadingStop()； - 可结合首帧时间统计、流失点分析使用。
▶️ 游戏运行状态埋点
playStart()
标记“游戏进入运行状态”或“从暂停恢复”，如：进入关卡、继续游戏等。
window.playolSDK.game.playStart()playStop()
标记“游戏中断/暂停状态”，如：跳转到菜单、设置、广告弹窗等。
window.playolSDK.game.playStop()📌 建议调用时机：
playStart()用于记录用户实际进入游戏内容的时间起点；playStop()用于记录用户停止游戏交互（非关闭页面）的中断节点；- 可辅助平台识别“活跃时段”“游戏粘性”等行为模型。
🏆 同步成就数据
syncAchievement(achvKey, achvData)
提交用户在某项成就上的达成状态，用于构建成就展示/解锁功能。
| 参数名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| achvKey | string | 是 | 成就唯一标识（平台需预设） |
| achvData | string | number | 是 | 成就进度值或完成状态 |
根据成就类型的不同，achvData 应采用不同格式：
| 成就类型 | 说明 |
|---|---|
| 一次性成就 | 达成某个任务即完成 |
| 进度成就 | 完成百分比展示（0-100%） |
| 累计成就 | 有明确进度数值（如 30/100） |
// 一次性成就示例（通关第一关）
window.playolSDK.game.syncAchievement('CLEAR_STAGE_1', 1)
// 进度成就示例（游戏完成度 50%）
window.playolSDK.game.syncAchievement('GAME_COMPLETION', 50)
// 累计成就示例（收集了 80 枚金币）
window.playolSDK.game.syncAchievement('COLLECT_COINS', 80)📌 说明：
- 自动绑定
成就数据自动关联当前用户（userId）和游戏（gameId），无需额外标记身份。当用户切换账号、退出登录或身份变更时，系统会自动处理数据隔离与切换。
- 前置要求
必须先在开发者平台配置成就信息（成就key、类型、最大值等），否则上报无效 - 状态计算
平台根据配置自动计算成就状态（0:未达成/1:达成）
一次性成就： 上报值匹配完成标识时，状态更新为"达成"
进度成就： 上报值大于或等于配置最大值时，状态更新为"达成"
累计成就： 上报值大于或等于配置最大值时，状态更新为"达成" - 数据更新
多次上报以最新值为准
已达成成就的状态保持为"已达成"
首次达成时间会被记录并保留 - 使用场景
可用于触发前端成就解锁动画、奖励提示、服务器回调等逻辑。
- 调用时机
建议在关键节点（通关、获得物品、任务完成）调用
📊 同步排行榜数据
syncRankData(rankData)
上报用户的得分或表现指标，供平台进行排行榜排序与展示。
| 参数名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| rankKey | string | 是 | 排行榜唯一标识（平台需预设） |
| rankData | string | number | 是 | 用户得分、通关时间等数值 |
根据排行榜类型的不同，rankData 应采用不同格式：
| 排行榜类型 | 说明 |
|---|---|
| 数量类型 | 根据数值大小排行（积分、宝石数等） |
| 时长类型 | 根据时间长度排行（通关时间、生存时间等） |
| 时间类型 | 根据时间点排行（最早通关、最晚达成等） |
// 积分排行榜示例（数量类型）
window.playolSDK.game.syncRankData('TOTAL_SCORE', 9850)
// 速通排行榜示例（时长类型- mm:ss.SSS格式）
window.playolSDK.game.syncRankData('SPEED_RUN', '01:55.500')
// 首通排行榜示例（时间类型）
window.playolSDK.game.syncRankData('FIRST_CLEAR', '2025-01-06 12:30:45')📌 说明：
- 自动绑定
排行榜数据自动关联当前用户（userId）和游戏（gameId）。当用户切换账号、退出登录或身份变更时，系统会自动处理数据隔离与切换。
- 前置要求
必须先在开发者平台配置排行榜信息（排行榜key、排序规则等），否则上报无效
- 排序规则
倒序： 数值越大排名越靠前
正序： 数值越小排名越靠前 - 使用场景
可用于展示全服排名、个人最佳记录、赛季排行榜等。 - 调用时机
建议每次关卡结束或得分变化后上报，保持数据准确性。
🛠️ 三、推荐实践场景
| 场景描述 | 推荐调用方式 |
|---|---|
| 游戏加载页开始 | loadingStart() |
| 游戏加载页结束，进入主逻辑 | loadingStop() |
| 进入实际游戏内容 | playStart() |
| 跳转菜单 / 广告弹窗 | playStop() |
| 成就解锁 / 任务完成 | syncAchievement() |
| 更新分数 / 通关时间 | syncRankData() |
📦 四、常见问题解答
Q: loadingStart() 和 playStart() 有什么区别？
A: loadingStart() 只用于记录页面首次加载资源时的埋点；playStart() 表示玩家进入实际可交互游戏的阶段。
Q: sync 系列方法会覆盖旧数据吗？
A: 会实时更新记录值，如多次调用以最后一次为准；排行榜系统自动取最大值/最新值。
Q: 方法调用失败有回调吗？
A: 当前版本为静默上报，若遇网络中断平台会重试，未来版本将支持 Promise 形式结果回传。