Mediate Facebook

This guide is intended for publishers who want to use the MoPub SDK to load and display ads from Facebook Audience Network 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.

Supported Ad Formats

The following ad formats are currently supported by Facebook Audience Network. For the latest support, visit the Facebook Audience Network homepage.

  • Banner (To request banner ads with a height greater than 250, you must configure your Facebook placement as a medium rectangle on the Facebook dashboard. Using a placement of type banner won’t return ads in this case.)
  • Interstitial
  • Rewarded Video
  • Native and Native Banner

Download and Integration

To download the Facebook Audience Network adapters, navigate to the Mediation Integration Tool. You will also need to download the Facebook Audience Network SDK, which can be found below.

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

iOS Download
Android Download

Localhost whitelisting

Facebook uses the device’s localhost (127.0.0.1) to cache ad media files. Since Android 9 blocks cleartext traffic by default, publishers must add the following XML configuration to their app’s Manifest to whitelist unsecure traffic (click here for additional information):

    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">127.0.0.1</domain>
    </domain-config>

Request native banner ads

MoPub now supports Facebook Audience Network native banner mediation as of v5.6.0.0 of the Android and iOS adapters. To get started, create a native banner placement on the Facebook Audience Network dashboard.

Facebook placement IDs can be enabled for native or native banner demand. You will pass a flag to MoPub to indicate your preference for native or native banner demand. Follow the appropriate instructions below based on the platform and your native ad integration.

Manual native ad integration

Android
  1. In your native ad implementation, create a Map<String, Object> object containing your native banner preference. Set the flag’s value to true to request native banner, or false (or don’t set it at all) to request regular native ad.

     Map<String, Object> localExtras = new HashMap<>();
     localExtras.put("native_banner", true);
    
  2. Pass the above Map to your MoPubNative instance before making the ad request. Subsequently, to change your preference, re-do step 1.

     MoPubNative.setLocalExtras(localExtras);
     // Make your ad request
    
  3. (Optional) If you will be alternating between regular native as well as native banner requests, we recommend preparing separate XML layout files—one for each format. Then, when registering your native ad renderer, because at this time you are in control of which format is requested, you can pass in the corresponding layout to your renderer. Doing so allows you to avoid having assets unexpectedly laid out.

iOS
  1. In your native ad implementation, create an NSDictionary holding an {NSString : Boolean} pair containing your native banner preference. Set the flag’s value to true to request native banner, or false (or don’t set it at all) to request regular native ad.

     NSDictionary *localExtras = @{@"native_banner" : true}; 
    
  2. Pass the above NSDictionary to your MPNativeAdRequestTargeting instance before making the ad request. Subsequently, to change your preference, re-do step 1.

     MPNativeAdRequestTargeting *targeting = [[MPNativeAdRequestTargeting alloc] init];
     targeting.localExtras = localExtras;
     // Make your ad request
    
  3. (Optional) If you will be alternating between regular native as well as native banner requests, we recommend preparing separate layout files—one for each format. Then, when registering your native ad renderer, because at this time you are in control of which format is requested, you can pass in the corresponding layout to your renderer. Doing so allows you to avoid having assets unexpectedly laid out.

Ad Placer integration

Android
  1. In your app, before you initialize MoPub, create a Map<String, String> object containing your native banner preference. Set the flag’s value to "true" (with the quotation marks because this API expects a String) to request native banner, or "false" (or don’t set it at all) to request regular native ad.

     Map<String, String> facebookNativeBanner = new HashMap<>();
     facebookNativeBanner.put("native_banner", "true");
    
  2. In your SdkConfiguration.Builder, pass the above Map to the withMediatedNetworkConfiguration() call before initializing the MoPub SDK:

     SdkConfiguration.Builder configBuilder = new SdkConfiguration.Builder("YOUR_AD_UNIT_ID");
    
     configBuilder.withMediatedNetworkConfiguration(FacebookAdapterConfiguration.class.getName(), facebookNativeBanner);
     // Initialize MoPub
    
iOS
  1. In your app, before you initialize MoPub, create an NSDictionary holding an {NSString : Boolean} pair containing your native banner preference. Set the flag’s value to true to request native banner, or false (or don’t set it at all) to request regular native ad.

    NSDictionary * facebookConfig = @{ @"native_banner" : true};
    
  2. In your MPMoPubConfiguration object, pass that NSDictionary to the mediatedNetworkConfigurations call before initializing the MoPub SDK:

     MPMoPubConfiguration * sdkConfig = [[MPMoPubConfiguration alloc] initWithAdUnitIdForAppInitialization: @"YOUR_AD_UNIT_ID"];
    
     NSMutableDictionary * config = [@{@"FacebookAdapterConfiguration" : facebookConfig} mutableCopy];
    
     sdkConfig.mediatedNetworkConfigurations = config;
     // Initialize MoPub
    

That’s it! When you make your ad request, we’ll inform Facebook that this is a native banner ad request.

Native ad advertiser name asset

Depending on the Facebook SDK version you are integrating, you will need to show only either the ad title or the advertiser name. For more information about Facebook’s implementation requirements, check out this article.

To show the advertiser name asset on Android, follow this guide. If you are on iOS, adapters will automatically manage showing the correct asset depending on the Facebook Audience Network SDK version you are integrating.

Android Integration Help

Facebook Audience Network adapters are released as an Android Archive (AAR) file starting from version 5.2.0.1. The AAR includes the required Manifest data for FAN. As a result, publishers no longer have to update their AndroidManifest manually for any generic data, such as permissions and Activities. Any other app-level placement configuration required by Facebook Audience Network must be manually entered into the AndroidManifest.

Set up Facebook Audience Network on the MoPub dashboard

  • Placement ID is required.

Migrate Facebook Audience Network from Custom Native Setup

  • Transfer Placement ID (if applicable) from the old custom native connection to the supported Facebook Audience Network instance.
  • MoPub will initiate the following Facebook Audience Network custom event class names to render the ads:
    • iOS
      • FacebookBannerCustomEvent
      • FacebookInterstitialCustomEvent
      • FacebookRewardedVideoCustomEvent
      • FacebookNativeCustomEvent
    • Android
      • com.mopub.mobileads.FacebookBanner
      • com.mopub.mobileads.FacebookInterstitial
      • com.mopub.mobileads.FacebookRewardedVideo
      • com.mopub.nativeads.FacebookNative

Note: If you are manually entering the above-mentioned class names, migrate to the new network setup and pause the “custom native network”. If you are using your own custom event class names, you should have both the old custom native network setup & the new Facebook Audience Network network UI setup for backward compatibility.

Note: During migration, please make sure the custom native network and the Facebook Audience Network network are not live at the same time as this may cause revenue-impacting issues.

Facebook Token for Network reporting & Auto CPM”

To enable Facebook network reporting and Auto CPM, you will need to enter “System user token” and “Facebook business ID”.

Facebook Token 1

You can find the “Facebook business ID” from the URL of Facebook business manager or monetization manager portal.

Facebook Token 2

For the “System user token”, below is the Facebook help article which provides instructions on how to generate a reporting token to use in the MoPub UI.

https://developers.facebook.com/docs/audience-network/reporting-api/systemuser

This setup is required to take advantage of Auto CPM.

Troubleshooting tips

Invalid Credentials:

  1. Have you associated the system user for which you generated the token to the right property?
  2. Did you assign the correct apps to the correct property? Here is the Facebook help article on how to create apps within properties: https://www.facebook.com/help/publisher/709041312624617?helpref=page_content
  3. Still stuck? Reach out to your Facebook team for help and provide them with the app and property ids.

Why are some of my apps not updating for Facebook?

Confirm that all the apps that are connected to your Facebook token ID are correctly permissioned in Facebook Business Manager so that MoPub can collect the data for the placement IDs. Follow the instructions here: https://developers.facebook.com/docs/audience-network/reporting-api/systemuser

Test Ad

While testing your SDK integrations and network setups, it is recommended that you leverage test ad placements for a consistent fill rate. To set up test mode, please reference Facebook’s test ad article for instructions.

For details about available error codes as well as potential resolutions, reference Facebook’s documentation.

Additional Support

For inquiries and support, please visit Facebook Audience Network’s support center.

Last updated October 29, 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.)