OpenRTB 2.x Specification

repository·main·Indexed 41 days ago

https://github.com/interactiveadvertisingbureau/openrtb2.x

A standard for programmatic advertising exchange protocols maintained by the IAB Tech Lab. It defines the interaction model between Exchanges and Bidders, including the BidRequest object model, transport requirements via HTTP, and support for JSON and Protocol Buffers encoding. The specification covers various ad formats including Banner, Video, Audio, and Native, with version 2.6 introducing Ad Pods for CTV and structured User-Agent objects.

Tokens
48.9K
Snippets
59
Records
117
Agent score
52%

What's inside OpenRTB

  1. Understand Protocol Buffers encoding differences in OpenRTB

    main

    The openrtb.proto file is the standard binary encoding for OpenRTB, but it differs from the JSON representation in two specific ways:

    1. Booleans: Fields that are expressed as integers in JSON are expressed as actual boolean types in Protocol Buffers.
    2. Enumerations: Enumerations are expressed as integers in both JSON and Protocol Buffers (a legacy of proto2 syntax). For the standard enumerated values, refer to the adcom-proto repository.
  2. Choose an ad serving method

    main

    Bidders can choose how to deliver ad markup to the exchange. There are two primary methods defined in the OpenRTB specification. Bidders and exchanges should agree on the method during integration.

    1. Markup Served in the Bid

    Markup is returned directly in the bid response using the bid.adm attribute.

    • Advantage: Reduces the risk of 'forfeiture' (where a bidder wins but fails to serve the markup due to an HTTP error during the win notice call). It also allows the exchange to potentially process markup and the win notice concurrently.
    • Precedence: If both bid.adm and the win notice return data, the contents of bid.adm take precedence.

    2. Markup Served on the Win Notice

    Markup is returned via the response body of the win notice call (invoked by the bid.nurl attribute).

    • Requirement: The response body must contain only the ad markup and no other structured data. In this method, the bid.adm attribute must be omitted.
    • Advantage: Reduces bandwidth costs because markup is only transferred after a win is confirmed.
  3. Configure BidRequest seat restrictions

    main

    You can restrict which buyers are allowed to bid or which are blocked using seat lists.

    • wseat (string array): An allowed list of buyer seats (advertisers, agencies) permitted to bid.
    • bseat (string array): A block list of buyer seats restricted from bidding.

    Constraint: You should use at most one of wseat or bseat in a single request. Omitting both implies no seat restrictions.

  4. Understand EID roles: inserter, source, and matcher

    main

    When working with the Extended Identifier (eid) array, understand the three primary roles involved in ID management:

    • inserter: The party that puts the ID into the bid request (typically a Publisher or an SSP). In header bidding, the inserter is the Publisher.
    • source: The party that defined or created the ID. For universal/alt-IDs, this is the entity that created the ID. For cookie IDs, this is the domain the cookie belongs to.
    • matcher: The party that created the match included in the ID array (e.g., a device graph vendor or the publisher).
  5. Avoid anti-patterns in Deal ID bidding

    main

    To ensure successful Deal ID implementation, avoid these common anti-patterns:

    • Subjecting Deal ID Bids to internal price auctions: Do not sort Deal ID bids by price and truncate them too aggressively. The goal is often deal fulfillment, not just the highest price.
    • Associating Deal ID to the wrong Object: Treat a Deal ID as a "targeting token" for orders, line-items, or campaigns. Do not associate it with a Seat/Buyer (which applies it to too many campaigns) or an Advertiser (which limits them to one deal).
    • Improper handling of pmp.private_auction: If this flag is true, do not expose open market bids. If false, all bidders are welcome.
    • Improper handling of Seat IDs: Do not use Seat IDs as a filter for open market impressions; this violates the "all bidders are welcome" intent.
    • Silently applying margin discounts: Do not apply automatic or silent discounts to Deal ID bid prices. This can cause the direct communication between buyer and seller to fail.
  6. Use the DOOH object for Digital Out-Of-Home

    main

    The DOOH object should be included in a bid request if the ad supported content is a Digital Out-Of-Home screen.

    Important Constraints:

    • A bid request containing a DOOH object must not contain a site or app object.
    • At a minimum, it is useful to provide id and/or venuetypeid, though these are not strictly required.
  7. Use substitution macros in URLs and markup

    main

    Exchanges support substitution macros in win notice URLs, billing notice URLs, and ad markup. The exchange searches for these macros and replaces them with real-time auction data.

    Key Behaviors:

    • Simple Substitution: The exchange replaces the macro wherever it is found, regardless of syntax correctness.
    • Missing Parameters: If a macro refers to an optional parameter that was not provided, the macro is replaced with an empty string.
    • Encoding: To protect data (e.g., when passing price through a browser via a tracking pixel), you can append a suffix :X to a macro, where X is an agreed-upon algorithm code (e.g., ${AUCTION_PRICE:B64} for Base64).
    • Best Practice: For testing or quality audits where values like clearing price are unknown, use the string "AUDIT" as the macro value.
  8. Use genres and gtax attributes for CTV content targeting

    main

    To improve programmatic targeting, reporting, and forecasting for CTV/OTT content, OpenRTB uses the genres and gtax attributes within Object: Content. This replaces the legacy free-text genre attribute with enumerated values from a standardized taxonomy.

    Key Attributes

    • genres: An integer array containing accepted genre IDs from the taxonomy.
    • gtax: A string indicating the specific taxonomy version being used (e.g., pointing to IAB Tech Lab Content Taxonomy 3.1).

    Implementation Best Practices

    • For Publishers:
      • Use genres only for the holistic genre of the content.
      • Use cat and cattax for finer details of content parts, not for the primary genre.
      • Use keywords or kwarray for additional free-text metadata.
      • Pass a minimum viable number of genres, placing the most accurate enumeration as the first integer in the genres array.
    • For SSPs:
      • Upgrade from the legacy genre attribute to passing genres and gtax through to DSPs.
      • If using a third-party vendor for classification, pass the vendor's 500+ designation in the gtax attribute.
    • For Buyers/DSPs:
      • Implement targeting using allowlists and blocklists of genre IDs to achieve scale (e.g., grouping multiple genres into an 'entertainment' package).
      • Ensure support for the 500+ designation in gtax to handle vendor-specific taxonomies.
    {
      "content": {
        "genres": [123, 456],
        "gtax": "IAB Content Taxonomy 3.1",
        "keywords": ["example", "keyword"]
      }
    }
  9. Understand the ${AUCTION_MIN_TO_WIN} macro behavior

    main

    The ${AUCTION_MIN_TO_WIN} macro provides the price required to tie with the winning bid. Its behavior depends on whether your bid won or lost:

    • If your bid lost: It returns the minimum price required to tie with the winning bid.
    • If your bid won: It returns the minimum price required to tie with the next-closest bid (or the floor if there was only one bid).
    • If the value is unavailable: It returns an empty string. This happens if the bid wasn't allowed into the auction, price wasn't the deciding factor, or due to privacy controls.
    • Testing: As with other macros, you can use "AUDIT" for testing purposes.
  10. Understand Pod Bidding for Video and Audio

    main

    Starting in OpenRTB 2.6, 'pod bidding' allows for ad breaks (pods) in video or audio streams, similar to TV or radio. An ad pod contains one or more in-stream creative assets played contiguously. Pod bidding uses multiple ad requests within a single bid request to signal relationships between impressions, including sequence, total pod length, and maximum number of ads.

    Pod Types

    • Structured Pod: The seller provides a static, pre-defined structure. The number of ad slots, their specific position in the pod, and their durations are fixed.
    • Dynamic Pod: The seller provides a pod where the number of ads and individual durations are indeterminate, but the total pod duration and maximum number of ads are constrained. This gives buyers flexibility to optimize selection.
    • Hybrid Pod: A combination of both. It contains some structured ad slots (fixed duration/position) and some dynamic components (constrained by total duration and max ads).

    Key Terminology

    • Ad Slot: An individual space for an ad impression within a pod.