Skip to content
ZokoGames

Log in

Video ads

Video ads

SDK.ad shows full-screen video ads served by the portal. Two types exist:

  • midgame: shown at a natural break, such as between levels.
  • rewarded: the player opts in and receives something when it finishes.

Ads are served for games in full launch whose developer has enabled ads, and never for kids' games. In basic launch, in the QA frames and anywhere else ads are off, requestAd fails with adsDisabled; build your integration as if that can always happen. Only ads requested through the SDK are allowed. Read the advertisement rules before you design placements, and the monetisation guide for pacing.

requestAd#

requestAd(type: "midgame" | "rewarded", callbacks?: AdCallbacks): Promise<void>

interface AdCallbacks {
  adStarted?: () => void;
  adFinished?: () => void;
  adError?: (error: SdkError) => void;
}

The returned promise resolves after adFinished or adError has been called, never before. Exactly one of the two fires per request.

async function showMidgame() {
  await SDK.ad.requestAd("midgame", {
    adStarted: () => { game.pause(); audio.mute(); },
    adFinished: () => { audio.unmute(); game.resume(); },
    adError: (err) => { console.warn(err.code); audio.unmute(); game.resume(); },
  });
}
rewardButton.addEventListener("click", async () => {
  let earned = false;
  await SDK.ad.requestAd("rewarded", {
    adStarted: () => { game.pause(); audio.mute(); },
    adFinished: () => { earned = true; },
    adError: () => { earned = false; },
  });
  audio.unmute();
  game.resume();
  if (earned) grantExtraLife();
  else showMessage("No ad is available right now, try again later.");
});

Rules for callbacks#

  • Pause and mute inside adStarted, not when you call requestAd. The request may fail or take a moment; the player should not see a frozen game before the ad exists.
  • Resume in both adFinished and adError. A game stuck paused after a failed ad is the most common reason for a failed QA.
  • Never give a reward in adError.
  • Callbacks are wrapped, so an exception inside one does not break the SDK.

One ad at a time#

While a request is in progress a second requestAd does not start another ad; its adError callback receives { code: "other" }. Disable your trigger button while waiting.

Error codes#

Code Meaning What to do
adsDisabled Ads are off for this game: basic launch, a kids' game, ads not enabled, or the ad provider switched off. Continue without an ad, give no reward unless your design allows an alternative.
unfilled The portal started no ad. Continue; try again later.
adblock Reserved for an ad stopped by a blocker. Today the portal falls back to its own ad when a network ad cannot load, so detect blockers with hasAdblock() instead. Continue; see below.
adCooldown A midgame ad was requested within the cooldown (three minutes by default) of the previous ad of either type. Continue; the break was too early.
other Anything else, including a request already in progress. Continue.

An invalid type argument throws invalidArgument instead of calling adError.

Cooldown#

Midgame ads are limited to one every 180 seconds by default (the portal can set a different value per game). The timer starts whenever any ad starts, so a midgame request right after a rewarded ad is declined with adCooldown. Request midgame ads at natural breaks and let the portal decline when it is too soon; do not build your own timer around exactly three minutes. Rewarded ads are player-initiated and are never declined for cooldown.

hasAdblock#

hasAdblock(): Promise<boolean>

Resolves true when an adblocker is detected.

if (await SDK.ad.hasAdblock()) {
  rewardButton.title = "Rewarded ads are unavailable while an ad blocker is active.";
  showAlternativeReward();
}

Players with an adblocker must be able to play the whole game. You may disable features that depend on rewarded ads, with a short notice, and must offer another way to get the same reward. Do not show pop-ups asking players to turn the blocker off.

Local testing#

In local mode an ad is a 3-second overlay; in the portal it is an ad screen with a countdown. Either way, the callbacks run in the same order. adStarted fires when it appears and adFinished when it closes. Use it to check your pause, mute and resume paths, then repeat in the Preview tool, where real ad plumbing and failures occur.

Something unclear, wrong or missing on this page? Tell us through support · Test your game in the preview tool