Versioning and migration notes
Op deze pagina
Versioning and migration notes
The script URL is the contract#
https://sdk.zokogames.com/zokogames-sdk-v1.jsThe v1 in the file name is the major version. Inside a major version the SDK stays backwards compatible: methods, argument shapes, return values and error codes you already use keep working. The current release is 1.0.0 and the exact number is exported as SDK_VERSION in the bundle (the SDK sends it to the portal during the handshake).
What may change inside v1 without notice:
- New methods, new optional arguments and new fields on returned objects.
- New error codes. Always keep a default branch in
switch (e.code)that takes the safe path. - Calls that are accepted but not yet used by the portal (
reportGameCompletedPercentage,setGameContext,trackOrder) start doing something. - Bug fixes and stricter validation of arguments that were already documented as invalid.
What requires a new major version (v2) and a long overlap:
- Removing or renaming a method, argument or documented error code.
- Changing the meaning of an existing return value.
- Changing the wire protocol in a way old SDK builds cannot answer.
The portal checks the protocol version during init(). A game built against v1 keeps working while v1 is served.
Do not self-host an old copy#
Load the script from the URL above rather than copying it into your build, so fixes reach your players. If you must bundle a copy (an offline build), keep the ZokoGames global name so the upload validator still recognises the SDK, and update the copy whenever the changelog lists a release.
Migration notes#
1.0.0 (first release)#
There is nothing to migrate from earlier ZokoGames versions. If you come from another portal's SDK, use the migration guide. The points that bite most often:
- Errors are plain
{ code, message }objects, notErrorinstances. Usee.code, note instanceof Error. init()never rejects. CheckSDK.environmentinstead of catching.SDK.datamethods are synchronous and throw, they do not return promises.getUserTokenacceptssigningKeyTypefor ported code but signs every token the same way (RS256, one key set).__dangerousUserIdis for display only. Identify players on your server through the verified token.- There is no client store or purchase API. See in-game purchases.
Engine wrappers#
Wrappers share one browser bridge with the JavaScript SDK. When you update a wrapper, re-export your web build and re-test in the Preview tool. Wrapper-specific changes are listed on each engine page and in the changelog.
How to upgrade safely#
- Read the changelog for the release.
- Run the game with
?sdk_debug=trueand look for new warnings. - Check error handling still takes the safe path for unknown codes.
- Test in local mode, then in the Preview tool, then in a build preview from the console.
- Ship the update. See updating a live game.