Bidding with In-House Mediation

API Reference

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.

This section applies if you are using Bidding Kit Server as a standalone product.

If you are integrating with Bidding KIt 3, this section does not apply.

Auction Endpoint

/bks/auction

Description

Bidding Kit Server accepts auction requests on this endpoint, which sends bid requests to individual bidders, collects responses, runs the auction, sends notification to bidders, merges waterfall entries with bids from all the bidders and responds back with a consolidated list of bidders and waterfall entries sorted according to price

URL Structure

http:///bks/auction

POST Method

Request parameters

Request body sent to the auction endpoint looks similar to this

{ 
   "bidder_data":{ 
      "facebook":{
         <request> // request for facebook bidder, optional, set this field when you 
                    want to send bid request to facebook bidder, please see section 
                    below for more details
      },
      "applovin":{ 
         <request> // request for applovin bidder, optional, set this field when you 
                    want to send bid request to applovin bidder, please see section 
                    below for more details
      },
      "tapjoy":{ 
         <request> // request for tapjoy bidder, optional, set this field when you 
                    want to send bid request to tapjoy bidder, please see section 
                    below for more details 
      },
      "chartboost":{ 
         <request> // request for chartboost bidder, optional, set this field when 
                    you want to send bid request to chartboost bidder, please see 
                    section below for more details 
      },
      "ironsource":{ 
         <request> // request for ironsource bidder, optional, set this field when 
                    you want to send bid request to ironsource bidder, please see 
                    section below for more details 
      "vungle":{ 
         <request> // request for vungle bidder, optional, set this field when 
                    you want to send bid request to vungle bidder, please see 
                    section below for more details 
      }
   },
   "waterfall_entries": [
       {
          "name":<string>, // name for the waterfall entry
          "cpm":<double>  // cpm in cents for this entry
       }
   ]
}
Parameters Type Description

bidder_data

map(string, JSON)

Mapping from bidder name to request sent to that bidder. Currently only facebook, applovin and tapjoy are supported. You could add more bidders if you want following instructions in the tech doc. More details about requests for each bidder can be found in sections below.

waterfall_entries

vec(JSON)

A list of waterfall entries passed in the request. This field is optional if you choose not to pass any waterfall entries in the request. If you do, these waterfall entries will be merged with bids from the bidders and be returned in a sorted list in the response of Bidding Kit Server.

waterfall_entries.name

string

Name of this waterfall entry. This is an identifier for each waterfall entry, used to distinguish each. This will be returned in the response.

waterfall_entries.cpm

double

CPM (in cents) for this waterfall entry. This will be used to sort when waterfall entries are merged with bids from bidders.

Request for Facebook bidder

{
   "id":<string>,
   "imp":[ 
       {
           "id":<string>,
           "banner": {
               "w":<int>,
               "h":<int>,
           },
           "native":{
               "w":<int>,
               "h":<int>,
           },
           "video":{
               "w":<int>，
               "h":<int>,
               "linearity":<int>,
               "ext":{
                   "videotype":<string>,
               },
           },
           "tagid":<string>,
           "instl":<int>,
        }
   ],
   "app":{
       "publisher" => {
           "id":<string>,
       },
   },
   "device":{
       "ua":<string>,
       "ifa":<string>,
       "dnt":<int>,
       "lmt":<int>,
   },
   "regs":{
       "coppa":<int>,
   },
   "user":{
       "buyeruid":<string>,
   },
   "ext":{
      "platformid":<string>, 
   },
   "at":<int>,
   "tmax":<int>,
   "test":<int>,
}
Parameters Type Description

id

string

Platform's auction identifier, auction ID. Randomly generated token to identify each auction opportunity. This id should be the same for all bidders in the same request.

imp

vec(JSON)

List of slots to bid on.

imp.id

vec(JSON)

Platform's identifier for this slot auction, won’t affect the bidding function.

imp.banner

JSON

Pptional field, present only for banner impression opportunities. One of imp.banner, imp.native or imp.video has to appear in the request. Accepted ad formats can be found in Auction Server Setup Guide.

imp.banner.w

integer

Width.

imp.banner.h

integer

Height.

imp.native

JSON

Optional field, present only for native impression opportunities. One of imp.banner, imp.native or imp.video has to appear in the request. Accepted ad formats can be found in Auction Server Setup Guide.

imp.native.w

integer

Width.

imp.native.h

integer

Height.

imp.video

JSON

Optional field, present only for video impression opportunities. One of imp.banner, imp.native or imp.video has to appear in the request. Accepted ad formats can be found in Auction Server Setup Guide. Please note that instream video is not allowed.

imp.video.w

integer

Width.

imp.video.h

integer

Height.

imp.video.linearity

integer

Optional field, instream video opportunity when set to 1.

imp.video.ext

JSON

Optional field, present if you want to specify the video type.

imp.video.ext.videotype

string

rewarded for Rewarded Video impression opportunities.

imp.tagid

string

Placement ID.

imp.instl

integer

Interstitial flag. Optional field. On when set to 1, Off when set to 0. app JSON app details.

app

JSON

App details.

app.publisher

JSON

Publisher details.

app.publisher.id

string

Publisher Facebook app ID.

device

JSON

Device details.

device.ua

string

Device user agent.

device.ifa

string

Identifiers for Advertisers, ID sanctioned for advertiser use.

device.dnt

integer

“do not track”, user’s preference regarding tracking. Optional field. On when set to 1, Off when set to 0. If this field is set to 1, Facebook won’t be able to match the users for this request.

device.lmt

integer

“limit ads tracking”, user’s preference to opt-out of having an ID for Advertisers (IDFA/IFA). Optional field. On when set to 1, Off when set to 0. If this field is set to 1, Facebook won’t be able to match the users for this request..

regs

JSON

Regulations object.

regs.coppa

integer

US FTC regulations for Children's Online Privacy Protection Act. Optional field. On6r when set to 1, “Off” when set to 0.

user

JSON

User details.

user.buyeruid

string

Facebook Audience Network Bidder Token. Mandatory field.

ext.platformid

string

Mediation partner Platform ID or publisher Facebook app ID. Mandatory field.

tmax

integer

Auction timeout in milliseconds. This is the maximum time allowed to return a bid. If in tmax time, Bidding Kit Server is not able to get any bids from the bidder, it’ll immediately return no bid for this bidder.

test

integer

normal when set to 0, test mode when set to 1. Facebook bidder will bid $99.99, but don't pay out in test mode.

Request for AppLovin bidder

Refer to Applovin’s documentation when you want to get bids from them. Bidding Kit Server won’t check or modify the requests for Applovin bidder, and will send them directly to the bidder.

Request for Tapjoy bidder

Refer to Tapjoy’s documentation when you want to get bids from them. Bidding Kit Server won’t check or modify the requests for Tapjoy bidder, and will send them directly to the bidder.

Request for Chartboost bidder

Refer to Chartboost's documentation when you want to get bids from them, and request the document “Chartboost Programmatic Supply Integration Guide for Facebook Bidding Kit 09172020.pdf” from your SPM.

Bidding Kit Server won’t check or modify the requests for Chartboost bidder, and will send them directly to the bidder.

Request for Ironsource bidder

Refer to Ironsource's documentation when you want to get bids from them, and request the document “BKSironSource-SDK-In-App-Bidding.pdf” from your SPM.

Request for Vungle bidder

Refer to Vungle’s documentation when you want to get bids from them, and request the document “External - Vungle Header Bidding oRTB Specification.pdf” from your SPM.

Response

{
    "auction_id":<string>,
    "notification_data":<string>,
    "bids": [
        {
            "name":<string>,
            "price":<double>,
            "cur":<string>,
            "is_bidder":<boolean>,
            "adunit_id":<string>,
            "sdk_rendering_data": {
                "bid_payload":<string>
            }
            "ext": {
                "encrypted_cpm":<string>
            }
        }
    ]
}
Parameters Type Description

auction_id

integer

Auction ID passed in the request.

notification_data

string

Essential token for display notification. Should be echoed back in display notification API.

bids

vec(JSON)

Details of the bids and waterfall entries. Elements in this list will be sorted ascendent by price.

bids.name

string

Name of the bidder or waterfall entries passed in the request.

bids.price

string

Price in US dollars.

bids.cur

string

Currency of the bid, currently only US dollars (“USD”).

bids.adunit_id

string

Ad unit id needed by bidders to load and show ads. If a bidder doesn’t need this ID, Bidding Kit Server will return an empty string. This field will only present in bids, not in waterfall entries.

bids.sdk_rendering_data.bid_payload

string

Bid payload for SDK to render the ads.

bids.encrypted_cpm

string

Encrypted blob of impression information. Can be used to get aggregated revenue data by publishers.

Notify Display Endpoint

/bks/notifyDisplay

Description

This endpoint will accept a request when the ad is displayed and send the display notification to bidders.

URL Structure

http:///bks/notifyDisplay

POST Method

Request Parameters

{
   {
    "auction_id":<string>,
    "clearing_price_cents":<double>,
    "notification_data":<string>
    "name":<string>
}
Parameters Type Description

auction_id

integer

Auction ID passed in the bid request.

clearing_price_cents

double

Clearing price in cents.

notification_dataString

string

Value returned as notification_data in auction response.

bids.name

string

Name of the winner.

Response

200 OK

See Also