Implementation guidance for 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.

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 for AdMob or Ad Manager. Remember that the URL doesn’t need to be available to your users.

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.

Note: Though we accept screenshots of your app for content mapping, HTML is the preferred method.

Use the examples below to learn more about what we mean by complete and accurate.

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 or viewport 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: You should not pass Personally Identifiable Information (PII) or any information that infringes your privacy agreement with your users. For AdMob or Ad Manager, you can remove any PII (examples: full names, email addresses, geolocation parameters) within the content URLs that you send Google.

 

We require a complete and accurate mapping of app content, but anything considered PII can be removed or replaced with a unique identifier prior to sending content URLs to Google.

^{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.

Banner ads

Banner ad on a single page

Banner ads can appear in a single page of an app’s content, such as inside of a news article.

In this example, the banner ad is implemented on a single page and the surrounding content is static. This means the content can be passed in a single URL. 

In this case, you would use the setContentURL() method to pass a single URL before loading the ad request.

Anchor banner ad on a single page

Anchor banners always appear on screen as the user scrolls, locked to the top or bottom of the screen.

In this example, the anchor banner ad is implemented on a single page and the surrounding content is static. This means the content can be passed in a single URL. You should send all of the content that can possibly be present on the page while the anchor banner remains visible.

In this case, you would use the setContentURL() method to pass a single URL before loading the ad request.

Anchor banner ad on a feed 

Anchor banners always appear on screen as the user scrolls, locked to the top or bottom of the screen.

In this example, the anchor banner is implemented on a feed. If you implement an anchor banner on a screen that has multiple pieces of content, you’ll need to pass a URL for each piece of content (up to 4 URLs) surrounding the ad. You should send all of the content that can possibly be present on the page while the anchor banner remains visible.

In this case, you would use setNeighboringContentUrls() method before loading the ad request.

Native ads

Native ad (partial screen) between content

Native ads match the user experience and visual design of the app they live within. Native ads can occupy part of an app’s screen and appear between different pieces of content, such as in between news articles or shopping listings, as a user scrolls or swipes. 

In this example, the native ad appears in line with the app's content as the user scrolls. This means there’s different content before and after the ad. 

If your native ad is implemented in this way, you’ll need to pass the URLs for the content that appears before and after the ad. In this case, you would use setNeighboringContentUrls() method before loading the ad request.

Note: If your ad implementation has more than 2 pieces of content near the ad, you’ll need to pass these URLs too. 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.

Native ad (full screen) between content

Native ads match the user experience and visual design of the app they live within. Native ads can take up a full screen and appear between the app's content as the user scrolls or swipes. 

In this example, the native ad appears between two different pieces of content as the user scrolls. If your native ad is implemented in this way, you’ll need to pass the URLs for the content that appears before and after the ad. 

In this case, you would use setNeighboringContentUrls() method before loading the ad request.

Note: If your ad implementation has more than 2 pieces of content near the ad, you’ll need to pass these URLs too. 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.

Here’s another example showing the native ad as a user swipes. No matter how your user scrolls, you should pass the content before and after the native ad.

Interstitial ads

Interstitial ad on a single page

Interstitial ads can take up a full screen while a user is on a single page, such as viewing a product listing on a shopping app. 

In this example, the interstitial ad is implemented on a single page and the surrounding content is static. This means the content can be passed in a single URL. 

In this case, you would use the setContentURL()method to pass a single URL before loading the ad request.

Interstitial ad between content

Interstitial ads can take up a full screen while a user is navigating between content, such as while a user is switching between sections of your app. 

In this example, the interstitial ad appears between different pages of content. If your interstitial ad is implemented in this way, you’ll need to pass the URLs for the content that appears before and after the ad. 

In this case, you would use setNeighboringContentUrls() method before loading the ad request.

Note: If your ad implementation has more than 2 pieces of content near the ad, you’ll need to pass these URLs too. 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.

Rewarded ads

Rewarded ads allow you to reward users with in-app items for interacting with an ad. For example, users can watch a rewarded ad video to unlock a news article behind a paywall. 

In this example, the rewarded ad appears on a single page (for example, the user was viewing a preview of a news article and interacting with the rewarded ad unlocked the full article). 

In this case, the content can be passed in a single URL using the setContentURL()method. 

App open ads

App open ads appear on the loading screen of your app when the user opens or switches back to your app. 

In this example, the app open ad is implemented on a single page and the surrounding content is static. This means the content can be passed in a single URL. 

In this case, you would use the setContentURL()method to pass a single URL before loading the ad request.

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.
  • You can remove any PII (examples: full names, email addresses, geolocation parameters) within the content URLs that you send Google. We require a complete and accurate mapping of app content, but anything considered PII can be removed or replaced with a unique identifier prior to sending content URLs to Google. 
• 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.
  • Don't append unnecessary URL parameters or tracking ids.
• 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 feedback form to tell us about it.