Technical quick start guide (AFG)

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.

Note: These products are subject to the AdSense Terms & Conditions, AdSense program policies, and product-specific usage guidelines. Remember that inadvertent clicks originating from overly aggressive or faulty implementations will result in action up to (and including) account termination.

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.

1. 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.

2. 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'));

3. 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};

4. 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.