Game Self-Update Version Reporting

This page is the integration guide for TapTap PC Game Update Mechanism. It applies to games that complete version upgrades through their own self-update (such as a built-in launcher). For the principle behind version-number comparison, see the update mechanism.

When a game upgrades itself through its own self-update, the files are not reinstalled through TapTap, so the version number in .taptap/meta.json does not change automatically. If left unhandled, TapTap will repeatedly prompt "Update game" because the .taptap/meta.json version is lower than the live package version. The fix: when the self-update starts, write the version number in .taptap/meta.json to the target version so that it is not lower than the live package version, and TapTap stops prompting.

Integration takes two steps: place .taptap/meta.json inside the game package; when the self-update starts, write its version number to the target version. In addition, before first integration you need to check the version numbers of packages already uploaded to the Developer Center, to avoid misjudgments caused by historical test packages.

The .taptap/meta.json file

The game package must contain a .taptap/meta.json file, placed in the same directory as the launch entry configured in the TapTap Developer Center. When you upload the package, the TapTap backend automatically extracts the version number from this file — no manual entry is needed.

Do not change this path

The TapTap client relies on the fixed path .taptap/meta.json (relative to the launch-entry directory configured in the Developer Center) to read version information. If the path is moved or renamed, TapTap cannot correctly identify the game version, which may cause duplicate update prompts.

File format:

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

Field descriptions:

Field	Description
version	Game version number, format vX.X.X; see "Version number format" below. When the game self-updates, this field must be written to the target version number.
app_id	The game's numeric ID on TapTap, visible in the TapTap game page URL, e.g., taptap.cn/app/12345. TapTap validates this field on upload to prevent uploading a package to the wrong game.

We recommend generating this file automatically in your CI/CD build process to keep the version number consistent with the build version. Manual maintenance is also fine, but you must update the version field on every release.

Version number format

The version number in .taptap/meta.json must use the same format as the version number uploaded to the Developer Center; otherwise the comparison cannot be done correctly.

Version number format

The format is vX.X.X, e.g., v1.0.0, v1.2.3. Version numbers that do not match the format cannot be correctly recognized by TapTap.

• X.X.X is three numeric segments separated by dots, each a non-negative integer.
• The v prefix must be lowercase.
• Comparison rule: compare segment by segment from left to right, e.g., v1.2.3 < v1.2.4 < v1.3.0 < v2.0.0.

Write the target version when the self-update starts

When the game detects a new version and starts its self-update (not when the update completes), write the version field in .taptap/meta.json to the target version — the version it is about to update to, not the currently installed version. For example, if the target version is v1.3.0:

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

Once written, the .taptap/meta.json version is not lower than the live package version, and TapTap no longer shows the "Update game" button. When the Developer Center later sets a higher version as live (the live package version rises and the .taptap/meta.json version becomes lower again), this judgment automatically becomes invalid and the prompt resumes. Writing a higher version number multiple times simply overwrites the old value, with no side effects.

You do not need to roll back the version field when an update fails. The game can retry or repair on its own, and TapTap will not re-prompt an update because of that failure.

tip

You only need to write the version number when the self-update starts; no extra handling is needed when the update completes or fails.

After first integration: clean up high-version packages left in the Developer Center

High-risk warning

After integrating version reporting for the first time, be sure to check the version numbers of packages already uploaded to the TapTap Developer Center. Do not keep any package with a version number higher than the current official release — otherwise the live package version is raised and triggers false prompts.

Appendix: Full process sequence

If you want to understand the complete process TapTap goes through to read and judge at launch, see the diagram below (for technical reference only; not something you need to worry about during integration):