API Reference

All methods live on the global window.EzGameSDK, installed by gamesdk.js. Every method returns a Promise and never rejects — failures resolve with {success: false, error, message} so a missing ad can never break the game. Call init() before any other method; calls made before init() resolves return {success: false, error: 'internal'} (except hasAdBlock(), which resolves false).

Set EzGameSDK.debug = true to log SDK activity to the console.

init(config)

Initializes the SDK: detects the environment and, when embedded on an Ezoic page, performs the postMessage handshake with the host bridge. Safe to call multiple times — subsequent calls return the same promise, and the config is read only on the first call.

EzGameSDK.init({ breakCooldownSec: 5 }).then(function (info) {
  // info.environment: 'ezoic' | 'local' | 'unavailable'
});

When the game does not set breakCooldownSec, the host page's bridge can supply its own default during the handshake. A value set by the game always wins.

Resolves: {environment: string}

commercialBreak(config)

Shows a full-frame ad break covering the game's play area (not the whole host page). Use position: 'preroll' before gameplay starts and 'midgame' at natural pauses such as level transitions or game over.

EzGameSDK.commercialBreak({
  position: 'midgame',
  format: 'auto',
  onStart: function () { pauseGame(); muteAudio(); },
}).then(function (result) {
  // result: {success, watched} or {success: false, error, message}
  resumeGame();
});

Resolves: {success: true, watched: boolean} on success — watched is true when the user saw the ad through rather than skipping. On failure: {success: false, error, message}.

Only one break (commercial or rewarded) can run at a time; a second call while one is in progress resolves with error: 'busy'. Calls inside the cooldown window resolve with error: 'adCooldown' and a message stating the seconds remaining.

rewardedBreak(config)

Shows a rewarded ad. Rewarded ads must be user-opted-in: present them as a choice (a button or prompt that states the reward), never trigger them automatically, and never mislead the user about what they get.

EzGameSDK.rewardedBreak({ rewardName: 'extra_life', onStart: pauseGame })
  .then(function (result) {
    if (result.rewarded) {
      grantExtraLife();
    }
    resumeGame();
  });

Resolves: {success: true, rewarded: boolean} — rewarded is true only when the user watched the ad to completion. Grant the in-game reward only in that case. On failure: {success: false, rewarded: false, error, message}.

Rewarded breaks are not subject to the commercial-break cooldown, but they share the one-break-at-a-time rule (error: 'busy').

showBanner(config)

Shows a banner ad anchored to the top or bottom edge of the game frame.

width and height describe the maximum box the game reserves — not one exact size. The bridge offers every standard ad size that fits inside the box, and the ad server picks one supported on the current device. The promise resolves only after the ad server confirms a fill; when nothing fills the box (for example a mobile-only 320x50 box on desktop) it resolves {success: false, error: 'unfilled'} and no empty container is left behind.

EzGameSDK.showBanner({ width: 728, height: 90, anchor: 'bottom' })
  .then(function (result) {
    if (result.success) {
      shrinkPlayAreaForBanner();
    }
  });

Requested dimensions are capped at 970x250 — the largest standard banner size.

Resolves: {success: boolean, error?, message?}

hideBanner()

Hides the banner shown by showBanner().

EzGameSDK.hideBanner();

Resolves: {success: boolean, error?, message?}

gameplayStart() / gameplayStop()

Signal when active gameplay starts and stops (pause, level end, game over). While gameplay is active, the host page suppresses its own page-level interstitials so they never interrupt play, and the signals are recorded for analytics. Fire-and-forget — both always resolve.

EzGameSDK.gameplayStart();
// ... player is playing ...
EzGameSDK.gameplayStop();

Resolves: {success: boolean}

hasAdBlock()

Detects whether the user has an ad blocker. On Ezoic pages the check runs on the host page; elsewhere the SDK falls back to a local bait-element check inside the game frame.

EzGameSDK.hasAdBlock().then(function (blocked) {
  if (blocked) {
    showAdblockMessage();
  }
});

Resolves: boolean — true when an ad blocker is detected. Never rejects; detection failures resolve false.

Error codes

Failed calls resolve (never reject) with {success: false, error, message}:

When the host page disables the bridge with ezstandalone.config({gameSdk: false}) — or the game iframe is missing the data-ez-game attribute — the handshake is rejected, init() resolves with environment unavailable, and ad calls return error: 'noParent'.

Cooldown behavior

The cooldown is the minimum interval between commercial breaks (default 5 seconds). It is enforced on both sides: the SDK gates calls client-side, and the host bridge enforces it independently. Rejected calls resolve with error: 'adCooldown' without showing anything. rewardedBreak is exempt — a user who chose to watch an ad should never be blocked by a timer.

Configure it once in init({breakCooldownSec}); it cannot be changed per call.