Get started with content mapping

For every ad unit, the content surrounding the ad can be mapped individually using either setContentUrl() or setNeighboringContentUrls(). Note that each ad unit should use only one type of content mapping, not both. 

Learn more about the two types of content mapping. 

To use content mapping:

1.  Install Google Mobile Ads SDK version:
   • Android: 19.0.0 or later for AdMob and 19.5.0 for Ad Manager
   • iOS: 7.67.0 or later
2. Determine which type of content mapping to use for each of your ad units. 
3. Ensure that the URLs you will pass are public (accessible by crawler). Learn more about making your site fully crawlable.

How to map content completely and accurately

Ensure that each piece of content maps to a URL that captures what the user sees in the app.  The URLs you pass should provide a complete and accurate picture of the content that surrounds the ad.  Use the examples below to learn more about what we mean by complete and accurate. 

Note that the concept of complete and accurate mapping applies to both content url and multi-content url, however the examples below show mapping examples for multi-content url.

Example 1 - Complete mapping (includes all the content around an ad)

The URLs you pass must be a complete representation of the content that surrounds the ad. The URL must contain all of the elements that are adjacent to the ad, including any elements that could appear on the same screen as the ad. 

In Figure 1, there is a homepage newsfeed with two pieces of content, Content A and Content B, which must both be mapped separately. For Content A, we have 3 map examples: 2 good examples and one bad example.

In Map A1, the mapping for Content A is complete because the URL passes the header, the image, and the same paragraph that the user sees directly above the ad. This mapping matches the content the user sees in the app completely.

In Map A2, the mapping for Content A is even more complete because the URL passes the full version of the paragraph (for example, the feed shows a summary of a news article, but you can pass the entire news article). Passing all of the information is the best way to ensure a complete representation of the content that surrounds the ad. 

In Map A3, the mapping for Content A is not complete because the URL only passes the header and the same paragraph that the user sees directly above the ad. This mapping didn’t include the image, so it’s not a complete representation of the content that surrounds the ad. 

Note that you should not pass Personally Identifiable Information (PII) or any information that infringes your privacy agreement with your users.

^{Figure 1} 

Mapping for Content B follows the same pattern as the mapping for Content A.

Example 2 - Accurate mapping

The URLs you pass must be an accurate representation of the content that surrounds the ad. Note that the content can’t be accurate if it’s not complete.

In Figure 2, we’re once again attempting to map a homepage newsfeed. This time, we have two examples of mapping for Content A in the newsfeed.

In Map A1, the mapping for Content A is accurate because it passes the correct elements to match the app content. 

In Map A2, the mapping for Content A is not accurate because it maps Content Z instead, which is unrelated to Content A. This would not be an accurate representation of the content that surrounds the ad. 

^{Figure 2}

Example use cases

For the best performance, it’s important to pass URLs that thoroughly describe the content users see around the ad. First consider the type of ad being served to best determine what URL or URLs you should pass for content mapping. 

Note that the following use cases are examples to help you determine how to use content mapping.

Single page ads

Single page ads, sometimes called in-article ads, appear on one page of your app’s content. These ads often appear between paragraphs. Most often, single page ads will be represented in static content, such as inside of a news article or in a product listing on a shopping app. 

Single page ads can include native and some banner ads.

For single page ads, use the setContentURL() method to pass a single URL before loading the ad request.

Example Android code	// Assuming URL references to Content A is // http://www.my-mobile-website.com/content_A.html   //AdRequest adRequest = new AdRequest.Builder().setContentUrl("http://www.my-mobile-website.com/content_A.html").build();
Example iOS code	// Assuming URL references to Content A is // http://www.my-mobile-website.com/content_A.htm   // GADRequest GADRequest *request = [GADRequest request];  request.contentURL = @"http://www.my-mobile-website.com/content_A.html";

More content mapping code examples are available for Android and iOS.

In-feed ads

In-feed ads appear between different pieces of content, such as news articles or videos, as a user scrolls or swipes. In-feed ads can be partial screen or full screen ads. 

For in-feed ads, you can pass up to 4 URLs that represent all the other content elements that can be on the screen at the same time as the ad. Use the setNeighboringContentUrls() method before loading the ad request.

Partial screen in-feed

Partial screen in-feed ads appear in line with app content and only take up a portion of the app’s screen as the user scrolls. These can include banner ads or native ads. 

Example 

On Publisher A’s news app, there’s a section on fashion trends. As a user scrolls through the list of fashion news, they will come across an ad in-between different articles. The fashion section is dynamic, and it updates as more fashion news is published.

Publisher A should use setNeighboringContentUrls() and reference the URLs for the articles above and below the ad in the fashion trends feed.

Full screen in-feed

Full screen in-feed ads appear in line with app content and take up the entire app’s screen as the user scrolls or swipes.

Example

On Publisher A’s news app, the user can scroll through a list of the latest articles. As the user scrolls, an ad appears between the articles and takes up the full screen until the user scrolls past the ad. 

Publisher A should use setNeighboringContentUrls() and reference the URLs for the articles above and below the ad in the fashion trends feed.

The example images below show that no matter how your user scrolls, you should pass the content before and after the in-feed full screen ad.

 

Example Android code

// Assuming URL references to Content A is // http://www.my-mobile-website.com/content_A.html // and URL references to Content B is // http://www.my-mobile-website.com/content_B.html List<String> urls = Arrays.asList("http://www.my-mobile-website.com/content_A.html", "http://www.my-mobile-website.com/content_B.html"); //AdRequest adRequest = new AdRequest.Builder().setNeighboringContentUrls(urls).build();

Example iOS code

// Assuming URL references to Content A is // http://www.my-mobile-website.com/content_A.html // and URL references to Content B is // http://www.my-mobile-website.com/content_B.html // GADRequest GADRequest *request = [GADRequest request];  request.neighboringContentURLStrings =  @[ @"http://www.my-mobile-website.com/content_A.html", @"http://www.my-mobile-website.com/content_B.html"];

Out-of-feed ads (not supported)

Support for out-of-feed ads is not yet available. To see the benefits of Content mapping, consider creating other ads until out-of-feed is fully supported. The following formats can’t be used: rewarded ads, anchored banner ads,  interstitial ads, and app open ads.  

Out-of-feed ads do not appear in-line with the app’s content and can be partial screen or full screen ads. 

Out-of-feed partial screen ads (not supported)

Out-of-feed partial screen ads appear anchored on the screen as the user interacts with app content. These can include anchored banner ads or native ads. 

Example

On Publisher A’s news site, the publisher creates an adaptive banner ad at the bottom of the screen. This ad will appear consistently, no matter what screen the user navigates to.

The examples below show why content mapping isn’t supported for out-of-feed partial screen ads. 

In the following image, the banner is anchored on the screen and doesn’t change as the user navigates to a new page in the app. There’s no way to determine what content will be shown next, so content mapping can’t be used. 

In the following image, the banner is anchored on the screen and doesn’t change as the user navigates between several pieces of content. Because the pieces of content change as the user scrolls in the feed, we can’t determine what content will appear next to the ad. 

Out-of-feed full screen ads (not supported)

Out-of-feed full screen ads appear between app screens, not as you scroll. You can’t use content mapping with rewarded ads, interstitial ads, and app open ads.

Example

On Publisher A’s news site, the user can navigate between different sections of the app. As the user navigates from today’s news screen to the customized news screen, a full-screen ad appears.

URL requirements

Consider the following when selecting URLs to use in content mapping:

• URLs must consistently match the content the user sees in the app. Learn more about our policies on misrepresentative content.
• Don’t pass Personally Identifiable Information (PII) or any information that violates your privacy agreement with your users.
• URLs must be crawlable by Google.
  • If viewing the content requires a login, follow the instructions for configuring crawler logins. 
• URLs must not be shortened (for example, goo.gl/MyContent)
• URLs must be unique to the content the user sees in the app.
  • Don’t pass one generic URL for your entire app.
  • Don’t pass your app’s Play Store, App Store, or other app store URLs.
• If you have a desktop website (such as example.com) and a separate mobile website (such as m.example.com), choose the URL which leads to the most complete representation of your app content. 

Don’t use content mapping if your content isn’t represented in the example use cases. If your implementation is not described, fill out this form to tell us about it.