# API Reference

Source: https://docs.ezoic.com/docs/webgames/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.

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

| Parameter | Type | Default | Description |
|---|---|---|---|
| `breakCooldownSec` | number | 5 | Minimum seconds between commercial breaks. `0` disables the cooldown; values above `3600` are clamped to `3600`. |

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.

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

| Parameter | Type | Default | Description |
|---|---|---|---|
| `position` | string | `'midgame'` | `'preroll'` or `'midgame'`. |
| `format` | string | `'auto'` | `'auto'` — video ad with display fallback. `'display'` — display ad only (quickest; good between levels). `'video'` — video ad only; resolves `{success: false, error: 'unfilled'}` when no video demand fills. |
| `onStart` | function | — | Called right before the ad displays. Pause gameplay and mute audio here — an auction runs first, so there can be a delay between the call and the ad appearing. |

**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.

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

| Parameter | Type | Default | Description |
|---|---|---|---|
| `rewardName` | string | `''` | Label for the reward, used for analytics. |
| `onStart` | function | — | Called right before the ad displays. |

**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.

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

| Parameter | Type | Default | Description |
|---|---|---|---|
| `width` | number | 320 | Maximum banner width in pixels. Capped at 970. |
| `height` | number | 50 | Maximum banner height in pixels. Capped at 250. |
| `anchor` | string | `'bottom'` | `'top'` or `'bottom'` edge of the game frame. |

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

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

## hideBanner()

Hides the banner shown by `showBanner()`.

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

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

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

| Code | Meaning |
|---|---|
| `adCooldown` | A commercial break was requested inside the cooldown window. The message states the seconds remaining. |
| `busy` | Another ad break — or another ad flow on the host page — is already in progress. |
| `unfilled` | The auction ran but no ad filled (for example `format: 'video'` with no video demand, or a banner box no standard size fits). |
| `noParent` | The game is embedded but no Ezoic bridge responded (environment `unavailable`). |
| `timeout` | The host page did not answer within the time limit. |
| `internal` | Unexpected failure, including calls made before `init()` resolved. |

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.