This article provides notes and examples that demonstrate how to display a game manual interstitial ad using the Google Publisher Tag (GPT) library. Game manual interstitials are GPT-managed, full-page ads that are made visible to users via a manual trigger.
The following GPT events are used to display and interact with interstitial ads:
| Event | Fired when... |
|---|---|
|
|
A game manual interstitial ad slot is ready to be displayed. To display the interstitial, call |
The game manual interstitial can render fullscreen or inside the game frame, depending on how the game is displayed. Learn more about H5 Game Ad structures.
The sample code below assumes that the H5 game is directly placed on the same top frame as the page (using the "Fullscreen" structure). If that is the case, the manual interstitial ad will also render fullscreen.
However, this same code also works when placed inside of a child frame (using the "iFrame/WebView" structure). To constrain the manual interstitial ad to the H5 game canvas, the game will need to be placed in an iFrame.
Example
<!doctype html>
<html>
<head>
<!-- The Google Publisher Tag here, if any, will only be responsible for serving ads outside of the H5 game. -->
<title>Page for this example H5 game</title>
<!-- Your <head> content here. -->
</head>
<body>
<span id="example-text">Example H5 game</span>
<iframe src="https://www.example-game.com" title="Example game" allow="autoplay">
<!-- Sample code is served here. The Google Publisher Tag loaded in this frame will only be used within the H5 game. -->
</iframe>
</body>
</html>
Usage notes
- To ensure an optimal user experience, GPT only requests game manual interstitial ads on pages that properly support the format. Because of this,
defineOutOfPageSlot()may return null. You should check for this case to ensure you're not doing any unnecessary work. - Only request game manual interstitial ads on pages or environments where you want an interstitial to appear. Game manual interstitial ads are eligible to serve to desktop, tablet, and mobile devices.
- The interstitial appears when you call
makeGameManualInterstitialVisiblefrom theGameManualInterstitialSlotReadyevent. - Game manual interstitial ads have a fixed frequency cap. This prevents the
gameManualInterstitialSlotReadyevent from firing more than once every 120 seconds.
Requirements and recommendations
- Game manual interstitial ads generate their own ad slot. Unlike other ad types, it's not necessary to define a
<div>for game manual interstitial ads. These ads automatically create and insert their own container into the page when an ad fills. - If using single-request architecture (SRA) on a page with multiple slots, don't call
display()until static ad slots divs are created. As explained in Ads Best Practices, the first call todisplay()requests every ad slot defined before that point. Although game manual interstitial slots do not require a predefined<div>, static ad slots do. Callingdisplay()before these elements are present on the page can result in lower quality signals, so it is recommended that you delay the initial call until after static slots are defined. - Trafficking manual interstitials requires the same ad unit and line item setup as with standard web interstitials.
Example
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Game Manual Interstitial Ad Example</title>
<script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
<script>
window.googletag = window.googletag || { cmd: [] };
let gameManualInterstitialSlot;
googletag.cmd.push(function () {
// Define a game manual interstitial ad slot.
defineGameManualInterstitialSlot();
// Define static ad slots.
staticSlot = googletag.defineSlot(
'/6355419/Travel/Europe', [100, 100], 'static-ad-1')
.addService(googletag.pubads());
// Enable SRA and services.
googletag.pubads().enableSingleRequest();
googletag.enableServices();
});
function defineGameManualInterstitialSlot() {
gameManualInterstitialSlot = googletag.defineOutOfPageSlot(
'/6355419/Travel/Europe/France/Paris',
googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL);
// Slot returns null if the page or device does not support interstitials.
if (gameManualInterstitialSlot) {
gameManualInterstitialSlot.addService(googletag.pubads());
printStatus('Waiting for interstitial to be ready...');
// Add event listener to register click handler once interstitial loads.
// If this event doesn't fire, try clearing local storage and refreshing
// the page.
googletag.pubads().addEventListener('gameManualInterstitialSlotReady',
(slotReadyEvent) => {
if (gameManualInterstitialSlot === slotReadyEvent.slot) {
printStatus('Interstitial is ready.');
const button = document.getElementById('trigger');
button.style.display = 'block';
button.addEventListener('click', () => {
slotReadyEvent.makeGameManualInterstitialVisible();
printStatus('Interstitial is active.');
}, { once: true });
}
});
googletag.pubads().addEventListener('gameManualInterstitialSlotClosed',
resumeGame);
}
}
function resumeGame() {
document.getElementById('trigger').style.display = 'none';
// Game manual interstitial ad slots are one-time use, so destroy the old slot and create a new one.
googletag.destroySlots([gameManualInterstitialSlot]);
defineGameManualInterstitialSlot();
googletag.display(gameManualInterstitialSlot);
}
function printStatus(status) {
document.getElementById('status').innerText = status;
}
</script>
<style>
button {
display: none;
}
div.content {
position: fixed;
top: 50%;
}
</style>
</head>
<body>
<div id="static-ad-1" style="width: 100px; height: 100px;"></div>
<div class="content">
<span id="status">Game manual interstitial is not supported on this page.</span>
<p>
<button id="trigger">TRIGGER INTERSTITIAL</button>
</p>
</div>
<script>
googletag.cmd.push(function () {
// Ensure the first call to display comes after static ad slot
// divs are defined.
googletag.display(staticSlot);
});
</script>
</body>
</html>
