Introduction, init and errors
SDK introduction
The ZokoGames SDK is a small browser library that connects your game to the portal page that embeds it. Version 1.0.0 has six modules.
| Module | Purpose |
|---|---|
SDK.ad |
Midgame and rewarded video ads, adblock detection. |
SDK.banner |
In-game banner placements. |
SDK.game |
Gameplay events, loading, settings, rooms and invites. |
SDK.user |
Player identity, friends, tokens, sign-in and account linking. |
SDK.data |
Cloud save with a localStorage-shaped API. |
SDK.analytics |
Purchase tracking (in-game purchases are invite-only). |
Leaderboards use SDK.user.submitScore plus a server API, see leaderboards.
Loading#
<script src="https://sdk.zokogames.com/zokogames-sdk-v1.js"></script>
<script>
const SDK = window.ZokoGames.SDK;
</script>If you use a bundler, keep loading the script tag (the validator looks for it) and read the global. For TypeScript, copy src/zoko-sdk.d.ts from the html5-vite-ts starter kit: it declares window.ZokoGames and the types ZokoSdk, SdkError, PortalUser, GameSettings, SystemInfo and others.
init()#
init(): Promise<void>Resolves once the SDK has chosen an environment. Call it once, before anything else. It never rejects; a failed handshake leaves SDK.environment at "disabled" (or "local" when local mode applies).
await SDK.init();
if (SDK.environment === "disabled") return runStandalone();Other top-level members:
| Member | Type | Notes |
|---|---|---|
SDK.environment |
"local" | "zokogames" | "disabled" |
"disabled" before init() resolves. |
SDK.isQaTool |
boolean |
true when the page URL carries qaTool=true. |
Sync and async members#
Calls that cross the frame boundary return promises. In the portal, a few calls are accepted but not yet used for anything visible: game.reportGameCompletedPercentage, game.setGameContext and analytics.trackOrder. Keep calling them; they will start to matter without code changes. A handful of members read state that init() already loaded and are synchronous: SDK.game.settings, SDK.game.isInstantMultiplayer, SDK.game.inviteParams, SDK.game.getInviteParam, SDK.user.isUserAccountAvailable, SDK.user.systemInfo and the four SDK.data methods. Synchronous members throw the error object instead of rejecting.
Errors#
Every failure is a plain object, never an Error instance:
interface SdkError {
code: string; // stable, switch on this
message: string; // English, for logs
containerId?: string; // banner errors only: the container you passed
}try {
await SDK.user.getUserToken();
} catch (e) {
if (e.code === "userNotAuthenticated") continueAsGuest();
else console.warn(e.code, e.message);
}Ad errors are different in one way: they are delivered to your adError callback, not thrown (invalid arguments excepted). See video ads.
General codes#
| Code | When |
|---|---|
sdkNotInitialized |
A member was used before init() resolved. |
sdkDisabled |
The environment is disabled. |
invalidArgument |
A parameter has the wrong type or range. The message names it. |
timeout |
The portal did not answer within 10 seconds. Ad requests and auth prompts have no timeout because the player may take their time. |
Module codes#
| Module | Codes |
|---|---|
| Ad | adsDisabled, unfilled, adblock, adCooldown, other |
| Banner | bannersDisabled, unfilled, missingId, notVisible, noAvailableSizes, notCreated, videoAdPlaying, invalidSize, bannerCooldown, maxRefreshReached, other |
| User | userNotAuthenticated, userAlreadySignedIn, userCancelled, showAuthPromptInProgress, showAccountLinkPromptInProgress, rateLimited, requestInProgress, unexpectedError |
| Data | dataLimitExceeded, dataModuleDisabled, other |
Anything the SDK cannot classify is reported as other. Write your handlers so an unknown code takes the safe path (resume the game, continue as a guest).
Debugging#
Add ?sdk_debug=true to the URL to log every call and its result, in any environment. Combine it with the Preview tool.