Facebook Audience Network App Bidding Overview

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 overview will cover the general concepts of app bidding.

Introduction

What Is App Bidding

App Bidding is a way for publishers to establish an impartial and open auction over their ad inventory by offering every ad opportunity to multiple demand sources in real time. Every demand source has the opportunity to compete and win every impression, when the value is the highest.

Why App Bidding

  • A real-time auction is an opportunity to optimize for every ad request.
  • Provides visibility into the true value of your ad inventory.
  • Easy to maintain and requires less ad operations resources.

Integration Architectures

App bidding is offered through an endpoint that implements the Open Real-Time Bidding (ORTB) protocol to provide bids on individual impression opportunities. Facebook Audience Network SDK is still required in app bidding for 3 functions:

  • Obtain the buyeruid (named bidderToken in Audience Network SDK), which is a required field in the bid request.
  • Load bid response and show an ad in the event of winning an auction.
  • Record impressions and clicks.

Key Steps In Bidding Flow

  • Obtaining bidder token: This is an opaque string that is required for Audience Network to be able to respond to a bid request.

  • Sending bid request and getting bid response: this is the main interaction with the bidding endpoint where you send an ORTB bid request and receive a valid bid response or an error.

  • Running auction: Running an auction is needed to select a winner among bid responses. Auctions can run by in-house server that runs your own custom auction logic, by a 3rd party auction server, by the client directly on the user's device. Note: Since not all demand sources support real-time bids, so most setups include a step where real-time bids are compared with estimated CPMs from other demand sources (e.g. based on historical average CPMs).

  • Retrieving ad with bid response: When Audience Network wins an auction, the next step is to load the ad by using the Audience Network SDK on the user's device and passing it the payload from the bid response. Note that the payload does not contain an ad, it only contains information that allows the SDK to retrieve the ad from Audience Network Server.

Integration Types

When running auction (the 3rd step in above bidding flow), it can be hosted on Client-Side or Server-Side. Below are 3 different integration types:

Client-to-Server Integration Architecture

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.


Server-to-Server Integration Architecture

In server-to-server integration, an auction server calls Facebook Audience Network bidding endpoint and all other demand sources to get bid responses. Then the auction server runs the auction and picks the winning bid. This auction server could be an in-house server running auction logic that you built or it could be a 3rd party server that is integrated with Audience Network's app bidding. This allows you to utilize the server's resources and available network to call the demand sources' bidding endpoints. It also allows you to make changes to these endpoint integrations without necessarily requiring client updates.


External Ad Server Integration

The external ad server integration allows you to bridge today's world of waterfall mediation with app bidding. This works by doing a server-to-server integration with the demand sources that support app bidding and then passing the auction winner to the waterfall mediation platform which runs the waterfall and chooses the overall winning demand source. This integration is meant as an interim bridge between the worlds of waterfall mediation and app bidding. With this integration type you do not need to write your own auction logic.

ORTB Request/Response and Supported Ad Formats

ORTB Request

Our bidding endpoint supports a subset of OpenRTB protocol v2.5.

Note: The site.publisher.id field in the following request must be your Audience Network Business ID.

'id' => string // platform's auction identifier,
'imp' => vec< // slots to bid on
  shape(
    'id' => string, // platform's identifier for this slot auction
    'banner' => ?shape(
      'w' => int, // width
      'h' => int, // height
    ),
    'native' => ?shape(
      'w' => int, // width
      'h' => int, // height
    ),
    'video' => ?shape(
      'w' => int, // width
      'h' => int, // height
      'linearity' => int, // 1 = instream
    ),
    'tagid' => string, // Placement ID or Placement Name
  )
>,
'app' => shape(
  'publisher' => shape(
    'id' => string, // Publisher Business ID
  ),
),
'device' => shape(
  'ua' => string, // device user-agent, required
  // Do not send ip or ipv6 if you are requesting bids from the client device
  // For server-side bid requests only, set one of ip or ipv6
  'ip' => ?string, // device IPv4 (optional, server-side bidding only)
  'ipv6' => ?string, // device IPv6 (optional, server-side bidding only)
  'dnt' => ?int, // 0: normal, 1: do-not-track
),
'user' => shape(
  'buyeruid' => string, // Audience Network Identity Token 
),
'ext' => shape(
  'platformid' => string, // Mediation partner Platform ID (FB App ID)
),
'at' => int, // auction type: 1: First Price, 2: Second Price
'tmax' => int, // auction timeout, ms
'test' => ?int, // 0: normal, 1: test mode (we bid $99.99, but don't pay out)  (optional)
);

Supported Ad Formats

We currently support four types of ads that can be requested through OpenRTB: banner, native (native or native banner) and video (rewarded or instream video), and interstitial. Note: the banner, native and video objects are mutually exclusive, but one of them is required.

Here is a list of supported ad formats in bid request:

Ad Format Parameters in Bid Request

Native

{'id': ${AUCTION_ID}, 'native': { 'h': -1, 'w': -1 }, 'tagid': ${PLACEMENT_ID}}

Native Banner

{'id': ${AUCTION_ID}, 'native': { 'h': -1, 'w': -1 }, 'tagid': ${PLACEMENT_ID}}

Interstitial

{'id': ${AUCTION_ID}, 'banner': { 'h': 0, 'w': 0 }, 'tagid': ${PLACEMENT_ID}, 'instl': 1}

Rewarded Video

{'id': ${AUCTION_ID}, 'video': { 'h': 0, 'w': 0, 'ext': { 'videotype': 'rewarded' } }, 'tagid': ${PLACEMENT_ID}}

Banner - Height: 50

{'id': ${AUCTION_ID}, 'banner': { 'h': 50, 'w': -1 }, 'tagid': ${PLACEMENT_ID}}

Banner - Height: 250

{'id': ${AUCTION_ID}, 'banner': { 'h': 250, 'w': -1 }, 'tagid': ${PLACEMENT_ID}}

Instream Video

{'id': ${AUCTION_ID}, 'video': { 'h': 0, 'w': 0, 'linearity': 1 }, 'tagid': ${PLACEMENT_ID}}

ORTB Response

A bid response is valid for 30 minutes. You can request the ad at any time within 30 minutes from receiving the bid response. Any impressions based on a bid more than 30 minutes won't be paid.

Note: once you request an ad with bid response, the ad can be cached on the client but must be shown within 60 minutes of when they are loaded. Any impressions based on an ad that is cached more than 60 minutes won't be paid..

'id' => string // platform's request identifier
'seatbid' => vec<
  shape(
    'bid' => vec<
      shape(
        'id' => string, // Our identifier for this bid
        'impid' => string, // platform's identifier for this slot auction
        'price' => float, // Our bid price, in USD cents, CPM basis
        'adm' => string, // Our creative - see Rendering The Ad
        'nurl' => string, // URL to get if we win the impression
        'lurl' => string, // URL to get if we lose the impression
        'burl' => string, // URL to get if the impression gets logged
      )
    >,
  ),
>,
'bidid' => string, // Our identifier for this response
'cur' => string, // bid currency: USD

Win/Loss/Billable/Timeout Notifications

We require win, loss, billable and timeout notifications with the appropriate loss codes as defined in ORTB. ORTB nurl, lurl and burl are provided in the bid response. Please check previous section for bid response example. In case of bid timeout, we provide you with an alternative reporting route.

Win Notification

The win nurl will be provided in the bid response. You need populate Clearing Price in nurl:

"https://www.facebook.com/audiencenetwork/nurl/?partner=${PARTNER_FBID}&app=${APP_FBID}&placement=${PLACEMENT_FBID}&auction=${AUCTION_ID}&impression=${IMPRESSION_ID}&request=${BID_REQUEST_ID}&bid=${BID_ID}&ortb_loss_code=0&clearing_price=${AUCTION_PRICE}"
  • ${AUCTION_PRICE}: This should be replaced with the Clearing Price for the auction in the same unit as our bid (i.e. USD on CPM basis).

Loss Notification

Our loss lurl contains 2 flags you need populate:

"https://www.facebook.com/audiencenetwork/nurl/?partner=${PARTNER_FBID}&app=${APP_FBID}&placement=${PLACEMENT_FBID}&auction=${AUCTION_ID}&impression=${IMPRESSION_ID}&request=${BID_REQUEST_ID}&bid=${BID_ID}&ortb_loss_code=${AUCTION_LOSS}&clearing_price=${AUCTION_PRICE}"
  • ${AUCTION_LOSS}: This should be replaced with ORTB Loss Code.
  • ${AUCTION_PRICE}: This should be replaced with the Clearing Price for the auction in the same unit as our bid (i.e. USD on CPM basis).

Below is a list of different Loss Codes and corresponding Loss Reasons.

Loss ReasonDescriptionORTB v2.5 Loss Code

Invalid bid response

Bid is invalid (but on-time, not a no-bid, and valid enough that you can extract the nurl)

3

Bid timeout *

Bid response received, but too late for auction cutoff

2

No bid

No-bids are indicated as HTTP 204 (i.e. no nurl to call), but you may interpret our response as a no-bid (likely an integration issue). You may also request bids for several impressions, and we bid on some but not all.

9

Not highest RTB bidder

Another bidder beat us, including synthetic bids (e.g. non-RTB exchanges), if they are entered into the same auction.

102

Inventory didn't materialise

Our bid won the auction, but the impression didn't materialize (e.g. page wasn't long enough to include this slot, or the user exited the app before the cached ad was used.) Not all partners can provide this (it's a non-event), so we will infer it if not provided.

4902

Sent to ad server

Send this if the last touchpoint you have with the decision process is sending our high bid to the ad server. The impression may still be lost through missing line items, the ad server overruling the auction, or the inventory not materializing.

4900

RTB winner not picked by ad server

We won the RTB auction, but the ad server overruled the auction (e.g. direct).

4903

Win

We won the full decision tree, and tag was placed on page (web) or ad object was cached (app). Viewable impression may still not result.

0

Billable Notification

We require billable notification in case of impression callback triggered in Audience Network SDK. You need populate Clearing Price in burl:

"https://www.facebook.com/audiencenetwork/burl/?partner=${PARTNER_FBID}&app=${APP_FBID}&placement=${PLACEMENT_FBID}&auction=${AUCTION_ID}&impression=${IMPRESSION_ID}&request=${BID_REQUEST_ID}&bid=${BID_ID}&ortb_loss_code=0&clearing_price=${AUCTION_PRICE}"
  • ${AUCTION_PRICE}: This should be replaced with the Clearing Price for the auction in the same unit as our bid (i.e. USD on CPM basis).

Timeout Notification

For the case of bid timeout, we provide you with an alternative reporting route. It is the generic nurl which might be called upon without the need to wait for the bid to arrive. The format is as follows:

"https://www.facebook.com/audiencenetwork/nurl/?partner=${PARTNER_FBID}&app=${APP_FBID}&auction=${AUCTION_ID}&ortb_loss_code=2"

Note: ${PARTNER_FBID}, ${APP_FBID} and ${AUCTION_ID} should be populated with appropriate values. The table below provides explanation about those values.

ParamTypeDescription

PARTNER_FBID

Int

Ad auction server id issued by Facebook. Use your app id here if you don't have a dedicated ad auction partner.

APP_FBID

Int

Facebook-issued Id of the application/business which initiated an auction.

AUCTION_ID

String

Client-generated id of the auction you used for issuing a bid request.

Payouts, Auctions, Viewability and Latency

Prices and Payouts

Prices are quoted in USD on a CPM basis (e.g. 4.25 means we'll pay $4.25/1000 impressions if we win). The same unit must be used for the clearing price in nurl, lurl and burl. Payouts are made directly to the publisher.

Auction Mechanics

We always bid on a first-price basis, meaning we pay the amount we bid and we bid assuming we'll pay the full amount. This means we are at a disadvantage in a second-price auction, where other bidders can bid assuming they'll pay less than the amount bid.

Viewability

For app impressions, we only pay out if the impression is viewed, regardless of whether we were the highest bidder.

Latency

  • For minimum latency, request a single bid per API call (i.e., if you are auctioning five slots then call the API five times, each for a single bid).
  • We don't provide region-specific endpoints. The Facebook infrastructure will route the bid request to the nearest data center.
  • Use HTTP/2 persistent connections.
  • Use the HTTP (not HTTPS) endpoint.
  • Populate the ORTB tmax field in the bid request with the auction timeout, and we will choose a bidding strategy balancing latency and performance. (Please check bid request example above for more info about tmax)
  • To meet latency targets, we may defer some processing to render time (i.e. a faster bid might mean a slower-rendering ad, and a slower bid results in an ad which renders faster).
  • We are actively working on improving latency. We currently recommend a 500ms timeout for server-to-server bidding.

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