Prebid Server faces reference

The companion to Header bidding through a Prebid Server, which has the steps, which server to use, the slot ids, what the other operator has to do and the fix-it checklist; this page holds what each of the three Prebid Server faces hands over. The keys and timings are on the hub, under Keys and timings at a glance.

Our Prebid Server

The publisher stands nothing up and stores nothing: they point their app or page at the Prebid Server this face names, name their account, and ask for slots by id. The slot definitions live here and are kept current here, so a change to a slot reaches their traffic without them touching anything. It is the quickest route for an app, because nothing has to be stood up.

Note: out of the box the server on this face is pbs.eashb.com, with its cache at cache.eashb.com. A network may use them for small volumes; for more, we recommend a dedicated Prebid Server instance, which this face can name instead — see Which Prebid Server to use.

Set Where the auction runs to Our Prebid Server. The face hands over, in this order:

• Where to send the auction — the auction endpoint of the configured Prebid Server, which on a network using pbs.eashb.com is https://pbs.eashb.com/openrtb2/auction. Give the SDK the full path; it does not add it. Captioned Their account on it beneath it is the account id, which is your network id — the same value that opens every slot id.

• In an app — the two SDK calls, ready to paste, with the address and account already in:

  // iOS
  Prebid.shared.prebidServerAccountId = "n1234"
  try! Prebid.shared.setCustomPrebidServer(url: "https://pbs.eashb.com/openrtb2/auction")
  
  // Android
  PrebidMobile.setPrebidServerAccountId("n1234")
  PrebidMobile.setPrebidServerHost(Host.createCustomHost("https://pbs.eashb.com/openrtb2/auction"))

  Under it, the link to the example apps.

• On a page — for a web page that wants the same server instead of an in-browser auction: a pbjs.setConfig({ s2sConfig: … }) block naming the account, bidders: ['epom_as'], the endpoint and the cookie-sync endpoint. The bidder named there is the one our server carries, so the page declares no alias.

• Our cache — pbjs.setConfig({ cache: { url: 'https://cache.eashb.com/cache' } }) with the default settings, only for a page that calls video bidders itself. An app never needs this: the Prebid Mobile rendering API uses the shared cache automatically.

• 1. The slot ids — the listing described under Slot ids. Each id goes into the app as the configId of one ad unit.

The option appears on the switch only while a Prebid Server is set for the network. pbs.eashb.com is set out of the box, so the option is there unless your network has had it removed.

Their Prebid Server, our setup

Pick this face for a publisher or buyer whose own Prebid Server will ask for these slots. It is titled What goes in a Prebid Server and walks three numbered steps — 1. The slot ids, 2. How their server finds those slots, 3. Check it answers. Step 2 offers two ways, and says to pick one rather than both.

The address. Every serving domain answers stored requests at https://{serving-domain}/hb/stored-requests, and the face prints it inside the block their server configuration takes:

stored_requests:
  http:
    endpoint: https://ads.example.com/hb/stored-requests
  in_memory_cache:
    type: lru
    ttl_seconds: 300
    request_cache_size_bytes: 10000000
    imp_cache_size_bytes: 10000000

Their server then reads the slots from us, and nothing they hold can go stale: a slot edited here reaches the address within a minute, and their server within its own cache window on top — five minutes with the block above.

The address reads both query shapes a Prebid Server fetcher can send:

https://ads.example.com/hb/stored-requests?imp-ids=["n1234-26","n1234-27"]
https://ads.example.com/hb/stored-requests?imp-id=n1234-26&imp-id=n1234-27

Either answers the same document, and an id we do not hold is simply absent from imps rather than present as null — that is how Prebid Server tells not found from a broken answer:

{ "requests": {}, "imps": { "n1234-26": { … }, "n1234-27": { … } } }

Asked for nothing at all, the address does not describe the network to whoever finds it: it answers 401 and asks for an HTTP Basic password — any username, the listing secret as the password — and only then lists which ids exist, with no placement keys and no hosts. Ask Epom support or your account manager for the secret; with no secret set, listing is off altogether while single-id lookups keep working. It is for your own tooling, not for the publisher: Prebid Server never calls without ids. Asked without the secret, the address answers 401 with the body {"requests":{},"imps":{}} — read the status, not the body.

The documents. For a server that keeps its own copy, step 2 also prints one document per slot, headed container name · id, to file under that id in their backend:

{
  "id": "n1234-27",
  "banner": { "format": [ { "w": 728, "h": 90 } ] },
  "ext": { "prebid": { "bidder": {
    "epom_as": {
      "networkId": "n1234",
      "host": "ads.example.com",
      "placementKey": "a4f21c9e7b",
      "channel": "sports-uk",
      "customParams": { "section": "sport" }
    }
  } } }
}

It states what only we know: which network and serving host answer, which placement, and the channel and custom parameters set on that placement. banner.format appears only on a banner slot with ad units picked; a Video or Native slot, and a Non-standard slot with no ad units, carry no media block at all. That is deliberate: media type, sizes, instl and rwdd are the caller’s to state on its own impression, and Prebid Server lets the incoming request win on conflict, so a document that named them would only overrule an SDK that knows the screen it is filling. Our bidder is always keyed epom_as in these documents; the choice of name exists only on the adapter face.

3. Check it answers. The face ends with one URL that asks the address for every id on the tag at once, in the repeated imp-id= form. Open it in a browser and you should see one entry per slot. It uses that form on purpose: a browser sends the [ of the array form raw, and the server refuses the request before we see it.

Their Prebid Server, our adapter

The last face is for a server that already stores these slots and is only taking us on as one more bidder; nothing else about their slot changes. Per slot it prints our entry alone, headed with the container name, to merge into ext.prebid.bidder of the document they already hold:

{
  "epom_as": {
    "networkId": "n1234",
    "host": "ads.example.com",
    "placementKey": "a4f21c9e7b"
  }
}

It is read back out of the same document the previous face prints, so the two can never disagree — and it carries the same channel and custom parameters, with the same copy-not-link caveat.

Under As epom_{network} the face also prints the declaration that makes the name resolve on their server:

{ "ext": { "prebid": { "aliases": { "epom_n1234": "epom_as" } } } }

Related

• Header bidding through a Prebid Server
• Header bidding
• Header bidding tag settings and slots
• Header bidding in an app with Prebid Mobile
• Header bidding: what a publisher installs