Implement Bidding with In-House Mediation in your Android App

This topic explains how to integrate Bidding Kit 2.0 with your Android app. Integration requires the following steps:

  1. Import the Bidding Kit 2.0 Module
  2. Initialize Bidding Kit 2.0
  3. Implement the Waterfall and WaterfallEntry Interfaces
  4. Add Bidders
  5. Implement Auction

1. Import the Bidding Kit 2.0 Module

Import the Bidding Kit 2.0 module into your Android Studio project as follows:

  1. Contact your Facebook business representative to get access to biddingkit-release.aar.
  2. In the Android Studio File menu, select New > New Module.
  3. In the New Module dialog, select Import .JAR/.AAR Package and then click Next.
  4. In the Import Module from Library dialog, navigate to the location of your biddingkit-release.aar file and then click Finish.
  5. In your app's build.gradle file, add a dependency for biddingkit-release as shown in the following example.
dependencies {
    ...
    implementation project(':biddingkit-release')
}

2. Initialize Bidding Kit 2.0

When your app starts up, pass the calling context to the BiddingKit.init method before calling any other Bidding Kit 2.0 method.

BiddingKit.init(getApplication());

You can also pass an optional configuration to the init method that specifies bidding endpoints and the timeout for the auction. This configuration should be formatted as a JSON string, as shown in the following example.

{
    "auction":  { "timeout_ms" : 10000 }, 
    "facebook": { "bid_url": "https://an.facebook.com/placementbid.ortb" },
    "applovin": { "bid_url": "https://a.applovin.com/header/facebook" },
    "tapjoy":   { "bid_url": "https://bid.tapjoy.com/facebook/request" }
}

3. Implement the Waterfall and WaterfallEntry Interfaces

Bidding Kit 2.0 uses the Waterfall and WaterfallEntry interfaces to read from and interact with your in-house implementation of a waterfall. Your application needs to implement both of these interfaces.

The Waterfall.entries method should return an Iterable of type WaterfallEntry, sorted by the value returned by the entry's getCPMCents method. Each WaterfallEntry represents the amount that a network is willing to pay for the impression, based on either the historical CPM or a real-time bid.

The following example demonstrates how to use your application's Bidding Kit 2.0 implementation to create a waterfall with three entries.

The Impl suffixes in this example indicate a class that is your application's implementation of the underlying Bidding Kit 2.0 interface. This example also assumes that your WaterfallEntry implementation has a constructor with the signature public WaterfallEntryImpl(String name, double cpmCents).

Waterfall mWaterfall = new WaterfallImpl();
mWaterfall.insert(new WaterfallEntryImpl("NetworkA", 5));
mWaterfall.insert(new WaterfallEntryImpl("NetworkB", 7));
mWaterfall.insert(new WaterfallEntryImpl("NetworkC", 3));

4. Add Bidders

Add the bidders that will compete in your auction. Bidding Kit 2.0 defines builders for the Audience Network, AppLovin, and TapJoy ad networks. For other bidders, you can implement the Bidder interface to create an object that you can add to your auction.

Bidder facebookBidder = new FacebookBidder.Builder(
    "YOUR_APP_ID",                     
    "YOUR_PLACEMENT_ID",               
    FacebookAdBidFormat.INTERSTITIAL, 
    BidderTokenProvider.getBidderToken(getBaseContext()))  
    .setTestMode(true) 
    .build();
    
Bidder applovinBidder = new AppLovinBidder.Builder(
    getApplication().getPackageName(),
    "Android",
    AppLovinAdFormat.INTERSTITIAL,
    applovinBidToken)
    .build(); 
    
Bidder tapjoyBidder = new TapjoyBidder.Builder(
    TAPJOY_SDK_KEY,
    "Interstitial",
    TapjoyAdFormat.INTERSTITIAL,
    tapjoyBidToken)
    .build();

5. Create an Auction

Pass your bidders to Auction.Builder to create your auction.

Auction auction = new Auction.Builder()
    .addBidder(facebookBidder)
    .addBidder(applovinBidder)
    .addBidder(tapjoyBidder)
    .build();

Next, implement the AuctionListener interface. This interface's onAuctionCompleted callback method will be invoked when bidding is complete. When invoked, the waterfall parameter contains a copy of your original waterfall with the added entries from the real-time bidders.

When invoked, your implementation of the onAuctionCompleted callback method should do the following:

  1. Call the Auction.notifyDisplayWinner method. This method notifies the winner of the auction so that they can track and serve the ad.
  2. Use the waterfall to display the winning ad.

The Impl suffixes in this example indicate a class that is your application's implementation of the underlying Bidding Kit 2.0 interface. This example also assumes that your Waterfall implementation sorts its entries by CPM, which means that the first entry represents the winner of the auction.

public class AuctionListenerImpl implements AuctionListener {

    @Override
    public void onAuctionCompleted(Waterfall waterfall) {
        WaterfallEntry winnerWaterfallEntry = waterfall.entries().iterator().next();
        if (winnerWaterfallEntry.getEntryName().equals(biddingConstants.FACEBOOK_BIDDER)) {
            Bid bid = waterfallEntry.getBid();
            interstitialAd = new InterstitialAd(
                getBaseContext(),
                bid.getPlacementId());
                interstitialAd.setAdListener(that);
                interstitialAd.loadAdFromBid(bid.getPayload());         
        } else {
            // Handle other networks.
        }
        // Notify the display winner immediately before displaying the ad.
        auction.notifyDisplayWinner(winnerWaterfallEntry);
    }

}

Finally, call the Auction.startAuction method to begin the bidding process. This method can be called only once per Auction. The startAuction method populates your waterfall with all received bids.

The Impl suffixes in this example indicate a class that is your application's implementation of the underlying Bidding Kit 2.0 interface.

auction.startAuction(
    waterfall,
    new AuctionListenerImpl());