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

Nell'integrazione server-to-server, un server aste chiama l'endpoint di offerta di Audience Network di Facebook e tutte le altre fonti di domanda per ottenere risposte all'offerta. Quindi il server aste avvia l'asta e sceglie l'offerta vincente. Questo server aste potrebbe essere un server interno che applica la logica dell'asta che hai creato o potrebbe essere un server di terzi integrato con l'App Bidding di Audience Network. Ciò ti consente di utilizzare le risorse del server e la rete disponibile per chiamare gli endpoint di offerta delle fonti di domanda. Ti consente anche di apportare modifiche alle integrazioni di questi endpoint senza richiedere necessariamente aggiornamenti client.

External Ad Server Integration

L'integrazione del server per le inserzioni esterno ti consente di collegare l'odierno mondo della mediazione con distribuzione a waterfall con la funzione di offerta nelle app. Ciò funziona realizzando un'integrazione server-to-server con le fonti di domanda che supportano le offerte in app, e successivamente passando il vincitore dell'asta sulla piattaforma di mediazione con distribuzione a waterfall che esegue la distribuzione a waterfall e sceglie la fonte di domanda vincente complessiva. Questa integrazione è intesa come ponte provvisorio tra il mondo della mediazione con distribuzione a waterfall e la funzione di offerta nelle app. Con questo tipo di integrazione non è necessario scrivere la propria logica dell'asta.

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