Google

This guide is intended for publishers who want to use the MoPub SDK to load and display ads from AdMob and Google Ad Manager via mediation. Below, you will find information about the ad network, integration/setup instructions, and more. For more information about how MoPub mediation works, visit this guide.

Download and Integration

The same adapters and SDKs support both AdMob and Google Ad Manager. To download the adapters, navigate to the Mediation Integration Tool. You will also need to download the Mobile Ads SDK, which can be found below.

For the latest download and integration instructions, ensure that you have consulted Google’s tutorials before you integrate the SDK and adapters.

iOS Download
Android Download

Update your AndroidManifest.xml and Info.plist

This is a required step as of v17.0.0 of the Mobile Ads SDK. Failure to do so results in a crash. If you mediate AdMob, see this Android and iOS instruction. If you mediate Google Ad Manager, see this Android and iOS instruction.

Android Integration Help

Adapters are released as an Android Archive (AAR) file starting from version 17.1.2.4. The AAR includes the required Manifest data for AdMob and Google Ad Manager if any. As a result, publishers no longer have to update their Manifest manually.

Instructions for passing user’s ad preference to Google

Publishers must work with Google for GDPR compliance by collecting consents on their own. To faciliate the process, the adapters (Android: 15.0.0.x / iOS: 7.30.0.x) will forward the user’s npa preference to Google. Publishers must make sure to complete the remaining steps below in their app:

Android

  1. In your implementation, before you initialize the MoPub SDK, create a HashMap with the following <key, value> pair if the user does not consent to receive personalized ads:

     HashMap<String, String> config = new HashMap<>();
     config.put("npa", "1");  
    
  2. In your SdkConfiguration object, pass that HashMap to the Google adapter configuration via Builder.withMediatedNetworkConfiguration():

     SdkConfiguration sdkConfiguration = new SdkConfiguration.Builder(adUnitId)
           .withMediatedNetworkConfiguration(GooglePlayServicesAdapterConfiguration.class.getName(), config);
           .build();
    
       // Initialize the MoPub SDK
    

iOS

  1. In your implementation, before you initialize the MoPub SDK, create an NSDictionary with the following <key, value> pair if the user does not consent to receive personalized ads:

     NSDictionary * npaConfig = @{ @"npa" : @"1"};
    
  2. In your MPMoPubConfiguration object, pass that NSDictionary to the Google adapter configuration via MPMoPubConfiguration.mediatedNetworkConfigurations:

     MPMoPubConfiguration * sdkConfig = [[MPMoPubConfiguration alloc] initWithAdUnitIdForAppInitialization: adUnitId];
    
     NSMutableDictionary * config = [@{@"GoogleAdMobAdapterConfiguration" : npaConfig} mutableCopy];
    
     sdkConfig.mediatedNetworkConfigurations = config;
    
     // Initialize the MoPub SDK
    

Unity

  • In your implementation, when you initialize the MoPub SDK, create an instance of NetworkConfiguration, and pass in the following value if the user does not consent to receive personalized ads:

        MoPub.InitializeSdk(new MoPubBase.SdkConfiguration {
          AdUnitId = anyAdUnitId,
          NetworkConfiguration = new[] {new MoPub.NetworkConfiguration.AdMob {
              {"npa", "1"}
              }
            }
        });
    

For additional context, please visit the AdMob articles (Android / iOS) on forwarding consent to the Mobile Ads SDK.

Pass data to Google

Google allows publishers to pass a URL String to target using content mapping, as well as test device IDs to activate test mode. In order to utilize data passing capabilities, publishers must use v17.1.2.2 (Android) and v7.37.0.0 (iOS) of the adapters at the minimum. Then, follow the steps below in the implementation while integrating the MoPub SDK. Note that the adapters currently do not support Google Ad Manager Custom Targeting.

Android

  1. Create a Map to hold two key-value pairs. For content mapping, the key should be contentUrl, and the value will be the URL String you’d like to pass to Google. For test device IDs, the key should be testDevices, and the value will be the test device ID String of your device. Note that the keys are case-sensitive.

     Map<String, Object> localExtras = new HashMap<>();
     localExtras.put("contentUrl", "www.example.com");
     localExtras.put("testDevices", "0123456789");
    
  2. Depending on the ad format you are integrating, pass the Map created from step 1 to the correct API, shown below:

     // Banner
     MoPubView.setLocalExtras(localExtras);
    
     // Interstitial
     MoPubInterstitial.setLocalExtras(localExtras);
    
     // Rewarded Video
     // Publishers are to pass the resources at the time of initializing the MoPub SDK, like so:
    
     // Pass the GooglePlayServicesMediationSettings to the SDK's initialization call from the "Instructions for passing user's ad preference to Google" section:
     SdkConfiguration sdkConfiguration = new SdkConfiguration.Builder(adUnitId)
     .withMediationSettings(new GooglePlayServicesRewardedVideo.GooglePlayServicesMediationSettings(npaBundle, "http://www.example.com", "0123456789"))
     .build();
    
     // Native
     MoPubNative.setLocalExtras(localExtras);
    
  3. Make your ad request.

iOS

  1. Create an NSDictionary to hold two key-value pairs. For content mapping, the key should be contentUrl, and the value will be the URL String you’d like to pass to Google. For test device IDs, the key should be testDevices, and the value will be the test device ID String of your device. Note that the keys are case-sensitive.

     NSDictionary *localExtras = @{@"contentUrl" : @"www.example.com", @"testDevices" : @"0123456789"};
    
  2. Depending on the ad format you are integrating, pass the NSDictionary created from step 1 to the correct API, shown below:
     // Banner
     MPAdView.localExtras = localExtras;
    
     // Interstitial
     MPInterstitialAdController.localExtras = localExtras;
    
     // Rewarded Video
     [MPRewardedVideo loadRewardedVideoAdWithAdUnitID:self.info.ID keywords:self.info.keywords userDataKeywords:nil location:nil customerId:@"testCustomerId" mediationSettings:@[] localExtras:localExtras];
    
     // Native
     MPNativeAdRequestTargeting *targeting = [[MPNativeAdRequestTargeting alloc] init];
     targeting.localExtras = localExtras;
    
  3. Make your ad request.

Network reporting

To access AdMob network reports for rewarded video, make sure to enter the network ids in the Google networks sections as shown below.

  1. Once you enable reporting as below for AdMob:

    AdMob Network Page

  2. Configure Admob ad unit IDs against the native MoPub ad unit IDs of your app as below:

    AdMob Network with AdMob IDs

Mediate AdMob Native Ad Demand

AdChoices Options

Google provides the option to select any of the four corners of the ad to render the AdChoices icon. To set a preferred AdChoices icon position for your app, follow the steps below. Ensure to set the preferred position before the ad request. The icon will be rendered in the topright corner by default if no custom position is set.

iOS

Call setAdChoicesPosition: from MPGoogleAdMobNativeCustomEvent with your preferred GADAdChoicesPosition position:

[MPGoogleAdMobNativeCustomEvent setAdChoicesPosition:GADAdChoicesPositionBottomRightCorner];

Android

Pass the preferred position to a HashMap, then pass the HashMap in the setLocalExtras() call:

HashMap<String, Object> extras = new HashMap<>();

extras.put(GooglePlayServicesNative.KEY_EXTRA_AD_CHOICES_PLACEMENT, NativeAdOptions.ADCHOICES_TOP_LEFT);

moPubNative.setLocalExtras(extras);

(Optional) Additional assets

Google also supports the following additional assets that you can access using the below API:

  • Star Rating (app-install ads only)
    • Textview showing the star rating on 5.
  • Price (app-install ads only)
    • Textview showing price of the app.
  • Store (app-install ads only)
    • Textview app store name.
  • Advertiser (content ads only)
    • Textview showing the name of the advertiser.

iOS

static NSString *const kGADMAdvertiserKey = @"advertiser";
static NSString *const kGADMPriceKey = @"price";
static NSString *const kGADMStoreKey = @"store";

- (void)layoutCustomAssetsWithProperties:(NSDictionary *)customProperties {

    _priceLabel.text = [NSString stringWithFormat:@"%@", customProperties[@"price"]];
    _storeLabel.text = [NSString stringWithFormat:@"%@", customProperties[@"store"]];
}

Android

ViewBinder mViewBinder = new ViewBinder.Builder(R.layout.native_ad_item)
        // bind to the other required assets here
        .addExtra(GooglePlayServicesAdRenderer.VIEW_BINDER_KEY_STAR_RATING,
                R.id.native_star_rating)
        .addExtra(GooglePlayServicesAdRenderer.VIEW_BINDER_KEY_PRICE,
                R.id.native_price)
        .addExtra(GooglePlayServicesAdRenderer.VIEW_BINDER_KEY_STORE,
                R.id.native_store)
        .addExtra(GooglePlayServicesAdRenderer.VIEW_BINDER_KEY_ADVERTISER,
                R.id.native_advertiser)
        .build();

Best Practices

MoPub Manual Integration

When using MoPub’s manual integration via AdapterHelper, it’s important to avoid using a recycled view that once displayed an ad from AdMob to display one from another network, and vice versa. The following code snippet shows how to render and show ads when manually integrating:

if (nativeAd.getMoPubAdRenderer() instanceof GooglePlayServicesAdRenderer) {

   // When creating an AdMob ad using AdapterHelper's
   // getAdView(convertView, parent, nativeAd, viewBinder), do not pass a view used to
   // display an ad from another network as convertView instead let the AdapterHelper
   // create a new one. Views used to show another AdMob ad can be reused.

} else {
   // Create/show ads from other networks.
}

Margins

AdMob renders the AdChoices icon in one of the four corners of the native ad view by default. Some layout designs can cause this icon to appear to be outside the ad’s content area. The following are some examples of the view hierarchies that might cause the AdChoices icon to be rendered on top of margins.

  • Layouts with empty views used as padding/margins:

    layout1

  • Layout with margin on the child view (containing assets) relative to the outermost view.

    layout2

  • Layouts with a margin on the outermost view.

    layout3

Note: The Google Mobile Ads SDK considers the bounds of the top level view of the layout used to create the MoPub ViewHolder to define the bounds of the native ad’s presentation, and will place the AdChoices icon in one of the corners of those bounds.

The Google Mobile Ads SDK supports a different setting to allow publishers to specify the location of the AdChoices placement, and it addresses the layouts with margins noted above. However, your account must be enabled by AdMob for this feature. If you are affected by this margin issue and placing AdChoices in one of the four corners of the native ad view is not sufficient, please contact your Google account manager to request this feature. Once your account is whitelisted to use the customized Ad Choices placement, follow the below steps.

Android

  • Modify your ad view layout by wrapping the MoPub privacy information icon with a FrameLayout with the ID “native_ad_choices_icon_container”. For example, if your privacy icon layout looks like this:

    <ImageView android:id="@+id/native_ad_daa_icon_image"
                android:layout_width="40dp"
                android:layout_height="40dp"
                android:padding="10dp" />
    

    You should modify it to look like like this:

    <FrameLayout android:id="@+id/native_ad_choices_icon_container"
                android:layout_width="40dp"
                android:layout_height="40dp"
                android:padding="10dp" >
       <ImageView android:id="@+id/native_ad_daa_icon_image"
                  android:layout_width="match_parent"
                  android:layout_height="match_parent" />
    </FrameLayout>
    
  • Add the ID of the FrameLayout as an extra to the ViewBinder that would be provided to the GooglePlayServicesAdRenderer using the key GooglePlayServicesAdRenderer.VIEW_BINDER_KEY_AD_CHOICES_ICON_CONTAINER.

    mViewBinder = new ViewBinder.Builder(R.layout.native_ad_item)
      // bind to the other required assets here
      .addExtra(GooglePlayServicesAdRenderer.VIEW_BINDER_KEY_AD_CHOICES_ICON_CONTAINER,
              R.id.native_ad_choices_icon_container)
      .build();
    

iOS

No additional code is required. The Google adapter will place its AdChoices icon in the same spot where you placed the MoPub privacy icon.

Known Issues

  • Android - the AdChoices icon not visible when using CardView as the view passed to MoPub.
  • Android - MoPub will not collect the advertising ID in pre-5.5 SDKs if com.google.android.gms:play-services-ads is missing. Please check the dependencies as mentioned here

OAuth Authentication for Auto CPM

Here is the Google help article which provides instructions on how to setup authentication through OAuth2 to use in the MoPub UI.

This setup is required to take advantage of Auto CPM.

Test Ad

While testing your SDK integrations and network setups, it is recommended that you leverage test ad placements. To set up AdMob test mode, please reference Google’s test ad article for Android and iOS for instructions. For Google Ad Manager, see the Android and iOS articles.

Last updated August 27, 2019

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2019 MoPub (a division of Twitter, Inc.)