This article provides notes and examples that demonstrate how to display a H5 gaming interstitial ad using the Google Publisher Tag (GPT) library. Gaming interstitials are GPT-managed, full-page ads that are made visible to users via a manual trigger on games that run on web pages.
The following GPT events are used to display and interact with gaming interstitial ads:
| Event | Fired when... |
|---|---|
|
|
A gaming interstitial ad slot is ready to be displayed. To display the interstitial, call |
|
|
A gaming interstitial ad slot that was being displayed is now closed. Used to execute custom logic whenever the gaming interstitial is closed. |
The gaming interstitial can render fullscreen or inside the game frame, depending on how the game is displayed. Learn more about H5 Game Ad structures.
The following sample code 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 gaming 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 gaming 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 gaming interstitial ads on pages that properly support the format. Because of this,
defineOutOfPageSlot()may return null. Only request gaming interstitial ads on pages or environments where you want an interstitial to appear. Gaming interstitial ads are eligible to serve to desktop, tablet, and mobile devices. - The interstitial appears when you call
makeGameManualInterstitialVisiblefrom thegameManualInterstitialSlotReady event. - Gaming interstitial ads have a fixed frequency cap. This prevents the
gameManualInterstitialSlotReadyevent from firing more than once every 120 seconds.
Requirements and recommendations
- Publishers are not allowed to use H5 gaming interstitial on non-gaming inventory. By implementing this format, publishers automatically agree to this condition. Google Publisher Policies and Google Ad Manager Partner Guidelines should also be adhered to.
- Google reserves the right to approve or disapprove publishers at any given time, and publishers found to be in violation will subsequently be taken out of the allowlist.
- Gaming interstitial ads generate their own ad slot. Unlike other ad types, it's not necessary to define a <div> element for gaming 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 gaming 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.
Get started
- Tagging
- Create a GPT slot using
googletag.defineOutOfPageSlot()and set the OutOfPage Format togoogletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL.
See the GPT technical developer guidance for H5 gaming interstitial. - Once the slot is defined, add an event-listener which listens for the
gameManualInterstitialSlotReadyevent. In the event-listener callback, call themakeGameManualInterstitialVisible()method on the provided event object to display the ad. - Once you've declared all other static ad slots, a call to
googletag.displaywill trigger a request for the gaming interstitial slot to fill.
- Create a GPT slot using
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>
Trafficking
- Create a new ad unit or re-use an existing one. Select 320x480, 300x250, and 336x280 as the ad unit size.
- Create line items. Select the appropriate line item settings based on your use case:
| Line item settings | ||||
|---|---|---|---|---|
| Use case | Ad type | Line item type | Expected creatives | Targeting > Inventory |
| To serve a reservation display ad | Display |
|
320x480, 300x250, or 336x280 |
The ad unit created or selected in the earlier step |
| To serve a non-reserved ad | Display |
|
||
| To serve a reservation video ad (eg a VAST tag or an MP4) | Video or audio |
|
300x250v or 320x480v | |
| To serve backfill / open auction ads | Display | Ad Exchange | All requested sizes | |