OpenRTB for ad ops and product managers

What ad ops owns

Engineers build the integration, but most of the values inside it come from settings that ad ops and product teams control.

• Configuration that becomes fields. Floors, deals, blocked advertisers and categories, ad unit sizes and formats, and the auction type.
• Inventory declarations. ads.txt, app-ads.txt, and sellers.json entries, which buyers compare with what each request says.
• Partner setup. Which OpenRTB version each partner speaks, which extra fields it needs, and when test traffic is switched to live.
• Reconciliation. Which notice each side counts as an impression, and in which time zone.
• Triage. Reading a captured request, a response, or a reason code to decide whether a problem is configuration, demand, or code.

Reading a bid request in two minutes

A bid request is one JSON object that a seller sends to buyers for each ad opportunity. It always has the same parts: the auction rules at the top, the impressions for sale in imp, where the ad runs (site, app, or dooh), the device and user, the regulatory signals in regs, and the sales path in source. Here is a connected TV request for a live sports stream:

{
  "id": "ctv-8f21c4a0",
  "at": 1,
  "tmax": 300,
  "cur": ["USD"],
  "badv": ["rivalbet.example"],
  "imp": [
    {
      "id": "1",
      "bidfloor": 18.00,
      "bidfloorcur": "USD",
      "video": {
        "mimes": ["video/mp4"],
        "plcmt": 1,
        "startdelay": -1,
        "minduration": 15,
        "maxduration": 30,
        "protocols": [7, 8],
        "w": 1920,
        "h": 1080
      },
      "pmp": {
        "deals": [{ "id": "pg-sports-q4", "bidfloor": 32.00, "at": 3, "wseat": ["agency-311"] }]
      }
    }
  ],
  "app": {
    "bundle": "com.example.sportsnow",
    "storeurl": "https://play.google.com/store/apps/details?id=com.example.sportsnow",
    "publisher": { "id": "pub-1180" },
    "content": { "genre": "Sports", "livestream": 1, "language": "en" }
  },
  "device": {
    "devicetype": 3,
    "ip": "198.51.100.77",
    "os": "Android",
    "ifa": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "lmt": 0
  },
  "regs": { "coppa": 0 },
  "source": {
    "schain": {
      "ver": "1.0",
      "complete": 1,
      "nodes": [{ "asi": "ssp.example", "sid": "pub-1180", "hp": 1 }]
    }
  }
}

A field that is missing is not the same as zero. Many fields have a default, so leaving out at means second price, and leaving out bidfloorcur means US dollars. The spec reading guide explains defaults in more depth.

The fields that move revenue

The floors and deals rows are covered in depth by the floors reference and the deals guide.

Signals buyers filter on before they price

A buyer runs gates before it thinks about price. When a gate fails, a well-behaved buyer answers with a no-bid reason code in BidResponse.nbr, which makes the gate visible to you.

Privacy signals act as a gate too. If regs.gdpr is 1 and the consent string is missing, or a regs.gpp string signals an opt-out, many buyers bid without personal data or not at all. All codes are in no-bid reason codes.

Reading what comes back

Three kinds of feedback reach ad ops. No-bid reasons come from buyers, as above. Loss reasons come from the exchange to each buyer that lost, and buy-side teams use them to tell pricing problems (100 Below Auction Floor, 102 Lost to Higher Bid) from creative problems (the 200 range). Notices count the money: the win notice nurl fires when a bid wins, and the billing notice burl fires when the impression becomes billable.

Most discrepancies between a buyer's report and a seller's report trace back to those two notices. If one side counts wins and the other counts billable impressions, every won ad that never rendered becomes a gap. Agree with each partner which notice defines an impression, and in which time zone the reporting day ends. The loss reason codes guide covers the buyer side of this feedback.

Symptoms and where to look first

For the full fill-rate funnel, see why is my fill rate low.

Questions to settle with every partner

• Which OpenRTB version and dated release do you send or expect?
• Which extension fields under ext do you require, and where are they documented?
• Will you return no-bid reason codes during testing?
• What event fires the billing notice, and do you send loss notices?
• Which currencies do you accept, and which currency are floors in?
• How are deal IDs and seat IDs formatted, and who creates them?
• Which time zone do your reports use?

The answers belong in the integration notes for that partner. Many exchanges publish their own requirements, and the exchange notes collect the documented ones.

Checking a payload yourself

Ask engineering or your partner for a captured request, taken after the seller has added everything it adds. A sample from documentation shows what was intended, not what was sent. Read it against the tables above, then run it through a validator to catch wrong types, unknown fields, and outdated paths. For live checks that cost nothing, a request with test set to 1 runs a full auction that neither side bills.

To see a complete CTV pod request, open the CTV video pod sample in the tester, then paste your captured request in its place.

Questions people ask