Bidding with In-House Mediation

Server-to-Server Bidding Integration

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.

Facebook Audience Network has an Open Real-Time Bidding (ORTB) bidder that supports both direct client integrations and server-to-server integrations. This guide describes how to integrate bidding from an auction server.

In server-to-server integration, an auction server calls the Facebook Audience Network bidding endpoint and all other demand sources to get bid responses. The auction server then 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 third-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.

Prerequisites

Before you begin, read Audience Network Bidding Overview and Bidding Integration Best Practices.

Android

iOS

Preparation

The following steps are required to prepare for in-house server-to-server bidding:

Register your Business

Each publisher needs to create an Audience Network Business ID, which we will add to the allow list for bidding. Under this Business ID you can create multiple properties that utilize the bidding endpoint.

  • Go to the Facebook Audience Network documentation and click the Start Now button to create a new Business ID, or use your existing Business ID.
  • You can create properties under the same Business ID but you will have to register them; see the Monetization Manager for more details.
  • Let us know the Business ID (this is your publisher ID).
  • You can manage user access to your business/app.

Create a Facebook Security App

All server-side in-house publishers are required to create a Facebook security app at https://developers.facebook.com. Once the app is created, you will need to get the App ID and App Secret for the security app. The App Secret will be used in every request to create an authentication token to validate the originator of the request.

Ensure you are using the correct Hash (specified below) and if the hash starts with a 0, it is not getting lost.

To create a security app and link it to your business:

  1. Log in to https://developers.facebook.com.
  2. In the My Apps menu, click Create App.
  3. Select Business., and then click Next.
  4. Provide a name for the app with the prefix "AN_SECURITY_APP" and then click Create App ID.
  5. In the left menu, select Settings → Basic.
  6. In the App Secret field, click Show. Write down your App ID and App Secret.
  7. Go to https://business.facebook.com and select your business.
  8. In the left menu, click Business Settings.
  9. In the left menu of the Business Settings page, select Accounts → Apps.
  10. In the Apps pane, click Add → Add an App.
  11. Enter the App ID of your security app and then click Add App. Your AN_SECURITY_APP should now be under your business.

The request-specific authentication_id is generated with the HMAC-SHA256 algorithm. This algorithm uses the following inputs:

  • Request ID as the message
  • App Secret as the key
      authentication_id = HMAC_SHA256(request_id, app_secret)

The generated ID is then added to the top-level OpenRTB bid request extension in the authentication_id field. For example, if the request ID is "9r90wurjqw" and the app secret is "12345asdfg" the authentication_id is generated like this:

      authentication_id = HMAC_SHA256(9r90wurjqw, 12345asdfg) = 39bbe40bc68899a9356085ca8c81

This token will be included in every request along with the App ID of the security app.

      {
      "id": "9r90wurjqw",
      ...
      "ext": {
      "authentication_id": "39bbe40bc68899a9356085ca8c81d3021cfa124f2a2b3c68c88f95fb4cde40a4",
      "security_app_id": "AN_SECURITY_APP_MY_SECURITY_APP_ID" 
      ...
      }
      }

Pass your Identity Token to the Bidder

Our bidder expects an identity token in the user.buyeruid field of the ORTB request. This token is generated in different ways for different platforms.

Android

On a background thread, call com.facebook.ads.BidderTokenProvider.getBidderToken() from the Android Audience Network SDK. The token must be requested for every bid request. Also pass the IDFA in the device.ifa field to AdvertisingIdClient.getAdvertisingIdInfo(context).getId().

iOS

Call [FBAdSettings bidderToken] from the iOS Audience Network SDK. The token must be requested for every bid request. Also pass the IDFA in the device.ifa field with [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString].

Next Steps