Ad monetisation guide
Ad monetisation guide
Ads pay when players keep playing, and only run once your game is in full launch (basic launch is ad-free). Build the integration during basic launch so it is ready: in the portal an ad request before then fails with adsDisabled, which your code already has to handle. A design that earns today and loses players next week earns less in total. These patterns respect both. The binding rules are in advertisement rules; this page is how to do well inside them.
Midgame ads#
Choose the breaks#
Good: end of a level, return to the menu, after a game-over screen has been read, after a shop closes. Bad: right after a death in the middle of a streak, when the player just opened the game, on any button players press repeatedly.
Pace them#
The portal allows one midgame ad every three minutes by default, and any ad (rewarded too) restarts that timer. Do not try to hit exactly that:
- Make the first ad later than the cooldown, once the player has played a round. Players who see an ad in the first thirty seconds leave more.
- Count breaks (levels, runs), not seconds, and show an ad every second or third break.
- If a request fails (
unfilled,adCooldown), just continue. Do not retry immediately.
let breaks = 0;
async function onLevelEnd() {
await SDK.game.gameplayStop();
breaks++;
if (breaks % 2 === 0) await showMidgame();
showLevelSummary();
}Be clean#
Block clicks while the request is pending, pause and mute in adStarted, and resume on both adFinished and adError. After resuming, return focus to the game.
Rewarded ads#
Rewarded ads convert when the reward is obviously worth thirty seconds.
- Offer, don't push. Show the button on a screen where the player is already deciding: results screen ("double your coins"), a shop, or a continue screen.
- Be explicit. Name the reward on the button. Mark it as an ad.
- Always provide a no-ad route to the same reward, even if slower or smaller.
- Reward only after
adFinished. OnadErrorshow a friendly message and no reward. - Limit frequency. Cap how many rewards can be claimed per session or per timer. Rewards that never run out devalue themselves.
- Don't stack. No midgame ad directly followed by a rewarded offer between the same two levels.
async function onDoubleCoins() {
let ok = false;
await SDK.ad.requestAd("rewarded", {
adStarted: pauseAll,
adFinished: () => { ok = true; },
adError: () => {},
});
resumeAll();
if (ok) addCoins(runCoins); else toast("No ad available right now");
}Banners#
- Only on screens that stay open at least about five seconds: menus, level select, results.
- Never over the playfield or over a control.
- Clear them before gameplay (
clearAllBanners). - Do not request again inside 30 seconds; each container can refresh once per 30 seconds and a session has a cap of 60 refreshes.
- Banner requests while a video ad is on screen fail with
videoAdPlaying; request them again afteradFinished. - Make the layout work without a banner; they can fail or be disabled.
When to show what#
| Moment | Midgame | Rewarded | Banner |
|---|---|---|---|
| First 30 seconds of a first session | No | No | No |
| During active play | Never | Never | Never |
| Level or round complete, results read | Yes, every second or third break | Offer "double it" | Yes, on the results screen |
| Death or fail screen | After the screen was read, not instantly | "Continue" offer with a no-ad route | Yes |
| Shop, upgrade or pause menu | No | Offer a reward tied to what the player is looking at | Yes |
| Returning to the main menu | Yes, if the cooldown allows | Optional daily bonus | Yes |
| Loading screens | No | No | No |
The starter kits implement exactly this pattern.
Measure#
- Watch session length and retention alongside revenue in the console. If a change raises ad frequency and lowers day-1 retention, undo it.
- Change one thing at a time and give it a few days of traffic.
Adblock players#
They are still players. Check SDK.ad.hasAdblock(), hide the rewarded button or offer the alternative, and do not shame them.