Mobile App Client-to-Server Bidding Integration

Facebook Audience Network supports bidding in mobile apps as well as mobile websites. Mobile app bidding integrations can be from the mobile client to our server or from your server to our server. This guide describes how you can integrate bidding from your mobile app (client side) directly.

Prerequisites

In this type of integration, the app, running on the user's device, calls Facebook Audience Network bidding endpoint and all other demand sources to get bid responses. Then the app will run the auction directly on user's device. This type of integration allows you to use app bidding without an auction server but requires relying on the user's device and potentially less-reliable network and more latency.


In the step by step guide below, we will be using the example of bidding on an interstitial ad. Make sure that you are already familiar with using Audience Network interstitial ads. Bidding also supports Native, Banner, In-stream Video and Rewarded Video formats. When you are using ad formats other than interstitial for bidding, you can change the corresponding ORTB request parameters and the SDK classes to load those ads.

Preparation Steps

Publisher Registration

Getting Android/iOS Bidding Kit


Android Client Bidding Setup Steps

Android - 1. Getting the bidding SDK module

Android - 2. Sending the bid request

Android - 3. Running the auction

Android - 4. Loading the ad with bid response payload


iOS Client Bidding Setup Steps

iOS - 1. Getting the bidding SDK module

iOS - 2. Sending the bid request

iOS - 3. Running the auction

iOS - 4. Loading the ad with bid response payload


Preparation Steps

Publisher Registration

Each publisher needs to create an Audience Network business ID, which we will whitelist for bidding. Under this business id you can create multiple properties that utilizes bidding end point.

  • Go to the Facebook Audience Network documentation, click the "Start Now" button to create a new Business ID or you can use your existing Business ID.
  • You can create properties, apps or domains (mobile web), under the same Buisness ID but you will have to register them see Monetization Manager for more details. For web domains, this is only be possible once the app ID has been approved by Facebook.
  • Let us know the Business ID (this is your publisher ID).
  • You can manage user access to your business/app.

Getting Android/iOS Bidding Kit

The bidding kit contains utility classes for your integration of bidding on the client side, as well as a sample project showing how you can use it.

The bidding kit version is independent of the main Audience Network SDK versions. You can use the bidding kit together with any Audience Network SDK versions that's equal or newer than 4.99.x in your client side bidding integration, but we always recommend that you use the latest SDK versions to include the latest improvements and features (as long as it's supported; see the table below).

You can find the downloads of bidding kit here:

Platform Date Package Compatible FAN SDK

Android

Feb 20th, 2019

bidding-kit-sdk-5.0.1

≥ 4.99.x

iOS

May 9th, 2019

FBAudienceNetworkBiddingKit-5.3.1-beta

≥ 5.3.x

iOS

Sep 6th, 2018

FBAudienceNetworkBiddingKit-5.0.0-beta

4.99.x5.2.x

Android

Android - 1. Getting the bidding SDK module

Ensure you have completed the Audience Network Getting Started and Android Getting Started guides before you proceed.

For apps integrating with bidding from the client side, in addition to the Audience Network SDK, we provide some utility functions for client side bidding integration in the Audience Network Bidding Kit.

If using Android Studio, Intellij IDEA or Eclipse, download and extract the Audience Network Bidding Kit for Android. Copy the FBAudienceNetworkBiddingKit-release.aar and ads-release.aar library files and place it in the /libs folder in your project's app module. You might need to create the directory if it doesn't already exist. Then, add the following lines to your app module's build.gradle:

repositories {
  flatDir {
    dirs 'libs'
  }
}

dependencies {
  ...
  compile(name: 'ads-release', ext: 'aar')
  compile(name: 'FBAudienceNetworkBiddingKit-release', ext: 'aar')
}

Note that the Audience Network Bidding Kit only works with the included Audience Network SDK version, which is contained in the ads-realse.aar library file. You don't need to include Audience Network Android SDK again.

Android - 2. Sending the bid request

In your Activity or Fragment, create a bid request object like this:

import com.facebook.bidding.FBAdBidFormat;
import com.facebook.bidding.FBAdBidRequest;

...

FBAdBidRequest bidRequest = new FBAdBidRequest(
  context,
  "YOUR_APP_ID",
  "YOUR_PLACEMENT_ID",
  FBAdBidFormat.INTERSTITIAL);

Set the bid format according to your placement format type. In the example, we used FBAdBidFormat.INTERSTITIAL for interstitial ad. Your can find the other supported ad formats in the FBAdBidFormat enum.

public enum FBAdBidFormat {

  // Bid For Banner 320x50
  BANNER_320_50,
  // Bid For Banner with flexible width and height 50
  BANNER_HEIGHT_50,
  // Bid For Banner with flexible width and height 90
  BANNER_HEIGHT_90,
  // Bid For Banner with flexible width and height 250
  BANNER_HEIGHT_250,
  // Bid For Interstitial
  INTERSTITIAL,
  // Bid For Instream Video
  INSTREAM_VIDEO,
  // Bid For Rewarded Video
  REWARDED_VIDEO,
  // Bid For Native
  NATIVE,
  // Bid For Native Banner
  NATIVE_BANNER;
  ...
}

After the request object is created, we can send the request by calling the getFBBid method, which takes a FBBidReqeust.BidResponseCallback object to handle the bid response.

bidRequest.getFBBid(new FBAdBidRequest.BidResponseCallback() {
  @Override
  public void handleBidResponse(final FBAdBidResponse bidResponse) {
    activity.runOnUiThread(new Runnable() {
      @Override
      public void run() {
        if (bidResponse.isSuccess()) {
          // Running the auction...
          runAuction(bidResponse);

        } else {
          Log.e(bidResponse.getErrorMessage());
        }
      }
    });
  }
});

Note that the handleBidResponse callback is executing on a worker thread. If you need to do work on the UI, for example loading the ad from the bid response, you will need to use methods like activity.runOnUiThread to make sure that the following code is executed on the UI thread.

The bidRequest has a default time out of 1000 milliseconds. It can be changed by calling withTimeoutMS() method. When a bid times out, Bidding Kit sends a timeout notification back to Facebook and returns a bidResponse with isSuccess() as false, as well as "Bid timeout" in getErrorMessage().

Here is an example of setting bid request timeout to 500 milliseconds.

bidRequest.withTimeoutMS(500).getFBBid(new FBAdBidRequest.BidResponseCallback() {
  @Override
  public void handleBidResponse(final FBAdBidResponse bidResponse) {
    activity.runOnUiThread(new Runnable() {
      @Override
      public void run() {
        if (bidResponse.isSuccess()) {
          // Running the auction...
          runAuction(bidResponse);

        } else {
          Log.e(bidResponse.getErrorMessage()); // When bid timeout, will see "Bid timeout - Please consider increasing the timeout."
        }
      }
    });
  }
});

Android - 3. Running the auction

In this part, we take the bid response from Audience Network and compare it with CPM prices from other buyers, and decide whether the Audience Network wins and loads the ad, or it loses. When you determine with the result of the auction, call the methods notifyWin() or notifyLoss() to notify Facebook about the result.

Note that the auction logic is implemented by the app itself. It should be simply comparing bid prices and choosing the highest bidder as the auction winner.

Here is an example of how to use the returned bidResponse and run an auction in an Android app.

public void runAuction(final FBAdBidResponse bidResponse) {
  // Some other price that we are competing against
  final double otherPrice = ...;
  
  final double price = bidResponse.getPrice();
  if (price >= otherPrice) {
    // Load the ad from the bid response
    loadAdFromBidResponse(bidResponse);

    // Notify the bid won
    bidResponse.notifyWin();
  } else {
    // Notify the bid lose
    bidResponse.notifyLoss();
  }
}

Android - 4. Loading the ad with bid response payload

When the Audience Network bid wins an auction, the next step is to use the bid response with loadAdFromBid(bidResponse) method to retrieve an ad and then show it. Similar to normal ad loading, in client side bidding integration you will need to create the ad object and specify the corresponding ad listener object to handle the callback methods. The difference is that instead of calling loadAd() method, you call the loadAdFromBid(bidResponse) with the payload from the bid response, which you can get from bidResponse.getPayload(). The callback methods of the listener work the same as normal ad object listeners.

Note that ads can be cached on the client but must be shown within 60 minutes of when they are loaded. Any impressions based on an cached ad more than 60 minutes won't be paid.

public void loadAdFromBidResponse(final FBAdBidResponse bidResponse) {
  // Setup the listener
  final InterstitialAdListener listener = new InterstitialAdListener() {
    @Override
    public void onInterstitialDisplayed(Ad ad) {
      Log.d(TAG, "Interstitial Displayed");
    }

    @Override
    public void onInterstitialDismissed(Ad ad) {
      Log.d(TAG, "Interstitial Dismissed");
      if (interstitialAd != null) {
        interstitialAd.destroy();
        interstitialAd = null;
      }
    }

    @Override
    public void onError(Ad ad, AdError error) {
      Log.d(TAG, "Interstitial failed to load: " + error.getErrorMessage());
    }

    @Override
    public void onAdLoaded(Ad ad) {
      // Show the ad when ready
      if (interstitialAd != null && interstitialAd.isAdLoaded()) {
        interstitialAd.show();
      }
    }

    @Override
    public void onAdClicked(Ad ad) {
      Log.d(TAG, "Interstitial clicked!");
    }

    @Override
    public void onLoggingImpression(Ad ad) {
      Log.d(TAG, "Interstitial impression logged!");
    }
  };

  // Create the ad object
  interstitialAd = new InterstitialAd(context, bidResponse.getPlacementId());
  interstitialAd.setAdListener(listener);
  // Call the loadAdFromBid method
  interstitialAd.loadAdFromBid(bidResponse.getPayload());
}

We use InterstitialAd class in the example above, but the same process applies to other supported ad formats. Similar to normal ad loading, in client side bidding integration you will need to create the ad object and specify the corresponding ad listener object to handle the callback methods. The difference is that instead of calling loadAd() method, you call the loadAdFromBid() method with the payload from the bid response, which you can get from bidResponse.getPayload(). The callback methods of the listener work the same as normal ad object listeners.

iOS

iOS - 1. Getting the bidding SDK module

Download the bidding kit and unzip it. Drag and drop both FBAudienceNetwork.framework and FBAudienceNetworkBiddingKit.framework into your project in XCode. Select "Copy files if needed" and click finish. In the source code, you will be able to import the bidding kit by adding:

#import <FBAudienceNetwork/FBAudienceNetwork.h>
#import <FBAudienceNetworkBiddingKit/FBAudienceNetworkBiddingKit.h>

iOS - 2. Sending the bid request

In your iOS code, create a bid request like this:

// Initiate a request to load an ad.
[FBAdBidRequest getAudienceNetworkBidForAppID:appID
                                  placementID:placementID
                                     adFormat:FBAdBidFormatInterstitial
                             responseCallback:^(FBAdBidResponse *bidResponse) {
    // Handle the bidResponse
    // ...
}];

In the sample we are using FBAdBidFormatInterstitial. The list of ad formats supported are included in the FBAdRequest.h header file:

typedef NS_ENUM(NSInteger, FBAdBidFormat) {
    // Bid For Banner 300x50
    FBAdBidFormatBanner_300_50,
    // Bid For Banner 320x50
    FBAdBidFormatBanner_320_50,
    // Bid For Banner with flexible width and height 50
    FBAdBidFormatBanner_HEIGHT_50,
    // Bid For Banner with flexible width and height 90
    FBAdBidFormatBanner_HEIGHT_90,
    // Bid For Banner with flexible width and height 250
    FBAdBidFormatBanner_HEIGHT_250,
    // Bid For Interstitial
    FBAdBidFormatInterstitial,
    // Bid For Native
    FBAdBidFormatNative,
    // Bid For Rewarded Video
    FBAdBidFormatRewardedVideo,
    // Bid For Instream Video
    FBAdBidFormatInstreamVideo
};

iOS - 3. Running the auction

In this part, we take the bid response from Audience Network and compare it with CPM prices from other buyers, and decide whether the Audience Network wins and load the ad, or it loses. When you are determined with the result of the auction, call the methods notifyWin or notifyLoss to notify Facebook about the result.

Note that the auction logic is implemented by the app itself. It should be simply comparing bid prices and choosing the highest bidder as the auction winner.

Here is an example of how to use the returned bidResponse and run an auction in an iOS app.

self.interstitialAd = [[FBInterstitialAd alloc] initWithPlacementID:placementID];

// Set a delegate to get notified on changes or when the user interact with the ad.
self.interstitialAd.delegate = self;

// Initiate the request to load the ad.
[FBAdBidRequest getAudienceNetworkBidForAppID:appID
                            placementID:placementID
                               adFormat:FBAdBidFormatInterstitial
                       responseCallback:^(FBAdBidResponse *bidResponse) {
    if ([bidResponse isSuccess]) {
        self.bidPayLoad = [bidResponse getPayload];
        self.bidPrice = [bidResponse getPrice];

        if (self.bidPrice < otherPrice) {
            NSLog([NSString stringWithFormat:@"Ad bid failed with bid price: %.2f below other price: %.2f", self.bidPrice, otherPrice]);
            // Call notifyLoss when bid from Audience Network is lost.
            [bidResponse notifyLoss];
            return;
        }
        // Call notifyWin when bid from Audience Network is won.
        [bidResponse notifyWin];

        // Load ad with bid pay load
        [self.interstitialAd loadAdWithBidPayload:self.bidPayLoad];
    } else {
        self.adStatusLabel.text = [bidResponse getErrorMessage];
    }
}];

The FBAdBidRequest has a default time out of 1000 milliseconds. It can be changed by giving maxTimeoutMS parameter to getAudienceNetworkBid method. When a bid times out, Bidding Kit sends timeout notification back to Facebook, and returns bidResponse with isSuccess as false, as well as "Bid timeout" in getErrorMessage.

Here is an example of how to request a bid with timeout in an iOS app.

// Initiate the request to load the ad.
[FBAdBidRequest getAudienceNetworkBidForAppID:appID
                            placementID:placementID
                               adFormat:FBAdBidFormatInterstitial
                           maxTimeoutMS:500
                       responseCallback:^(FBAdBidResponse *bidResponse) {
    if ([bidResponse isSuccess]) {
        // ...
    } else {
        self.adStatusLabel.text = [bidResponse getErrorMessage]; // When bid timeout, will see "Bid timeout - Please consider increasing the timeout."
    }
}];

iOS - 4. Loading the ad

When the Audience Network bid wins an auction, the next step is to use the bid response with loadAdWithBidPayload method to retrieve an ad and then show it. Similar to normal ad loading, in client side bidding integration you will need to create the ad object and specify the corresponding ad listener object to handle the callback methods. The difference is that instead of calling loadAd method, you call the loadAdWithBidPayload with the payload from the bid response, which you can get from [bidResponse getPayload]. The callback methods of the listener works the same as normal ad object listeners.

Note that ads can be cached on the client but must be shown within 60 minutes of when they are loaded. Any impressions based on a cached ad more than 60 minutes won't be paid.

[self.interstitialAd loadAdWithBidPayload:self.bidPayLoad];

When loading the ad you need to specify the delegate to the ad object just like loading the ad normally. Here is how you can implement the delegate:

Declare your ViewController implements the FBInterstitialAdDelegate protocol:

@interface InterstitialViewController : UIViewController <FBInterstitialAdDelegate>

Then implement the delegate functions:

#pragma mark - FBInterstitialAdDelegate implementation

- (void)interstitialAdDidLoad:(FBInterstitialAd *)interstitialAd
{
  NSLog(@"Interstitial ad was loaded. Can present now.");

  // Ad is ready, present it!
  [self.interstitialAd showAdFromRootViewController:self];
}

- (void)interstitialAd:(FBInterstitialAd *)interstitialAd didFailWithError:(NSError *)error
{
  NSLog(@"Interstitial failed to load with error: %@", error.description);
}

- (void)interstitialAdDidClick:(FBInterstitialAd *)interstitialAd
{
  NSLog(@"Interstitial was clicked.");
}

- (void)interstitialAdDidClose:(FBInterstitialAd *)interstitialAd
{
  NSLog(@"Interstitial closed.");

  // Optional, Cleaning up.
  self.interstitialAd = nil;
}

- (void)interstitialAdWillClose:(FBInterstitialAd *)interstitialAd
{
  NSLog(@"Interstitial will close.");
}

- (void)interstitialAdWillLogImpression:(FBInterstitialAd *)interstitialAd
{
  NSLog(@"Interstitial impression is being captured.");
}

Above is how you can use bidding to get and show an interstitial ad. For other ad formats, the process is similar, you will need to change FBInterstitialAd into other supported format, and change the delegate class as well. For more details, please refer to the sample app included in the Audience Network Bidding Kit download from above.

What is Next

More Resources

Getting Started Guide

Technical guide to get started with Audience Network

Audience Network Mobile App Bidding Overview

Facebook Audience Network Mobile App Bidding architecture and other Concepts

Mobile App Server-to-Server Bidding Integration

Step-by-Step tutorial for mobile app server-to-server bidding integration

Mobile App Client-to-Server Bidding Integration

Step-by-Step tutorial for mobile app client-to-server bidding integration

Audience Network Mobile SDK Downloads

Latest versions of Audience Network SDK downloads page