Facebook Audience Network Mediation Integration Guide

This guide will instruct you step-by-step on how to set Facebook Audience Network live as an Ad Network on the ironSource Mediation platform.

Before You Start
Make sure you have correctly integrated ironSource’s InterstitialRewarded Video or Banner Mediation in your application.

Step 1. Create a Facebook Account

  1. First Time Setup
    1. Go to Facebook for Developers and register with your Facebook account.
    2. Follow the procedure and set your application name.
    3. Click ‘Register‘.
      2-facebook-developer-get-started
  2. Registered Users
    1. Sign into your Facebook account.
    2. On the right sidebar you will see ‘My Apps’. Click on Your app.
      5-facebook-my-apps

 

Step 2. Create Ad Placement in Facebook Audience Network

Important! You must create a dedicated placement per platform (iOS and Android) in order for Facebook Audience Network to work correctly with ironSource‘s Mediation platform.
  1. To create ad placements for your app in your Facebook account, Navigate to the main Dashboard and on the center grid under Add a Product  Audience Network, click on ‘Setup‘.
    Note! unless you did it already, you will be asked to open business account (by facebook), it is rather simple and quick procedure. Complete it and move on.
  2. Choose a platform:
    6-facebook-network-setup-platforms
  3. Next, choose the first ad unit you would like to implement in your application:
    6-facebook-network-setup-ad-units
  4. Click on ‘Next’ and now the ad unit you choose is good to go.
    7-facebook-placementid
  5. Now you can either create more placements for this platform or add another platform. the next step is setting up Facebook Audience Network inside ironSource platform.
    8-facebook-create-new-placement-add-another-platform
    Note: It is mandatory to create two separate placements for iOS and Android. We recommend creating one placement per ad location per application.

    Step 3. Activate Facebook on the ironSource SDK Network Module

    There are 3 pieces of Data from the Facebook Audience Network account which need to be inserted into your ironSource Network Setup Module in order for Facebook Audience Network to work correctly in connection with ironSource:

    App ID This is the unique identifier of your app in Facebook Audience Network’s system.
    Placement ID  This is the unique identifier of a specific placement in your app in Facebook Audience Network’s system.
    User Token The user token is the most commonly used type of token. This kind of access token is needed any time the app calls an API to read, modify or write a specific person’s Facebook data on their behalf. 

    Once you obtain this information, you must configure Facebook Audience Network’s Parameters in your ironSource Account. By adding the above information correctly, you will be able to take full advantage of Facebook’s Interstitial or Banner ad inventory and reporting data on ironSource’s Mediation platform.

    1. App ID
      1. To retrieve your app ID, hover over ‘≡’ in the upper-left corner, and click on ‘App Dashboard’:
        9-facebook-access-to-appid
      2. Choose the application of which you want to see the App ID. this will navigate you to your Facebook Audience Network dashboard. there you should see the specific App ID located on the center of the upper bar
        9-facebook-appid
    2. User Token
      1. While still inside your dashboard, To retrieve your User Token, go to Tools -> Graph API Explorer on the top menu.
      2. On the upper-right corner of the Graph API Explorer you should click on the drop-down list (at first it should point on ‘Graph API Explorer’) and choose your application
        13-facebook-choose-app-user-token
      3.  Now you should click on the ‘Get Code’ drop-down list (right under the ‘Graph API Explorer’ list from the previous point) and choose ‘Get User Access Token’
      4. Check ‘read_insights’ and press on the ‘Get Access Token’ button
        13-facebook-read_insights
      5. At this stage Facebook will generate the new token. Copy the new Access Token and continue.
        13-facebook-copy-new-access-token

    3. Placement ID
      1. To retrieve your Placement ID, click on ‘Audience Network’ on the left sidebar in the dashboard
      2. you should be asked to navigate to ‘Monetization Manager’, click on the link:
        9-facebook-access-to-placementid
      3. Under your application review you find a list of your placements, click on the one you want to retrieve it’s PlacementID
        10-facebook-monetization-manager
      4. Now click over the ‘Get Code’ and there you will find your ID
        11-facebook-get-placement-id

    Configure Facebook’s Parameters into ironSource Account

    • Once you have all these parameters, log in to your ironSource account and go to ‘Monetize‘ ➣ ‘Setup‘ ➣ ‘SDK Networks‘.
      iron-source-networks
    • Select Facebook from the list of Available Ad Networks and click on ‘Activate’.
      Note: To run Mediation with Facebook, you must have an active Facebook Audience Network Account. When you select Facebook as a network, you will see the below pop-up. If you have an active Facebook account, simply click activate and Save. If you do not have an active Facebook account, you must register at Facebook Audience Network and follow this documentation from Step 1.
      ironsource-platform-activate-fb
    • Select the app on which you’d like to run ironSource‘s Interstitial, Rewarded Video or Banner Mediation with Facebook.
      ironsource-fb-network-setup-2
    • Select Facebook Audience Network from the Setup list of Ad Networks, click on the Define icon and insert the App ID, Placement ID and User Access Token in the relevant fields.
      facebook-network-in-listfacebook-setup-ironsource
    • Then set status to Active and click ‘Save’. You will then see Facebook as Active for Interstitial Mediation on your Mediation Dashboard.
      facebook-network-in-list-verified
    • Verify your integration with the Reporting API; this column will check your integration through the Reporting API and return three possible responses: Verified, Failed and No Response. Double check your integration and the information you entered above; then click ‘Retry‘ until you see ‘Verified’.

    Step 4. Add the Facebook Adapter to Your Build

    Unity Plugin (Android Integration):

    Make sure you have the support-v4.jar integrated in your project in your Assets/Plugins/Android directory.
    1. Download the Facebook Unity Package:
      Import the IronSourceFacebookAdapter_[version].unitypackage to your Unity project. You can find the latest Facebook Unity Package here.
    2. Add the Facebook files to your Unity project:
      1. To add the adapter, simply double click on the IronSourceFacebookAdapter_[version].unitypackage and add all files to your Unity project.
        Note: If you are upgrading from a previous version, please remove Facebook.x.x.x.jar from Assets/Plugins/Android.
    Disclaimer: Plugin version 6.7.1

    To accommodate changes in Unity version 5.5, the ironSource Plugin version 6.7.1 requires Android Manifests to be added separately to the Plugin and mediation adapter. If you are updating your plugin or currently running on 6.7.1, make sure to add the manifest activities noted in the Android documentation.

    Unity Plugin (iOS Integration):

    1. Download the Facebook Unity Package:
      Import the IronSourceFacebookAdapter_[version].unitypackage to your Unity project. You can find the latest Facebook Unity Package here.
    2. Add the Facebook files to your Unity project:
      To add the adapter, simply double click on the IronSourceFacebookAdapter_[version].unitypackage and add all files to your Unity project.
      Note: If you are upgrading from a previous version, please remove Facebook.x.x.x.framework from Assets/Plugins/iOS.
      Our Unity Plugin adds the necessary frameworks automatically to your Xcode project.

     

    Verify Your Ad Network Integration

    • Verify your ad network integration with our Integration Helper. The ironSource SDK provides a tool to ensure you’ve successfully integrated our SDK as well as any additional network adapters.
    • Manage the debug logs for your integrated mediation ad networks with this boolean

      IronSource.Agent.setAdaptersDebug(true);

      When set to TRUE, this line of code will enable debug logs to help you troubleshoot issues with all of the mediation ad networks that permit to do so.  Remove this code before your app goes live with our ad units! Supported for SDK versions 6.5.2 and up.

     Note: if you are using Facebook Audience Network’s server-to-server callbacks and are leveraging the DynamicUserID parameter to verify AdRewarded events, you will see this parameter reflected in their server-side callbacks. In addition, you can also see this parameter in the ironSource server-to-server callbacks.

    Done!
    You are now all set to deliver Facebook Audience Network Ads through the ironSource Mediation platform!


    What’s Next?
    To leverage additional ad networks through ironSource Mediation, integrate the adapters and follow our integration guides.