Integrating bidding from your mobile application (client side)

Facebook Audience Network has an ORTB bidder which competes for app, mobile web, and video impressions; either directly from the client (actual mobile devices), or from a server (auction platform). We support both direct publisher integrations and mediated integrations. This guide describes how you can integrate with bidding from your mobile app (client side).

In this document we guide you to use the bidding kit to integrate with Audience Network mobile app bidding from your Android or iOS app. For more details on our bidding endpoint, please read this document on ORTB bidding.

Bidding typically consists of the following steps:

  • Getting the bidding kit for your platform
  • Sending a bid request to Audience Network bidding endpoint
  • Running an auction to decide the winning bid using the CPM price in the bid response
  • Loading the ad from the winning bid by the buyer's SDK

We will be using the example of bidding on an interstitial ad in the step-by-step guide below. Make sure that you are already familiar with using Audience Network interstitial ads. Bidding also supports Native, Banner, Interstitial, In-stream Video and Rewarded Video formats. When you are using ad formats other than interstitial for bidding, you can change the corresponding ad format classes. For more details please refer to the sample apps included in the bidding kit.

Step-by-Step

Android

Android - 1. Getting the bidding SDK module

Android - 2. Sending the bid request

Android - 3. Running the auction

Android - 4. Loading the ad

iOS

iOS - 1. Getting the bidding SDK module

iOS - 2. Sending the bid request

iOS - 3. Running the auction

iOS - 4. Loading the ad

Getting the bidding kit

Please approach your Audience Network representative at Facebook for the bidding kits. The bidding kit will contain the necessary libraries to integrate bidding on the client side, and a reference sample app that demonstrates how it can be done.

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.

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.

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

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

Finally, loading the ad from bid response is similar to the normal ad loading:

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.

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];
    }
}];

iOS - 4. Loading the ad

Finally, loading ads from bid response using loadAdWithBidPayload:

[self.interstitialAd loadAdWithBidPayload:self.bidPayLoad];

When loading the ad you need to specify the delegate to the ad object just like loading 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.