Migrating from another portal's SDK
Migrating from another portal's SDK
Most web game portals offer a similar SDK: init, ads, gameplay events, user, cloud save. The ZokoGames SDK deliberately uses the same shapes, so porting is mostly renaming a global and checking a few differences.
Two ways to port#
- Rename (recommended). Replace the other SDK's global with
window.ZokoGames.SDKand fix the differences below. You end up with clean code and no shim. - Compatibility shim (quick port). Load the shim instead of changing call sites. It exposes the object other portals' scripts use and forwards each call to the ZokoGames SDK.
Add the shim after the ZokoGames SDK and tell it which global name your game already reads, using the data-global attribute. You supply the name; the shim defines window.<name>.SDK.
<!-- quick port: load the ZokoGames SDK, then the shim -->
<script src="https://sdk.zokogames.com/zokogames-sdk-v1.js"></script>
<script src="https://sdk.zokogames.com/zokogames-compat-v1.js" data-global="YourOldGlobal"></script>The shim file is zokogames-compat-v1.js, served next to the SDK. You can also ship a copy inside your build zip and load it with a relative path (<script src="zokogames-compat-v1.js" data-global="YourOldGlobal">). data-global must be a plain identifier and cannot be window, document or ZokoGames. Besides forwarding every call to window.ZokoGames.SDK, it translates the differences below:
| Old shape | What the shim does |
|---|---|
Error code dataLimitExcedeed (misspelt) |
Our code is dataLimitExceeded. Errors that pass through the shim carry the old spelling, so existing switch statements keep working. |
game.isInstantJoin |
Alias of game.isInstantMultiplayer. |
game.showInviteButton(params) / hideInviteButton() |
Deprecated; mapped to game.updateRoom({ isJoinable, inviteParams }). showInviteButton resolves the invite link. |
game.sdkGameLoadingStart() / sdkGameLoadingStop() |
loadingStart() / loadingStop(). |
getEnvironment(cb) |
Calls cb(null, environment). |
Callback style, method(args, (error, result) => ...) |
Supported on every promise method. ad.requestAd also accepts (type, adStarted, adFinished, adError). |
SDK.environment equal to the old host's name |
Add data-environment="oldname" to the script tag and the shim reports that string in place of zokogames. local and disabled pass through. |
user.getXsollaUserToken() |
Rejects with { code: "other" }; not offered here. |
Store and third-party purchase calls are not shimmed, and the shim does not replace the engine wrappers: engine projects use the wrappers in the engines section. Prefer the rename route for new work; the shim is a bridge, not a place to stay.
Mapping table#
The left column is the usual shape of another portal's SDK. Names there vary slightly between portals; match them by meaning.
| Another portal | ZokoGames | Notes |
|---|---|---|
SDK.init() |
SDK.init() |
Same. Never rejects here; check SDK.environment. |
| Environment check | SDK.environment |
zokogames, local, disabled. |
ad.requestAd(type, callbacks) |
SDK.ad.requestAd(type, callbacks) |
Same callback names (adStarted, adFinished, adError). Types are "midgame" and "rewarded". |
ad.hasAdblock() |
SDK.ad.hasAdblock() |
Same. |
banner.requestBanner / requestResponsiveBanner |
SDK.banner.requestBanner({id,width,height}), requestResponsiveBanner(id) |
Check your sizes against banners. |
game.gameplayStart / gameplayStop |
SDK.game.gameplayStart / gameplayStop |
Same. |
game.loadingStart / loadingStop |
SDK.game.loadingStart / loadingStop |
Same. |
game.happytime |
SDK.game.happytime |
Same. |
| Completion percentage | SDK.game.reportGameCompletedPercentage(0..100) |
Out-of-range values throw. |
| Game context | SDK.game.setGameContext(obj), clearGameContext() |
Flat object, primitives only. |
| Settings and listener | SDK.game.settings, addSettingsChangeListener |
disableChat, muteAudio. |
| Rooms and invites | SDK.game.updateRoom, leftRoom, inviteLink, inviteParams, getInviteParam, addJoinRoomListener |
Invite params are flat string maps. |
user.getUser() |
SDK.user.getUser() |
null when logged out. The id field is __dangerousUserId. |
user.systemInfo |
SDK.user.systemInfo |
Same fields. |
user.getUserToken() |
SDK.user.getUserToken() |
Verify with our JWKS and check the gameId claim. |
user.showAuthPrompt() |
SDK.user.showAuthPrompt() |
Same error codes. |
user.showAccountLinkPrompt() |
SDK.user.showAccountLinkPrompt() |
Resolves { response: "yes" | "no" }. |
user.listFriends |
SDK.user.listFriends({page,size}) |
Size 1 to 50. |
| Cloud save | SDK.data.getItem/setItem/removeItem/clear |
Strings only; 1 MiB. Error dataLimitExceeded. |
| Purchase tracking | SDK.analytics.trackOrder(provider, order) |
Purchases are invite-only. |
| Leaderboard submit | SDK.user.submitScore({encryptedScore, score}) |
New key, see leaderboards. |
What changes#
- Script URL and global:
https://sdk.zokogames.com/zokogames-sdk-v1.jsdefineswindow.ZokoGames.SDK. - Token verification: change your server to fetch keys from
https://zokogames.com/.well-known/jwks.json, and compare thegameIdclaim to your ZokoGames game id. - Sitelock: allow
zokogames.comand*.zokogames.com. See technical requirements. - Branding: remove the other portal's logos, links and store badges. Cross-promotion rules are in gameplay requirements.
- Error codes: compare your
switchstatements with the lists in SDK introduction. - Leaderboards: scores need a new encryption key from the console; see leaderboards.
- Saves: existing players keep their old progress only if you migrate it yourself; see the
localStoragemigration snippet in data.
Test#
Run the game with ?sdk_debug=true, open it in the Preview tool and walk through ads, user, data and invites. The tool's checklist ticks as each call arrives.