Mobile applications

Developing ads for the Google Mobile Ads SDK

The Android Google Mobile Ads SDK with support for DFP has moved into the Play Services SDK. Minor code changes are necessary to migrate to the new SDK.

All new or updated apps submitted to the Play Store after August 1, 2014 must use the new SDK. Ad serving to existing apps will not be affected.

To take advantage of the functionality of the Google Mobile Ads SDK, you can use the JavaScript functions exposed by the google.mobile.app.ads class. You must include the following code in the <head> section of the creative:

<script type="text/javascript" src="http://media.admob.com/api/v1/google_mobile_app_ads.js"></script>.

The Google Mobile Ads SDK supports the IAB's Mobile Rich Media Ad Interface Definitions (MRAID) standard for advertising in mobile applications. MRAID is supported on Android OS v4.0+ and all versions of iOS. Learn more about MRAID and related resources in our blog post.

Access to device capabilities

The SDK also exposes the capabilities of the in-app browsers available on iOS and Android. This allows developers to access device capabilities such as the accelerometer, gyroscope and compass via HTML5 where the platform supports them. Please refer to the documentation for each platform for more information on these capabilities and how to access them.

App events

App events enable you to execute custom code in your application when a creative dispatches an app event. With app events, you can introduce custom ad executions that interact with the application, such as changing the background color of the app.

Learn how to implement app events.

Scaling image to full screen

If you find that your full screen ad is only taking up part of the screen, insert the following code in the <head> section of the creative:

<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no"/>.

Sample code for a rotatable ad

You can use the code below to serve a rotatable ad.

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=0">
    <style>
      * {
        padding: 0px;
        margin: 0px;
        border: none;
      }

      a { display: block }

      #landscape{ display: none; }

      /* Portrait */
      @media screen and (orientation:portrait) {
        #portrait { display: block; }
	#landscape { display: none; }
      }
      /* Landscape */
      @media screen and (orientation:landscape) {
        #portrait { display: none; }
	#landscape { display: block; }
      }
    </style>
  </head>
  <body>
    <a href="%%CLICK_URL_UNESC%%[%ClickThroughURL%]">
      <img id="portrait" src="[%PortraitImageFile%]" width="[%PortraitImageWidth%]" height="[%PortraitImageHeight%]"/>
      <img id="landscape" src="[%LandscapeImageFile%]" width="[%LandscapeImageWidth%]" height="[%LandscapeImageHeight%]"/>
    </a>
  </body>
</html>

Sample code for an expandable ad (MRAID)

MRAID example

For more information, please refer to the MRAID API documentation.

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="user-scalable=no, width=device-width,initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"/>
    <script type="text/javascript" src="mraid.js"></script>
    <style type="text/css">
      html, body {
        margin: 0;
        padding: 0;
      }

      .banner, .overlayBanner {
        display: block;
        position: absolute;
        top: 0px;
        left: 0px;
        z-index: 1000;
        overflow: hidden;
      }

      .banner {
        background-color: black;
        width: 300px;
        height: 50px;
      }

      .overlayBanner {
        background-color: green;
        width: 300px;
        height: 250px;
      } 
    </style>
    <script type="text/javascript">
      // Check to see if document is ready
      if ((mraid.getState() != "default") || (mraid.getState() != "ready")) {
        // console.log("Document is not ready, adding event listener");
        // Register event listener to keep track of state changes
        mraid.addEventListener("stateChange", handleStateChanges);
      } else {
        // console.log("Document is ready");
        // Register event listener to keep track of state changes
        mraid.addEventListener("stateChange", handleStateChanges);
      }

      function handleStateChanges() {
        // console.log('mraid state: ' + mraid.getState());
        // Perform action on state change
        switch(mraid.getState()) {
        case "expanded":
          // console.log("handleStateChanges, expanded");
          // Show the overlay banner when view is in "expanded" state
          document.getElementById('banner').setAttribute('class', 'overlayBanner');
          break;
        case "default":
          // console.log("handleStateChanges, default");
          // Show the initial banner when view is in "default" state
          document.getElementById('banner').setAttribute('class', 'banner');
          break;
        }
      }
</script>
</head>

<body>
<div id='banner' onClick='mraid.expand()'></div>
</body>

</html>

Non-MRAID example, using creative templates

You can use the sample code below to serve a banner to a mobile application. On click, the banner expands to a full-screen unit displayed in an overlay window inside the application. In the sample code, replace the following placeholder elements with your own values:

  • [FALLBACK_CLICKURL]: Backup landing page in case JavaScript function doesn't get called.
  • [FULLSCREEN_UNIT]: URL of full screen ad unit.
  • [ORIENTATION]: Supported orientation for full screen unit (use "p" for portrait, "l" for landscape, or omit this value to allow any orientation).
  • [BANNER_UNIT]: URL of banner image.
  • [WIDTH]: Width of banner.
  • [HEIGHT]: Height of banner.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="user-scalable=no, width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"/>

<script type="text/javascript" src="http://media.admob.com/api/v1/google_mobile_app_ads.js"></script>
</head>

<body>
<a href="[FALLBACK_CLICKURL]" onClick="admob.opener.openOverlay('%%CLICK_URL_ESC_ESC%%[FULLSCREEN_UNIT]', '[ORIENTATION]'); 
return false;"><img border="0" src="[BANNER_UNIT]" width="[WIDTH]" height="[HEIGHT]"></a>
</body>

</html>

Sample code for automatically closing an interstitial

Only directly-booked interstitials can be automatically closed; interstitials served via dynamic allocation (i.e., Ad Exchange, AdSense or AdMob) can only be dismissed by the user.

To make an interstitial close after a fixed period of time:

  • Include code in the creative to close the interstitial after a fixed period of time has elapsed. The following code can be used as a template for this approach:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="user-scalable=no, width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"/>
      <script type="text/javascript" src="http://media.admob.com/api/v1/google_mobile_app_ads.js"></script>
      <script>
        <!--
          function
          _admStartCountDown(){setTimeout('admob.opener.close()',parseInt('[%displayTime%]')*1000)}
          function
          _admOnload(){if(admob.opener.isOverlayShowing()){_admStartCountDown()}else{admob.events.addEventListener('onshow',
          _admStartCountDown)}}
          if(window.addEventListener){window.addEventListener("load",_admOnload,false)}else{window.attachEvent("onload",_admOnload)}
        //-->
      </script>
  </head>
  <body>
    [Your_AdCode_Goes_Here]
  </body>
</html>

Target window: in-app overlay window (iOS)

Using admob.opener.openOverlay(), you can open a full screen overlay browser that is animated from the bottom of the screen. This browser does not include a status bar and always displays a close button at the upper-left corner. This option can work nicely for an expandable ad where the full screen unit can be hosted on a separate page (see the sample code for an expandable ad).

Below is sample code for a simple banner where the full screen unit can be loaded into an overlay browser window. You should replace the following placeholder elements with your own values. If available for your network, you can use the sample code to create a creative template.

  • [BANNER_UNIT]: URL of a banner creative.
  • [WIDTH]: Width of a banner creative.
  • [HEIGHT]: Height of a banner creative.
  • [FULLSCREEN_UNIT]: URL of a full screen creative. Note: Full screen unit should include JavaScript code to parse the destination URL and redirect the user to the landing page upon receiving a click action. See Handling destination URL from a full screen unit for more details.
  • [DESTINATION_URL]: URL of a destination page.
  • [FALLBACK_URL]: Fallback destination URL to use in case JavaScript function doesn't execute.
  • [ORIENTATION]: Supported orientation for destination URL (use "p" for portrait, "l" for landscape, or omit this value to allow any orientation).

Here's a sample creative code:

<!DOCTYPE html>
<head>
<meta name="viewport" 
content="user-scalable=no, width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"/>

<script type="text/javascript" src="http://media.admob.com/api/v1/google_mobile_app_ads.js"></script>
</head>

<body>
<a href="[FALLBACK_CLICKURL]" 
onClick="admob.opener.openOverlay('%%CLICK_URL_ESC%%[FULLSCREEN_UNIT]?destination=[DESTINATION_URL]', 
'[ORIENTATION]'); return false;"><img border="0" 
src="[BANNER_UNIT]" width="[WIDTH]" height="[HEIGHT]"></a>
</body>
</html>

Handling destination URL from a full screen unit

The admob.opener.openOverlay() function does not have the option to specify the destination URL of the html content. Assuming that you've passed the destination URL in the form of key/value pair when specifying the fullscreen unit, e.g. "http://link.to.fullscreen.unit?destination=http://my.destination.url", you can write a simple JavaScript function and include a snippet of HTML code to capture the click and redirect the user to the destination page.

 

Here's a sample page source:

<!DOCTYPE html>
<head>
<meta name="viewport" 
content="user-scalable=no, width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"/>

<script type="text/javascript" src="http://media.admob.com/api/v1/google_mobile_app_ads.js"></script>

<script type="text/javascript">
function destinationUrl() {
  // Get current url after ?
  var destinationUrl = window.location.search;

  // Strip off the leading '?'
  destinationUrl = destinationUrl.substring(1);
  // Parse destination=url key/value pair
  var kvPair = destinationUrl.split("=");
  var key = kvPair[0]; // key: destination
  var value = kvPair[1]; // value: url
  var url = decodeURIComponent(value); 

  // Open destination inside overlay
  window.location = url;

  // Open destination in an external browser
  // admob.opener.openUrl(url, true);
}
</script>
</head>

<body>
<div style="position:relative;">
<!-- Load content source into an iframe -->
<iframe src="http://creative.admob.com/t1/bestBuy/tradeinJul/gi/" 
align="middle" frameborder=0 width=320 height=480 marginheight=0 marginwidth=0 scrolling=no></iframe>
<!-- Create a clickable area -->
<a href="#" onClick="destinationUrl(); return false;" style="position:absolute; top:0; left:0; 
display:inline-block; width:320px; height:480px; z-index:5;"></a>
</div>
</body>
</html>

Target window: new browser window

Using admob.opener.openUrl(), you can open a new native browser window (outside the application). Below is sample code for a simple banner where the destination URL can be loaded into a new browser window. You should replace the following placeholder elements with your own values. If available for your network, you can use the sample code to create a creative template.

  • [BANNER_UNIT]: URL of a banner creative.
  • [WIDTH]: Width of a banner creative.
  • [HEIGHT]: Height of a banner creative.
  • [FULLSCREEN_UNIT]: URL of a full screen creative.
  • [FALLBACK_URL]: Fallback destination URL to use in case the JavaScript function doesn’t execute.
  • [EXTERNAL_WINDOW]: 'true' to open destination URL in an external browser window. ‘false’ to open destination URL in an in-app browser window.

Here's a sample creative code:

<!DOCTYPE html>
<head>
<meta name="viewport" 
content="user-scalable=no, width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"/>

<script type="text/javascript" src="http://media.admob.com/api/v1/google_mobile_app_ads.js"></script>
</head>

<body>
<a href="[FALLBACK_CLICKURL]" 
onClick="admob.opener.openUrl('%%CLICK_URL_ESC%%[FULLSCREEN_UNIT]', '[EXTERNAL_WINDOW]'); 
return false;"><img border="0" src="[BANNER_UNIT]" width="[WIDTH]" height="[HEIGHT]"></a>
</body>
</html>

 

Also see the AdMob Guide to Mobile Ad Development.