# Getting Started

Source: https://docs.ezoic.com/docs/webgames/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](/docs/ezoicads/integration/) and at least one `showAds()` call, which loads the ad pipeline the game bridge delegates to:

```html
<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:

```html
<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`):

```html
<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:

| Environment | Meaning | Ad behavior |
|---|---|---|
| `ezoic` | Embedded on a page whose Ezoic bridge answered the handshake | Real ads, rendered by the host page |
| `local` | Running as the top window (opened directly / local development) | Simulated ads, so the game is fully testable without Ezoic |
| `unavailable` | Embedded in a parent frame but no bridge responded | Ad calls resolve quickly with `{success: false, error: 'noParent'}` so the game keeps running |

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:

```javascript
// 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`:

```javascript
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:

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

See the [API Reference](../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](https://examples.ezoic.com/game-sdk/), with copyable source.