Troubleshooting
Pe această pagină
Troubleshooting
First step for almost everything: add ?sdk_debug=true to the page URL and watch the browser console. Every SDK call, result and event is logged. Then repeat the run in the Preview tool, whose event log shows what reaches the portal.
SDK and environment#
| Symptom | Likely cause | Fix |
|---|---|---|
sdkNotInitialized |
A call ran before init() resolved. |
await SDK.init() once at startup before touching any other member. |
sdkDisabled, or SDK.environment is "disabled" |
The page is on a normal host and is not inside the portal frame, or the host did not answer the handshake. | Run on localhost, add ?useLocalSdk=true, or open the game in the Preview tool. Your game must still run when disabled. |
window.ZokoGames is undefined |
The script tag is missing, is after your code, or was blocked. | Load https://sdk.zokogames.com/zokogames-sdk-v1.js before your bundle. Check the network tab. |
| Works on localhost, not when uploaded | You rely on local-only behaviour (always-filled ads, fake user). | Re-test in the Preview tool and handle failures. |
timeout |
The portal did not answer a call within 10 seconds. | Check the page is really framed by the portal. Ad requests and prompts never time out. |
invalidArgument |
A wrong type or range. The message names the argument. |
Fix the call. Example: reportGameCompletedPercentage(150). |
Ads#
| Symptom | Likely cause | Fix |
|---|---|---|
adsDisabled |
Basic launch, kids' game, ads not enabled, or the provider is off. | Expected. Continue without an ad. |
adCooldown |
A midgame ad was requested less than three minutes after any ad. | Request at natural breaks only; do not add your own timers. |
unfilled |
No ad was available. | Continue the game. Try at the next break. |
| Game stuck paused after an ad | You resumed only in adFinished. |
Resume in adError too. |
| Reward granted for no ad | Reward given in adStarted or adError. |
Grant it only in adFinished. |
| Second request does nothing | Another request is already running; its adError gets other. |
Disable the trigger while waiting. |
Banners#
| Symptom | Likely cause | Fix |
|---|---|---|
notCreated |
No element with that id in the DOM yet. |
Create the container first. |
notVisible |
The container is display:none, zero sized, transparent or outside the viewport. |
Show it and give it a size before requesting. |
invalidSize |
Not in the static list (728x90, 300x250, 320x50, 468x60, 320x100). | Use a listed size or requestResponsiveBanner. |
noAvailableSizes |
Container smaller than every responsive size. | Make it at least 120 x 600, 320 x 50 or another listed size. |
bannerCooldown |
Same container requested again within 30 seconds. | Refresh less often. |
videoAdPlaying |
A video ad is on screen. | Request again after adFinished. |
| Request resolves but nothing shows | Banners are off for the game's stage. | Normal. Never depend on a banner being visible. |
Cloud save#
| Symptom | Likely cause | Fix |
|---|---|---|
dataLimitExceeded |
The whole save is over 1,048,576 bytes as JSON. | Store ids and numbers, not world snapshots. |
dataModuleDisabled |
The data module is not enabled for the game. | Tick the data option in the technical step of the submission. |
| Save resets after sign-in | The account already had a save, which wins. | Handle the reload prompt and merge in your own code. See cloud saves. |
| Last write lost on close | The tab was killed before the sync. | Writes flush on pagehide and when hidden; avoid very frequent tiny writes and save at checkpoints. |
Users, tokens and leaderboards#
| Symptom | Likely cause | Fix |
|---|---|---|
userNotAuthenticated |
A guest called a signed-in feature. | Offer showAuthPrompt() on a button, or continue as a guest. |
| Server rejects the token | Wrong key set, expired token, or wrong gameId. |
Verify RS256 against https://zokogames.com/.well-known/jwks.json, check exp and compare gameId. |
| Server rejects a local-mode token | Local tokens are unsigned (alg: none). |
Expected. Test against the Preview tool or a test-only bypass. |
rateLimited on listFriends |
Calls less than 250 ms apart. | Wait between pages. |
requestInProgress |
Another friends request is running. | Wait for it. |
| Score never appears on the board | Not signed in, outside the board range, inside the cooldown, wrong key or payload older than 2 minutes. The portal drops these silently. | Check each rule in leaderboards and encrypt at submission time. |
| Server API returns 401 | Missing or revoked key. | Send X-API-Key with the current key. |
Upload and review#
| Symptom | Likely cause | Fix |
|---|---|---|
| "index.html not found" | It is not at the zip root. | Zip the contents, not the parent folder (one top-level folder is accepted). |
| Blank page after upload | Absolute asset paths (/assets/x.png). |
Make every path relative. Set base: "./" in Vite. |
| Rejected file types | .php, .exe, .sh, .py, and similar. |
Remove them from the build. |
| Initial download too large | Everything is loaded before the first frame. | Lazy-load levels and audio. See first frame fast. |
| Case-sensitive 404s | Hero.PNG referenced as hero.png. |
Match the exact file name and case. |
| Keys scroll the page | Default actions not cancelled. | See scroll and keys. |
| Keyboard dead after an ad | The frame lost focus. | Call canvas.focus() in adFinished. |
Preview tool#
| Symptom | Fix |
|---|---|
| Game URL refused | Use an http or https address with no username or password, not a page on this site. |
Plain http game blocked on the https portal |
Serve over https or run it on localhost. |
| Checklist never ticks | The matching SDK call did not reach the portal. Read the event log, then check the call is made in the portal environment, not only in local mode. |
Still stuck? Send the game name, the stage, the steps and the sdk_debug console output through support.