Use this guide to learn how to integrate with the Google IMA HTML5 SDK to serve ads on HTML 5 web games with AdSense.
Overview of technical setup
AdSense for games operates using the Google Interactive Media Ads Software Development Kit (IMA HTML5 SDK). This SDK allows you to request AdSense ads through JavaScript in order to more closely combine content and advertising.
To request and render ads through the IMA HTML5 SDK, set up an ad request, load the resultant ad, and play it at the right time. Test your integration using the default publisher ID ca-games-pub-4968145218643279
.
Note that you must provide your account manager with an example of your integration before you are allowed to deploy ads to your site(s).
There are two options for integration, simple or advanced.
Simple integration
The simple integration option is the easiest way to integrate AdSense for games with your HTML5 games. This option provides a quick to implementation solution that provides all of the features and ad formats available across AdSense for games.
For publishers looking to use this simple integration option, you may register your interest.
Advanced integration
For publishers looking for a more advanced and custom integration, the full IMA HTML5 SDK should be implemented with your HTML5 game. This option provides additional flexibility such as certain features available via Google Ad Manager, but also keep in mind that this option brings additional complexity.
Getting started with advanced integration
To get started, integrate the IMA HTML5 SDK with your game.
- Setup IMA HTML5 SDK integration
Follow the guidelines on the Google Developer site to create an IMA HTML5 SDK integration with your game. There are steps to get started, along with downloadable sample code, and a full API reference to help.
- Setup ad container (
AdDisplayContainer)
As the IMA HTML5 SDK caters for both video and gaming publishers, the
AdDisplayContainer
object can be configured in multiple ways.When configuring the
AdDisplayContainer
object for use with AdSense for games, simply pass in the reference to the div that will contain the ad.Example:
var adDisplayContainer = new google.ima.AdDisplayContainer(document.getElementById('adContainer'));
- Configure ad request (
AdsRequest
)When creating the
AdsRequest
object, you must ensure that the relevant parameters and properties are configured correctly so that ads are returned and rendered properly.Example:
// Request AdSense for games ads.
var adsRequest = new google.ima.AdsRequest();
// Setup AdSense for games ad tag
adsRequest.adTagUrl = 'https://googleads.g.doubleclick.net/pagead/ads?ad_type=video_image_text&client=ca-games-pub-4968145218643279&videoad_start_delay=0&description_url=http%3A%2F%2Fwww.google.com&max_ad_duration=20000&adtest=on';
// Force image/text ads to render with Full-Slot UI
adsRequest.forceNonLinearFullSlot = true;
// Specify the linear and nonlinear slot sizes.
adsRequest.linearAdSlotWidth = {your_game_width};
adsRequest.linearAdSlotHeight = {your_game_height};
adsRequest.nonLinearAdSlotWidth = {your_game_width};
adsRequest.nonLinearAdSlotHeight = {your_game_height}; - Listen for relevant events and create callbacks
It's important to listen for events that are fired within the IMA SDK, so that you know when to stop showing the ad, and let your users continue playing your game.
Below are some of the ad events that are commonly used to determine the placement of ads with your game content. For example, you may listen for the
COMPLETE
event to understand when an ad has completed playback, and you can then show your game content to the user. A full list of ad events is available in the API reference.Event name Description AdEvent.Type.CLICK
Fired when the ad is clicked. AdEvent.Type.COMPLETE
Fired when the ad completes playing. AdEvent.Type.LOADED
Fired when ad data is available. AdEvent.Type.SKIPPED
Fired when the ad is skipped by the user. AdEvent.Type.START
Fired when the ad starts playing. AdEvent.Type.USER_CLOSE
Fired when the ad is closed by the user. AdErrorEvent.Type.AD_ERROR
Fired when an ad error event occurs.
There are many different types of ad errors that can occur. Examples include the failure to load ad media asset, or empty ad responses being returned on the ad requests. A list of possible errors is available in the API reference.