Introduction
The Ezoic Game SDK lets HTML5 games embedded in an iframe on your site show ads that are auctioned and served against your hosting domain's ads.txt. This is the standard pattern the industry uses to monetize distributed games: the game itself can live on a game CDN or portal at a different origin, but the ads come from whatever site the game is currently embedded on.
The SDK gives games the game-specific ad calls they need: commercialBreak for mid-game and pre-roll ads, rewardedBreak for opt-in ads that grant an in-game reward, and showBanner / hideBanner for persistent banner units anchored to the play area. Games don't need their own ads.txt, dashboard setup, or placeholders. All of that stays on the hosting site.
This is what makes distributable games monetizable at scale. A single game can run on many sites, and each site earns from its own ad demand.
Instructions
Your site needs the standard Ezoic JavaScript integration in place, plus one addition: mark the game's iframe with the data-ez-game attribute so the SDK bridge recognizes it.
<iframe src="https://games.example-cdn.com/my-game/index.html"
data-ez-game
allow="autoplay; fullscreen"></iframe>The bridge only responds to iframes carrying that attribute. Unmarked iframes are ignored.
Game-Side Setup
Inside the game (which can be hosted on a completely different domain), load the SDK and call EzGameSDK.init():
<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) {
startGame();
});
});
</script>Then trigger ads at natural pause points in gameplay:
// Pre-roll before the game starts
EzGameSDK.commercialBreak({ position: 'preroll', onStart: pauseGame })
.then(resumeGame);
// Between levels
EzGameSDK.commercialBreak({ position: 'midgame', format: 'display', onStart: pauseGame })
.then(resumeGame);
// Opt-in rewarded ad
EzGameSDK.rewardedBreak({ rewardName: 'extra_life', onStart: pauseGame })
.then(function (result) {
if (result.rewarded) grantExtraLife();
resumeGame();
});
// Persistent banner
EzGameSDK.showBanner({ width: 320, height: 50, anchor: 'bottom' });Cooldowns Between Ad Breaks
The SDK enforces a 5-second cooldown between commercialBreak calls by default. If your game calls commercialBreak again before the cooldown has passed, the SDK resolves the promise with { success: false, error: 'adCooldown' } instead of showing an ad, so gameplay is never blocked by a rapid-fire ad request.
You can adjust the cooldown when initializing the SDK:
EzGameSDK.init({ breakCooldownSec: 10 });Detecting Ad Blockers
The SDK exposes a hasAdBlock() method that tells you whether the current player is running an ad blocker. Use it to swap in a fallback experience (a message, an alternate reward path, or a prompt to disable the blocker) instead of relying on ad calls that will never fill:
EzGameSDK.hasAdBlock().then(function (blocked) {
if (blocked) {
showAdBlockFallback();
}
});For the full API reference (every method, parameter, result shape, and error code), see the Web Games API Reference.
FAQs
Does the game need its own ads.txt?
No. All ads render against the hosting site's ads.txt. The game itself needs no ads.txt, no dashboard setup, and no placeholders.
Can the game run at a different origin than the host page?
Yes. That's the primary use case. Games are typically served from a CDN or portal at a different domain, embedded via iframe on the hosting site. The SDK bridges the two via postMessage so the game can request ads that render on the host's domain.
Can I test the SDK locally before deploying?
Yes. If the game is opened directly (not inside an iframe), the SDK detects local mode and returns simulated ads with the same success and failure shapes as production. You can develop and test the full ad flow offline.
What happens if the game is embedded somewhere that isn't Ezoic-integrated?
The SDK detects the missing bridge and returns unavailable. Ad calls resolve quickly with a failure result so the game keeps running without hanging.
Are rewarded ads required to be user-initiated?
Yes. Rewarded ads must always be triggered by an explicit user action (a button, a menu prompt, etc.) and never triggered automatically. Grant the reward only when the SDK returns rewarded: true.
Why did my commercialBreak call return success: false with an adCooldown error?
The SDK enforces a 5-second minimum gap between commercialBreak calls by default. If your game requests two ads too close together, the second one resolves as adCooldown and no ad is shown. This is a safeguard to prevent poor player experience. If your game genuinely needs a different cadence, pass a custom value with EzGameSDK.init({ breakCooldownSec: X }).
Where can I see a live example?
Working live integrations are at examples.ezoic.com/game-sdk with copyable source, and usconstitution.net/game-sdk-demo for a fully playable version.
Contact Information for Further Assistance
If you need further assistance with the Ezoic Game SDK, please log in via support.ezoic.com to make use of our dedicated resources for support. We're here to help!
