Getting Started

The Game SDK has two sides:

1. The host page — the ads.txt-approved website that embeds the game. It runs the standard Ezoic JavaScript integration. All auctions run here, and all ads render here (confined to the game's play area), because this is the domain advertisers bid on.
2. The game — an HTML5 game running inside an iframe, usually served from a different origin (a game CDN or portal). It loads gamesdk.js and calls the EzGameSDK API. Every call is proxied to the host page over a postMessage bridge.

The game never runs an auction itself and needs no ads.txt, no dashboard setup, and no placeholders of its own.

Host page setup

The host page needs the standard Ezoic JavaScript integration and at least one showAds() call, which loads the ad pipeline the game bridge delegates to:

<script data-cfasync="false" src="https://cmp.gatekeeperconsent.com/min.js"></script>
<script data-cfasync="false" src="https://the.gatekeeperconsent.com/cmp.min.js"></script>
<script async src="//www.ezojs.com/ezoic/sa.min.js"></script>
<script>
    window.ezstandalone = window.ezstandalone || {};
    ezstandalone.cmd = ezstandalone.cmd || [];
    ezstandalone.cmd.push(function () {
        ezstandalone.showAds();
    });
</script>

Then embed the game with the data-ez-game attribute. The bridge only answers frames that carry this attribute — handshakes from unmarked iframes are rejected:

<iframe src="https://games.example-cdn.com/my-game/index.html"
        data-ez-game
        allow="autoplay; fullscreen"></iframe>

That is the entire host-page integration. If the host page ever needs to turn the bridge off, it can call ezstandalone.config({ gameSdk: false }).

Game-side setup

Inside the game, load the SDK and queue your startup code on EzGameSDK.cmd. The queue pattern means your code runs whether it executes before or after gamesdk.js finishes loading (the same pattern as ezstandalone.cmd):

<script src="https://www.ezojs.com/ezoic/gamesdk.js"></script>
<script>
  window.EzGameSDK = window.EzGameSDK || {};
  window.EzGameSDK.cmd = window.EzGameSDK.cmd || [];

  window.EzGameSDK.cmd.push(function () {
    EzGameSDK.init().then(function (info) {
      console.log('Game SDK ready, environment:', info.environment);
      startGame();
    });
  });
</script>

init() detects the environment and, when embedded on an Ezoic page, performs the handshake with the host bridge. It resolves with one of three environments:

Your game logic does not need to branch on the environment — the same API surface and the same success/failure shapes apply in all three.

Your first ad break

Call commercialBreak() at natural pauses. Use the onStart callback to pause gameplay and mute audio — it fires right before the ad actually displays:

// Before gameplay starts
EzGameSDK.commercialBreak({ position: 'preroll', onStart: pauseGame })
  .then(function (result) {
    resumeGame();
  });

// Between levels — display format keeps it quick
function onLevelComplete() {
  EzGameSDK.commercialBreak({ position: 'midgame', format: 'display', onStart: pauseGame })
    .then(function (result) {
      resumeGame();
    });
}

Rewarded ads must always be the user's choice — offer them through a button or prompt, never trigger them automatically. Grant the reward only when rewarded is true:

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

And a banner anchored to the edge of the game frame:

EzGameSDK.showBanner({ width: 320, height: 50, anchor: 'bottom' });

See the API Reference for every method, parameter, result shape, and error code.

Testing

• Local development: open the game directly (not in an iframe). The SDK runs in local mode and every ad call shows a simulated ad that resolves with the same result shapes as production, so you can develop the full ad flow offline.
• Live example: a working cross-origin integration — real game, real host page, live bridge log — is at examples.ezoic.com/game-sdk, with copyable source.