Server-to-Server Bidding

In the Server to Server section:

• Integration
• Auction Server Setup
• Android Client Setup
• iOS Client Setup
• Testing
• Troubleshooting

On this page:

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
• Integration Architectures
• ORTB Request/Response and Supported Ad Formats
• Win/Loss/Billable/Timeout Notifications
• Payouts, Auctions, Viewability and Latency

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. The Audience Network SDK is required in app bidding to perform the following actions:

• Obtain the buyeruid (named bidderToken in the Audience Network SDK). This token is a required field in the bid request, and is unique both per user and per app; the token is not valid for another user or app.
• Load the bid response, and show an ad if the bidder wins the auction.
• Record impressions and clicks.

Key Steps in the Bidding Flow

1. Obtain the bidder token. Audience Network needs this opaque string to respond to a bid request.
2. Send the bid request and get the bid response. This is the main interaction with the bidding endpoint. In this step, you send a request for an ORTB bid and then receive either a valid bid response or an error.
3. Run the auction. Run an auction and select a winner from among the bid responses. Most auctions compare real-time bids with estimated CPMs from other demand sources (such as historical average CPMs); this is done because some demand sources don't support real-time bids. Auctions can be run by one of the following:
   • An in-house server that runs your own custom auction logic
   • A third-party auction server
   • The client on the user's device
4. Retrieve the ad with the bid response. If Audience Network wins the auction, load the ad by passing the adm field from the bid response to the Audience Network SDK on the user's device. Note that the adm field does not contain the actual ad; it contains information that allows the SDK to retrieve the ad from the 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:

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: Please see full sample request on Auction Server Setup Guide

'id' => string, // platform's auction identifier,
'imp' => vec< // slots to bid on
shape(
'id' => string, // platform's identifier for this slot auction
// only for banner impression opportunities
'banner' => shape(
'w' => int, // width
'h' => int, // height
),
// only for native impression opportunities
'native' => shape(
'w' => int, // width 
'h' => int, // height 
),
// only for video impression opportunities
'video' => shape(
'w' => int, // width
'h' => int, // height
'linearity' => int, // 1 = instream, optional
'ext' => shape(
'videotype' => string, // 'rewarded' for Rewarded Video impression opportunities, optional
),
),
'tagid' => string, // Placement ID
'instl' => int, // interstitial flag, 1 = On, 0 = Off, optional
)
>,
// app details (in-app bidding only)
'app' => shape( 
'publisher' => shape(
'id' => string, // publisher app ID
),
),
'device' => shape(
'ua' => string, // device user-agent
'ifa' => string, // ID sanctioned for advertiser use
// Do not send ip or ipv6 if you are requesting bids from the client device.
// For server-side bid requests set ip or ipv6.
'ip' => string, // device IPv4
'ipv6' => string, // device IPv6
'dnt' => int, // "do not track", 1 = On, 0 = Off, optional
'lmt' => int, // "limit ad tracking", 1 = On, 0 = Off
),
'regs' => shape( // regulations object
'coppa' => int, // US FTC regulations for Children's Online Privacy Protection Act, 1 = On, 0 = Off, optional
),
'user' => shape(
'buyeruid' => string, // Audience Network Identity Token, mandatory
),
'ext' => shape(
'platformid' => string, // Mediation partner Platform ID or publisher FB app ID, mandatory
'authentication_id' => string // Authentication token to validate the originator of the request                     
),
'at' => int, // auction type: 1 = First Price, 2 = Second Price
'tmax' => int, // auction timeout in milliseconds
'test' => int, // 0 = normal, 1 = test-mode (we bid $99.99, but don't pay out), optional

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

1  
'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 on CPM basis, in USD
                '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
            )
        >,
    ),
>,
'bidid' => string, // Our identifier for this response
'cur' => string, // bid currency: USD

Win/Loss/Billable/Timeout Notifications

"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}&phase=${PHASE}"

"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}&phase=${PHASE}"

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

"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}&phase=${PHASE}"

"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}&phase=${PHASE}"

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 and lurl. 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.
• 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 800ms timeout for server-to-server bidding.

See Also

• Integration
• Auction Server Setup
• Android Client Setup
• iOS Client Setup
• Testing
• Troubleshooting