Android Setup

In-house mediation is not publicly available

In-house bidding with Audience Network is currently in Closed Beta and is not publicly available. We'll provide further updates if this changes.

As an alternative, you can access Audience Network Bidding through one of the mediation platforms we partner with.

Library Integration

Step 1: Import your library as a module to your project

Go to File > Project Structure.

Add a new module.

Add the library as a dependency to your module.

Step 2: Add the library to your app module dependencies

dependencies {
   ...
   implementation project(':biddingkit-release')
}
}

Code Integration

Call the following before calling any other method in the SDK:

BiddingKit.init(Context context)

Call once only, at app startup.
Either call with no context to use the default configuration, or use your own configuration in JSON format: BiddingKit.init(context context, string configuration)

Sample Configuration

{
"auction" :
 { "timeout_ms" : 10000 }
}
"facebook":
{ 
  "bid_url" : "https://an.facebook.com/placementbid.ortb"
}
"applovin":  
{
   "bid_url" : "https://bid.applovin.com/header_facebook"
}
"tapjoy": 
{
  "bid_url": "https://bid.tapjoy.com/facebook/request"
}
"chartboost": 
{
   "bid_url": "https://da.chartboost.com/auction/facebookbiddingkit**"*
  }
}

Parameters	Sub-Parameters	Type	Description
`auction`	`timeout_ms`	`string`	The total amount of time in ms after which you want the auction to return. This value is for the whole auction and not a single bidder. The default timeout for auction is 10000ms (10 seconds).
`facebook`	`bid_url`	`string`	The address for which you want the Facebook Bidder to make the request.
`facebook`	`notify_url`	`string`	The address for which you want the Facebook Bidder to send the notifications.
`applovin`	`bid_url`	`string`	The address for which you want the Applovin Bidder to make the request.
`tapjoy`	`bid_url`	`string`	The address for which you want the Tapjoy Bidder to make the request.
`chartboost`	`bid_url`	`string`	The address for which you want the Chartboost Bidder to make the request.

Using Auction / Ab Auction

Make sure you have completed Code Integration before using this section.

Waterfall and WaterfallEntry

Implement the following interfaces:

WaterfallEntry

Contains an entry in your Waterfall.

The bid is the bid returned for the given bidder. Can be null if this entry wasn't made from a bidder.
The bidderName is an Identifier for the given entry
The CPMCents is the historical value for your CPM or the bidding returned value.

{
public interface WaterfallEntry {
   // return the bid for this waterfall entry, if it exists,
   // otherwise return null
   Bid getBid();
   // return the CPM in cents for this waterfall entry
   double getCPMCents();
   // return the bidder name for this waterfall entry
   String getBidderName();
}
}

Waterfall

Contains a list of Waterfall entries, sorted by CPMCents.

public interface Waterfall {
  
   // This method will create a copy of the existing Waterfall.
   // We do not need to also create a copy of the WaterfallEntries
   // Returns a copy of the current waterfall.
   Waterfall createWaterfallCopy();
   // creates a WaterFallEntry with the given bid   and inserts it into
   // the waterfall
   void insert(Bid bid);
   // inserts the given WaterfallEntry into the Waterfall
   void insert(WaterfallEntry waterfallEntry);
   // returns an Iterable of WaterfallEntry for this Waterfall
   Iterable<WaterfallEntry> entries();
}

ABTest and ABTestSegment (if using AbAuction)

Implement the following interfaces:

public interface ABTestSegment {
   // will return an identifier for the experiment
   String getSegment();
}

public interface ABTest {
   // equally splits the users into different segments
   ABTestSegment getCurrent();
}

You must implement these interfaces yourself. They are not part of the API.
Create the segments and add them to the ABTest.

Sample

ABTest abTest = new ABTestImpl();
ABTestSegment testA = new ABTestSegmentImpl();
ABTestSegment control = new ABTestSegmentImpl();
// the addSegment method is not mandatory and not part of our API
abTest.addSegment(testA);
abTest.addSegment(control);

Bidder (if using Auction)

Bidder facebookBidder = new FacebookBidder.Builder(
   // Your app id
   "YOUR_APP_ID",
   // Your placement id
   "YOUR_PLACEMENT_ID",
   // The format you want to use
   FacebookAdBidFormat.INTERSTITIAL,
   // The bidder token from the Audience network SDK
   BidderTokenProvider.getBidderToken(getBaseContext()))
   // You can set various parameters, one of them being
   // test mode.
   .setTestMode(true)
   .build();
  
Bidder applovinBidder = new AppLovinBidder.Builder(
   // the package name of your application (appId)
   getApplication().getPackageName(),
   // the platformId of your application
   "Android",
   // The format you want to use
   AppLovinAdFormat.INTERSTITIAL,
   // The bidder token from the AppLovin SDK
   applovinBidToken)
   // You can set various parameters, one of them being
   // test mode.
   .setTestMode(true)
   .build();
  
Bidder tapjoyBidder = new TapjoyBidder.Builder(
   // Your tapjoy SDK key, available on the tapjoy website
   TAPJOY_SDK_KEY,
   // Your placement name
   "Interstitial",
   // The format you want to use
   TapjoyAdFormat.INTERSTITIAL,
   // The user token from the Tapjoy SDK (Tapjoy.getUserToken())
   tapjoyBidToken)
   // You can set various parameters, one of them being
   // test mode.
   .setTestMode(true)
   .build();   
  
Bidder ironSourceBidder = new IronSourceBidder.Builder(
   // Your app id
   "YOUR_APP_ID",
   // Your placement id
   "YOUR_PLACEMENT_ID",
   // The format you want to use
   IronSourceAdFormat.INTERSTITIAL,
   //The token from the IronSource SDK (IronSource.getISDemandOnlyBiddingData())
   token)
   // You can set various parameters, one of them being
   // test mode.
   .setTestMode(true)
   .build();

Bidder vungleBidder = new VungleBidder.Builder(
   // Your app id
   "YOUR_APP_ID",
   // Your app name
   "YOUR_APP_NAME",
   // Your placement id
   "YOUR_PLACEMENT_ID",
   // The format you want to use
   VungleAdFormat.INTERSTITIAL,
   //The token from the Vungle SDK (Vungle.getAvailableBidTokens())
   vungleToken,
   // Your publisher id
   "YOUR_PUBLISHER_ID")
   .setTestMode(true)
   .build();

Bidder chartboostBidder = new ChartboostBidder.Builder(
   "YOUR_APP_ID",
   "YOUR_PLACEMENT_ID",
   "YOUR_PUBLISHER_ID",
   "YOUR_PUBLISHER_NAME",
   ChartboostAdFormat.INTERSTITIAL,
   "YOUR_STORE_URL",
   new String[]{"YOUR_CATEGORIES"},
   Chartboost.getSDKVersion())
   // You can set various parameters, one of them being
   // test mode.
   .setTestMode(true)
   .build();

Auction

An object to which you will pass all the bidders.
You can call startRemoteAuction only once on Auction

// Create an auction using Auction.Builder
Auction auction = new Auction.Builder()
               // You can add multiple bidders
               .addBidder(facebookBidder)
               .build();

Ab Auction

To run an AbTest, use +AbAuction

This is an object to which you will pass all the bidders and segments you want the bidders to belong to.
You can call startRemoteABAuction only once on an ABAuction.

// Create an auction using ABAuction.Builder
// You need to pass it the instance of your abTest
ABAuction auction = new ABAuction.Builder(abTest)
               // You can add multiple bidders to a certain segment
               // we will choose the bidders to run based on what
               // ABTest.getCurrent() will return
               .addBidder(testA, facebookBidder)
               // For a control group you can use addSegment,
               // which will require no bidders
               .addSegment(control)
               .build();

Implement the AuctionListener class (if using Auction)

public interface AuctionListener {
   // This method will be called when we populated the waterfall with all
   // entries and finished bidding.
   // The waterfall parameter is a copy of your original waterfall with
   // the added bidding waterfall entries
   //
   // In the method you should
   // 1. Do auction.notifyDisplayWinner(mAbTest, displayWinnerBid);
   //   a. You should call this before showing the ad.
   //   b. We need this in order to know who won the bid and is going
   //      to be shown
   // 2. Use the waterfall to show the desired ad.
   void onAuctionCompleted(Waterfall waterfall);
}

Start the Auction

Auction

auction.startRemoteAuction(
               // Base url for Bidding Kit Server
               "https://example.com"
               // A instance of the Waterfall class you implemented
               waterfall,
               // A instance of the AuctionListener you implemented
               new AuctionListenerImpl());

AbAuction

auction.startRemoteABAuction(
               // Base url for Bidding Kit Server
               "https://example.com"
               // A instance of the Waterfall class you implemented
               waterfall,
               // A instance of the AuctionListener you implemented
               new AuctionListenerImpl());

Sample Code

// Initialise by calling BiddingKit.init().
// You can also pass your configuration here
// BiddingKit.init(Context context, String configuration)
BiddingKit.init(getApplication());

// 1. Create the waterfall and add all the entries we have
mWaterfall = new WaterfallImpl();
mWaterfall.insert(new WaterfallEntryImpl("NetworkA", 5));
mWaterfall.insert(new WaterfallEntryImpl("NetworkB", 7));
mWaterfall.insert(new WaterfallEntryImpl("NetworkC", 3));

// 3. Create the AppLovin/Facebook bidder
Bidder facebookBidder = new FacebookBidder.Builder(
       "YOUR_APP_ID",
       "YOUR_PLACEMENT_ID",
       FacebookAdBidFormat.INTERSTITIAL,
       // getBidderToken call is slow, use AsyncTask to get this value
       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(); 
Bidder ironSourceBidder = new IronSourceBidder.Builder(
       "YOUR_APP_ID",
       "YOUR_PLACEMENT_ID",
       IronSourceAdFormat.INTERSTITIAL,
       ironSourceToken)
       .build();    
Bidder chartboostBidder = new ChartboostBidder.Builder(
       "YOUR_APP_ID",
       "YOUR_PLACEMENT_ID",
       "YOUR_PUBLISHER_ID",
       "YOUR_PUBLISHER_NAME",
       ChartboostAdFormat.INTERSTITIAL,
       "YOUR_STORE_URL",
       new String[]{"YOUR_CATEGORIES"},
       Chartboost.getSDKVersion())
       .build();
Bidder vungleBidder = new VungleBidder.Builder(
       // Your app id
       "YOUR_APP_ID",
       // Your app name
       "YOUR_APP_NAME",
       // Your placement id
       "YOUR_PLACEMENT_ID",
       // The format you want to use
       VungleAdFormat.INTERSTITIAL,
       //The token from the Vungle SDK (Vungle.getAvailableBidTokens())
       vungleToken,
       // Your publisher id
       "YOUR_PUBLISHER_ID")
       .setTestMode(true)
       .build(); 

// 4. Create an auction
auction = new Auction.Builder()
       .addBidder(testA, facebookBidder) // add segment with bidder
       .addBidder(testA, applovinBidder)
       .addBidder(testA, tapjoyBidder)
       .addBidder(testA, ironSourceBidder)
       .addBidder(testA, chartboostBidder)
       .addBidder(testA, vungleBidder)
       .addBidder(control, null) // add a segment with no bidders              
       .build();

// 6. Implement AuctionListenerImpl

// 7. Call startAuction
auction.startRemoteAuction(
       mWaterfall,
       new AuctionListenerImpl() {
           @Override
           public void onAuctionCompleted(Waterfall resultWaterfall) {
               // resultWaterfall contains your original waterfall entries
               // along with the real time bids

               // Our implementation of waterfall has the entries sorted by CPM so
               // we get the highest price for the first entry
               WaterfallEntry winnerWaterfallEntry =
                       resultWaterfall.entries()
                               .iterator()
                               .next();
               if (winnerWaterfallEntry.getEntryName().equals(biddingConstants.FACEBOOK_BIDDER)) {
                   Bid bid = waterfallEntry.getBid();
                   interstitialAd = new InterstitialAd(
                           getBaseContext(),
                           bid.getPlacementId());
                   interstitialAd.loadAd(
                           interstitialAd.buildLoadAdConfig()
                                   .withAdListener(that)
                                   .withBid(bid.getPayload())
                                   .build());
               } else {
                    // Handle other networks
               }
               // Notify about the display winner just before displaying the ad
               auction.notifyDisplayWinner(winnerWaterfallEntry);
           }
       });

Using Standalone Facebook Bidder

Before using any of the below please initialise the SDK as above.

Step 1: Create `BidderWithNotifier`

public @Nullable BidderWithNotifier createStandaloneBidder() {
    return new FacebookBidder.Builder(
        mAppId,
        mPlacementId,
        mAdBidFormat,
        BidderTokenProvider.getBidderToken(getBaseContext()))       
        .buildWithNotifier();
    }
}

Step 2: Implement `BidResponseCallback`

new BidResponseCallback() {
    @Override
    public void handleBidResponse(BidWithNotification bidResponse) {
        boolean facebookWon = true;
        // we decide Facebook won
        if (facebookWon) {
            bidResponse.notifyWin();
            // Show Ad using the Facebook Audience Network SDK
        } else {
            // Facebook did not win we call loss
            bidResponse.notifyLoss();
        }               
    }

    @Override
    public void handleBidResponseFailure(String errorMessage) {
        // Getting a bid failed
        Log.e(TAG, errorMessage);
    }
}

Step 3: Call `retrieveBidWithNotificationCompleted`

It’s important to call notifyWin/notifyLoss if you get a bid response.

BidderWithNotifier facebookBidder = createStandaloneBidder();
facebookBidder.retrieveBidWithNotificationCompleted(new BidResponseCallback() {
    @Override
    public void handleBidResponse(BidWithNotification bidResponse) {
        boolean facebookWon = true;
        // we decide Facebook won
        if (facebookWon) {
            bidResponse.notifyWin();
            // Show Ad using the Facebook Audience Network SDK
        } else {
            // Facebook did not win we call loss
            bidResponse.notifyLoss();
        }
    }

    @Override
    public void handleBidResponseFailure(String errorMessage) {
        Log.e(TAG, errorMessage);
    }
});

Transitioning from Bidding Kit 1.0

Bidding Kit 1

// Previously no need for 
// initialisation
//

// Create Bid Request
FBAdBidRequest bidRequest =
    new FBAdBidRequest(
    this, // activity
    "YOUR_APP_ID",
    "YOUR_PLACEMENT_ID",
    FBAdBidFormat.INTERSTITIAL)
    .withPlatformId("YOUR_PLATFORM_ID")
    .withTimeoutMS(2000)
    .withTestMode(
        AdSettings.isTestMode(this));
        
// Make the request
bidRequest.getFBBid(
    new FBAdBidRequest
        .BidResponseCallback() {
        @Override
        public void handleBidResponse(
            final FBAdBidResponse 
                bidResponse) {
            // handle error cases
            // and error message

            // load the ad from bid
            // if it's the winning bid        }
        }
});

Bidding Kit 2

// Intialise as soon as possible
` ``BiddingKit``.``init``(`
`    ``this``.``getApplicationContext()``);`
`    `
`// Create BidderWithNotifier`
`BidderWithNotifier`` bidder ``=`
    `new`` ``FacebookBidder``.``Builder``(`
        `"YOUR_APP_ID"``,`
        `"YOUR_PLACEMENT_ID"``,`
        `FacebookAdBidFormat``.``NATIVE``,`
        `bidToken``)`` ``// bid token from AN SDK`
    `.``setPlatformId``(``"YOUR_PLATFORM_ID"``)`
    `.``setTestMode``(`
`        ``AdSettings``.``isTestMode``(``this``))`
`    ``.``buildWithNotifier``();`
`    `
`// Make the Request`
`bidder`
`.``retrieveBidWithNotificationCompleted``(`
    `new`` ``BidResponseCallback``()`` ``{`
`        ``@Override`
        `public`` ``void`` handleBidResponse``(`
            final `BidWithNotification`` `
                `bidResponse``)`` ``{`
`            ``// load the ad from bid`
`            ``// if it's the winning bid`

            `// notify with ``notifyWin`
`            ``// or notifyLoss
            bidResponse.notifyWin();`
        `}`

        `@Override`
        `public`` ``void`` `
`            handleBidResponseFailure``(`
`                ``final`` ``String`` errorMessage``){`
            // Bid Failed
            // Handle error          `          `
`        ``}`
`});`