游戏自更新版本上报

本文为 TapTap PC 游戏更新机制 的接入指南，适用于通过自身热更新（自带启动器等）完成版本升级的游戏。版本号对比的原理见更新机制。

游戏通过自身热更新升级时，文件不经 TapTap 重新安装，.taptap/meta.json 中的版本号不会自动变化。若不处理，TapTap 会因 .taptap/meta.json 版本号低于线上包版本号而重复提示「更新游戏」。解决方式是：在热更新开始时，将 .taptap/meta.json 的版本号写为目标版本，使其不低于线上包版本号，TapTap 即不再提示。

接入分两步：在游戏包体中放入 .taptap/meta.json；在热更新开始时将其版本号写为目标版本。此外，首次接入前需检查开发者中心已上传包体的版本号，避免历史测试包体造成误判。

.taptap/meta.json 文件

游戏包体中必须包含 .taptap/meta.json 文件，放置在 TapTap 开发者中心配置的启动项同目录下。上传包体时，TapTap 后台会自动提取该文件中的版本号，无需手动填写。

请勿变更此路径

TapTap 客户端依赖固定路径 .taptap/meta.json（相对于开发者中心配置的启动项同目录）读取版本信息。若路径被移动或重命名，TapTap 将无法正确识别游戏版本，可能导致重复更新提示。

文件格式如下：

{
  "version": "v1.3.0",
  "app_id": 12345
}

字段说明：

字段	说明
version	游戏版本号，格式 vX.X.X，详见下文「版本号规范」。热更新升级时需将此字段写为目标版本号。
app_id	游戏在 TapTap 的数字 ID，可在 TapTap 游戏页 URL 中查看，例如 taptap.cn/app/12345。上传时 TapTap 会校验此字段，避免包体传错游戏。

推荐在 CI/CD 构建流程中自动生成此文件，确保版本号与构建版本一致。手动维护亦可，但每次发版都需同步更新 version 字段。

版本号规范

.taptap/meta.json 中的版本号必须与开发者中心上传的版本号使用同一套格式，否则无法正确比较。

版本号格式

格式为 vX.X.X，示例：v1.0.0、v1.2.3。不符合格式的版本号将无法被 TapTap 正确识别。

• X.X.X 为三段数字，以点分隔，每段为非负整数。
• 前缀 v 必须小写。
• 比较规则：从左到右逐段比较数字大小，例如 v1.2.3 < v1.2.4 < v1.3.0 < v2.0.0。

热更新开始时写入目标版本

游戏检测到新版本并开始热更新（而非更新完成）时，将 .taptap/meta.json 的 version 字段写为目标版本号——即将更新到的版本，而非当前已安装版本。例如目标版本为 v1.3.0：

{
  "version": "v1.3.0",
  "app_id": 12345
}

写入后 .taptap/meta.json 版本号不低于线上包版本号，TapTap 不再显示「更新游戏」按钮；当开发者中心后续将更高版本置为线上（线上包版本号抬高、重新出现 .taptap/meta.json 版本号低于线上包版本号）时，该判断自动失效、恢复提示。多次写入更高版本号会直接覆盖旧值，无副作用。

更新失败时无需回滚 version 字段。游戏可自行重试或修复，TapTap 不会因此次失败而重新提示更新。

提示

只需在热更新开始时写入版本号，更新完成或失败时无需额外处理。

首次接入后：清理开发者中心遗留的高版本包体

高风险提示

首次接入版本上报后，请务必检查 TapTap 开发者中心已上传包体的版本号，不要保留高于当前正式发布版本的包体版本号——否则线上包版本号被抬高，会触发误判提示。

附：完整流程时序

如需了解 TapTap 在启动时读取与判断的完整过程，可参考下图（仅作技术细节说明，接入时无需关注）：