GameMonetize SDK: SDK_OPTIONS, showBanner() and pause events

GameMonetize distributes HTML5 games and shares ad revenue with developers (see the GameMonetize page for the published terms). Its HTML5 SDK is small: one configuration object, three events, one call to request an ad. This guide integrates it into the example game used across this site’s SDK guides and is explicit about the parts the documentation leaves open. Documentation checked on 2026-10-01.

Step 1: SDK_OPTIONS and the loader

The README asks you to add a script to index.html (head or body) that sets window.SDK_OPTIONS and then injects https://api.gamemonetize.com/sdk.js with the element id gamemonetize-sdk. SDK_OPTIONS has two fields:

• gameId: the game hash from your GameMonetize dashboard (Game Management, My games).
• onEvent(a): a callback that receives events with a name.

Step 2: the three events

The README’s mandatory settings:

• SDK_GAME_PAUSE fires every time a video ad is ready to play. Pause and mute the game; background audio during video ads is forbidden.
• SDK_GAME_START fires when the ad is done. Resume the game and unmute.
• SDK_READY fires when the SDK is ready.

The event names match GameDistribution’s, which is a common source of confusion. The difference is the configuration object: SDK_OPTIONS here, GD_OPTIONS there. The Portal Readiness Checker tells the two apart by that object and warns when both are in one build.

Step 3: request ads with showBanner()

To show an ad, the README calls sdk.showBanner(), guarded by a check that sdk exists, since an ad blocker can stop the script from loading. Despite its name, this is the call that triggers the video ad around which the pause and start events fire.

What the README does not say:

• whether showBanner() returns anything, such as a promise;
• how often ads may show, or whether the SDK limits frequency itself;
• where ads should be placed in the game flow (the blog post below covers this);
• any rewarded-ad API.

GameMonetize’s blog post on where to place ads fills part of the gap: it says GameMonetize does not allow ads on the initial game load and recommends the Play button and the win/lose screens. It is a blog post rather than developer terms. This guide follows that advice with the pattern every portal SDK on this site shares: request ads only at natural breaks after a player’s button press (level complete, game over), never during play and never on load.

Because no return value is documented, the adapter does not wait for showBanner(). It calls it and lets the events do the work: if an ad starts, SDK_GAME_PAUSE pauses the game wherever it is; SDK_GAME_START resumes it. If no ad shows, no event arrives and nothing needs undoing. That is exactly the model the README describes, and it avoids guessing a timeout.

The adapter

// file: examples/lib/adapters/gamemonetize.js
// GameMonetize HTML5 SDK adapter.
// Docs: https://github.com/MonetizeGame/GameMonetize.com-SDK (README) and https://gamemonetize.com/sdk
// (checked 2026-10-01). The SDK is configured through window.SDK_OPTIONS; ads are requested with
// sdk.showBanner() and the game is paused/resumed only through the SDK_GAME_PAUSE / SDK_GAME_START events.
// The README documents no return value for showBanner() and no rewarded-ad API.
import { gameplayGuard } from './types.js';

const SCRIPT_ID = 'gamemonetize-sdk';
const SCRIPT_SRC = 'https://api.gamemonetize.com/sdk.js';

/**
 * @param {{ gameId: string, win?: any, doc?: any, loadScript?: boolean }} options
 * @returns {import('./types.js').PortalAdapter}
 */
export function createGameMonetizeAdapter({ gameId, win = globalThis, doc = globalThis.document, loadScript = true }) {
  /** Hooks of the most recent break; ad events can arrive after showBanner() has returned. */
  /** @type {import('./types.js').BreakHooks | null} */
  let hooksForEvents = null;
  let pausedByAd = false;

  win.SDK_OPTIONS = {
    gameId,
    onEvent(/** @type {{ name: string }} */ a) {
      switch (a.name) {
        case 'SDK_GAME_PAUSE': // an ad is ready to play: pause AND mute (background audio is forbidden)
          if (hooksForEvents && !pausedByAd) {
            pausedByAd = true;
            hooksForEvents.pause();
          }
          break;
        case 'SDK_GAME_START': // the ad is done: resume
          if (hooksForEvents && pausedByAd) {
            pausedByAd = false;
            hooksForEvents.resume();
          }
          break;
      }
    },
  };

  if (loadScript && doc && !doc.getElementById(SCRIPT_ID)) {
    const first = doc.getElementsByTagName('script')[0];
    const js = doc.createElement('script');
    js.id = SCRIPT_ID;
    js.src = SCRIPT_SRC;
    first.parentNode.insertBefore(js, first);
  }

  const guard = gameplayGuard(
    () => {},
    () => {},
  );

  return {
    name: 'gamemonetize',
    loadingStart() {},
    loadingStop() {},
    ...guard,
    async commercialBreak(hooks) {
      guard.gameplayStop();
      hooksForEvents = hooks;
      // The README's own guard: the SDK may be missing (ad blocker) or not loaded yet.
      if (typeof win.sdk !== 'undefined' && typeof win.sdk.showBanner === 'function') {
        win.sdk.showBanner();
      }
      // Resolve right away: if an ad starts, SDK_GAME_PAUSE pauses the game, SDK_GAME_START resumes it.
    },
    async rewardedBreak() {
      // No rewarded-ad API is documented, so never offer a reward.
      return false;
    },
    onMuteRequest() {},
  };
}

rewardedBreak() always resolves false without showing a prompt. Offering a reward that cannot be delivered is worse than offering none, and portals that review reward UIs (Poki and CrazyGames, for example) reject reward buttons that do nothing.

The vanilla entry point:

// file: examples/vanilla-gamemonetize/main.js
// GameMonetize SDK example, vanilla JS. Build: npm run examples:build, then serve examples/dist/ on localhost.
import { createGameMonetizeAdapter } from '../lib/adapters/gamemonetize.js';
import { startTapGame } from '../lib/tap-game.js';

const adapter = createGameMonetizeAdapter({ gameId: 'YOUR_GAMEMONETIZE_GAME_ID' });
adapter.loadingStart();
// Load your assets here. This example has none, so loading ends immediately.
adapter.loadingStop();
startTapGame({
  canvas: /** @type {HTMLCanvasElement} */ (document.getElementById('game')),
  overlay: /** @type {HTMLElement} */ (document.getElementById('overlay')),
  adapter,
});
console.info(`[example] portal adapter: ${adapter.name}`);

The Phaser 3.90.0 build uses the same scenes as every other portal example; only main.js differs:

// file: examples/phaser-gamemonetize/main.js
// GameMonetize SDK example, Phaser 3. Build: npm run examples:build, then serve examples/dist/ on localhost.
import { createGameMonetizeAdapter } from '../lib/adapters/gamemonetize.js';
import { createPhaserGame } from '../lib/phaser-game.js';

const adapter = createGameMonetizeAdapter({ gameId: 'YOUR_GAMEMONETIZE_GAME_ID' });
createPhaserGame(adapter, 'game');
console.info(`[example] portal adapter: ${adapter.name}`);

Steps 4 and 5: upload, verify, request activation

From the README and the SDK page:

1. Zip the build so that index.html and the game files sit at the root of the zip, then upload it under Game Management, My games, your game.
2. Click Verify Game. The SDK page describes it as the check that shows whether the integration is correct and the game is ready to publish.
3. Click Request Activation. A content manager reviews and approves the game.

The root-of-zip rule is the most common upload mistake for any portal. The Portal Readiness Checker flags a zip whose index.html sits inside a folder, which happens when you zip the folder instead of its contents.

What to check before you submit

• SDK_OPTIONS.gameId is your real game ID, and the loader runs once, at startup.
• SDK_GAME_PAUSE pauses the game loop and mutes all audio, wherever the game is when it fires.
• SDK_GAME_START resumes and unmutes.
• sdk.showBanner() is called only from non-gameplay buttons, and guarded by the existence check.
• The game still works with an ad blocker (no sdk object).
• No reward buttons, unless GameMonetize documents a rewarded API you have integrated.
• index.html is at the root of the zip; Verify Game passes before you request activation.

Limits of this guide

Everything here comes from the HTML5 README and the public SDK page. GameMonetize also offers SDKs for Construct 2 and 3 and Unity, which this guide does not cover. The SDK script itself is minified, so behaviour beyond the README (return values, frequency capping) is not described. The adapter was unit-tested against a mock that fires the documented events; it has not been run against GameMonetize’s live ads.