Ad Placement API: prerolls, start placements and ad frequency
Place the first ad correctly with Google's Ad Placement API: the preroll call sequence, when to use start instead, data-ad-frequency-hint, and the placement policy.
The Ad Placement API guide covers setup and the next and reward placements used during play. This guide is about the first ad: the preroll placement Google provides for the moment before your game appears, the start placement for restarts, and how often ads can show. Everything comes from Google’s Ad Placement API documentation as of 2026-10-01, and the code is bundled and unit-tested in the site’s repository.
What a preroll is
In Google’s placement types, preroll covers the moment before your game has any UI on screen or any sound playing. Their scenario: a player picks your game from a catalogue, the empty canvas appears, and the ad runs before your menus or audio start. A page load can have only one preroll.
Because nothing of the game is visible yet, the API overview gives a preroll its own call sequence:
- Call
adBreak({ type: 'preroll', adBreakDone })early in your game logic, before the UI is rendered. Nothing in the game area should be clickable. - Do not pass
beforeAd()orafterAd(). There is no game to pause or mute yet, and passing them makes the call fail with an error in the console. - Start the game from
adBreakDone(), which is always called, whether or not an ad showed.
Two convenience behaviours come with it. A preroll always tries to preload ads, so you do not need adConfig({ preloadAdBreaks: 'on' }) for it. And it waits for the API to initialise, but only up to a two-second timeout, so a slow network cannot hold the game back indefinitely.
The helper
// file: examples/lib/adplacement-preroll.js
// Preroll for the Google Ad Placement API: one ad before the game renders its UI.
// Docs: https://developers.google.com/ad-placement/apis (Prerolls) and
// https://developers.google.com/ad-placement/docs/placement-types (checked 2026-10-01)
// Rules this helper follows:
// - call it early, before the game UI exists and before any sound;
// - pass only adBreakDone (beforeAd/afterAd make a preroll fail);
// - adBreakDone is always called, ad or not, so the game starts from there;
// - only one preroll per page load.
// It also covers the case the docs cannot: adsbygoogle.js never loads (blocked or offline). The
// inline shim then only queues calls and nothing ever answers, so the helper stops waiting and takes
// its placement back out of the queue, so that a late loader cannot show it in the middle of play.
let used = false;
/**
* @param {any} [api] the page's globals: adBreak/adConfig shim and the adsbygoogle queue
* @param {{ timeoutMs?: number, script?: { addEventListener(type: string, fn: () => void): void } | null }} [options]
* timeoutMs: how long to wait for the API to take the placement; script: the adsbygoogle.js element
* @returns {Promise<{ breakStatus: string }>} resolves when the game may render its UI
*/
export function runPreroll(api = globalThis, { timeoutMs = 5000, script = findLoaderScript() } = {}) {
if (used) return Promise.resolve({ breakStatus: 'invalid' }); // the API would reject a second preroll anyway
used = true;
if (typeof api.adBreak !== 'function') return Promise.resolve({ breakStatus: 'notReady' }); // shim missing
return new Promise((resolve) => {
let settled = false;
let apiReady = false;
/** @type {ReturnType<typeof setTimeout> | undefined} */
let timer;
const finish = (/** @type {{ breakStatus: string }} */ info) => {
if (settled) return;
settled = true;
if (timer !== undefined) clearTimeout(timer);
resolve(info);
};
const placement = {
type: 'preroll',
name: 'game-preroll',
// No preloading call needed: a preroll preloads and waits (with its own timeout) by itself.
adBreakDone: (/** @type {{ breakStatus: string }} */ info) => finish(info ?? { breakStatus: 'other' }),
};
const giveUp = () => {
dropQueued(api, placement);
finish({ breakStatus: 'notReady' });
};
// onReady is called once the API has loaded and initialised.
if (typeof api.adConfig === 'function') {
api.adConfig({
onReady: () => {
apiReady = true;
},
});
}
script?.addEventListener('error', giveUp); // blocked or failed download
api.adBreak(placement);
if (settled) return; // the API answered synchronously
// Still sitting in the shim's queue and no sign of the API: the loader never arrived.
timer = setTimeout(() => {
if (!apiReady && isQueued(api, placement)) giveUp();
}, timeoutMs);
});
}
function findLoaderScript() {
return globalThis.document?.querySelector('script[src*="pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"]') ?? null;
}
function isQueued(/** @type {any} */ api, /** @type {object} */ item) {
return Array.isArray(api.adsbygoogle) ? api.adsbygoogle.includes(item) : false;
}
function dropQueued(/** @type {any} */ api, /** @type {object} */ item) {
if (!Array.isArray(api.adsbygoogle)) return;
const i = api.adsbygoogle.indexOf(item);
if (i !== -1) api.adsbygoogle.splice(i, 1);
}
/** Test helper: allow another preroll (a new page load in real life). */
export function resetPrerollForTests() {
used = false;
}
It also covers three cases the docs imply but your code has to handle: a page where the shim is missing (you forgot it, or it was removed), a second preroll call in the same page load, which the API would reject with a breakStatus of invalid, and a shim whose adsbygoogle.js never loads (blocked or offline). In the last case nothing ever calls adBreakDone(), so the helper stops waiting when the script reports an error, or when its placement is still sitting unprocessed in the shim’s queue after a few seconds. It then removes that placement from the queue, so a slow loader cannot show the preroll later in the middle of play. Once the API has taken the placement, the helper waits for adBreakDone(), because an ad may be playing.
The example’s entry point awaits the preroll, then renders the game and creates the regular adapter for later breaks:
// file: examples/vanilla-adplacement-preroll/main.js
// Ad Placement API with a preroll, vanilla JS. Build: npm run examples:build, serve examples/dist/ on localhost.
import { runPreroll } from '../lib/adplacement-preroll.js';
import { createAdPlacementAdapter } from '../lib/adapters/adplacement.js';
import { startTapGame } from '../lib/tap-game.js';
// 1. Nothing is rendered and no sound plays until the preroll placement is done.
const info = await runPreroll();
console.info(`[example] preroll: ${info.breakStatus}`);
// 2. Now render the game. Later breaks use 'next' (level complete) and 'start' (restart).
const adapter = await createAdPlacementAdapter();
adapter.loadingStart();
adapter.loadingStop();
startTapGame({
canvas: /** @type {HTMLCanvasElement} */ (document.getElementById('game')),
overlay: /** @type {HTMLElement} */ (document.getElementById('overlay')),
adapter,
});
Top-level await keeps the order obvious: no game code runs before adBreakDone().
start: the first ad once the UI exists
start is for a game that has loaded, shows its UI and has sound enabled, where play has not started yet. The placement-types page draws the line: use preroll for the very first ad while the game is still loading, before the UI has rendered; use start once the UI is up and the player can interact. start can also be used when the game restarts, and unlike preroll there can be several per page load. The example game uses start for “Play again” after a game over and next between levels.
If a start placement is the first one in your game (you use no preroll), the same page notes you may need to request preloading yourself with adConfig({ preloadAdBreaks: 'on' }), or the first call may find no ad ready.
Sequencing without a preroll
If you prefer a start placement on a short loading screen, the manual sequencing page explains the risk: called right after page load, adBreak() may run before the API has initialised, and then adBreakDone() reports notReady. Its fix is the onReady callback of adConfig(), which fires once the tag has loaded, the API has initialised and (if requested) ads are preloaded. The same page then recommends a preroll for this case anyway, because the preroll already includes that waiting and timeout logic.
How often ads can show
The ad-rate page describes one client-side control, the data-ad-frequency-hint attribute on the adsbygoogle.js tag:
- the value is a duration such as
"60s", the minimum average time between ads; - the default is
"120s", so ads show no more than once every two minutes on average; - the fastest allowed rate is one ad every 30 seconds;
- the hint is not applied to the very first placement;
- Google may ignore or override the hint with server-side controls in future.
So you can place next and pause breaks at every natural transition and let the hint, not your own timers, decide how many actually show. When an ad is skipped for that reason, adBreakDone() reports frequencyCapped, one of the breakStatus values listed in the adBreak() reference.
Policy: where full-screen ads may not appear
The API documentation and the policy pages should be read together. AdSense’s H5 Games Ads guidance lists placements that are not allowed for full-screen ads, including ads that appear before the application or hosting page has opened where the player may believe clicking the ad is part of the startup sequence, ads after the game exits, ads directly after another full-screen ad, and ads that interrupt continuous play. It limits full-screen ads to ones created with adBreak() that appear between screens or at transitions between a games catalogue and an individual game.
The preroll placement is Google’s own mechanism for the moment before a game starts, and the API manages its loading and timeout. Our reading is that the clearest way to stay on the right side of the startup rule is to keep the page visibly a game page (title, canvas, nothing clickable that looks like a start button) while the preroll runs, and to start the game only from adBreakDone(). Google does not publish a more specific rule; if you are unsure about a layout, ask through your AdSense support channel.
What to check before you submit
- At most one
prerollcall per page load, made before any UI renders or sound plays. - No
beforeAdorafterAdon the preroll; the game starts fromadBreakDone(). - Restarts use
start; level transitions usenext; pauses usepause. - If your first placement is not a preroll, preloading is requested or
onReadyis used. data-ad-frequency-hintis set deliberately (or left at the default), and no custom ad timers exist.data-adbreak-test="on"is removed before release.- The game starts normally when
adsbygoogle.jscannot load (test with an ad blocker); the preroll does not wait forever.
Limits of this guide
This guide covers placement and frequency on the web. It does not cover H5 Games Ads inside Android apps through AdMob, the advanced reporting features, or how Google evaluates individual layouts against the policy. The helper was unit-tested against a mock of adBreak(); it has not shown real ads, which requires an approved H5 Games Ads account.
Questions
- Do I need to pause or mute the game for a preroll?
- No. A preroll runs before the game renders its UI or plays sound, so Google's docs say not to pass beforeAd() or afterAd() at all; passing them makes the call fail. Start the game from adBreakDone().
- What happens if the API is slow to load during a preroll?
- The preroll waits for the API to initialise and preload ads, but only up to a timeout of two seconds according to the API overview. adBreakDone() is always called, so the game still starts.
- Does data-ad-frequency-hint apply to the preroll?
- Google's ad-rate page says the frequency control is not applied to the very first ad placement, that is, the first adBreak() call.