OpenRTB Integration

  • This guide provides details on integrating with Google's OpenRTB implementation, supporting JSON and Protobuf formats with a focus on Protobuf.

  • Impression tracking should be done using BidResponse.seatbid[].bid[].ext.impression_tracking_url or BidResponse.seatbid[].bid[].burl instead of pixels.

  • The BidRequest.user.eids.uids field includes a stype extension for publisher-provided and app/web first-party IDs.

  • Various OpenRTB objects like Imp, Banner, Video, Native, Pmp, Site, App, Publisher, Content, Device, and User are detailed with their attributes and Google-specific extensions.

  • The BidResponse object and its subordinate objects like Seatbid and Bid are described, including extensions for impression tracking URLs and DSA transparency declarations.

This guide provides information that can help you integrate with Google's OpenRTB implementation. OpenRTB's supported formats are JSON, as well as Protocol Buffers, hereafter referred to as Protobuf. The protocol reference in this guide will focus on the Protobuf format, but even if you use JSON, it is a reference for determining which OpenRTB fields are supported in Google's implementation, and learning about Google's OpenRTB extensions.

If your integration uses the JSON format, Google strongly recommends that you review Understand Protobuf versus JSON serialization to understand differences you should expect in comparison to the Protobuf reference included in this guide. You can also consult IAB's OpenRTB spec.

If your integration uses the Protobuf format, you will need to generate a library used to parse and serialize messages sent between your bidding endpoint and Google's exchange, which is based on the contents of openrtb-proto.txt and extensions found in openrtb-adx-proto.txt.

Understand how objects and fields are populated

Google doesn't populate the bid request with empty fields, and also doesn't populate fields set to empty string values. An unpopulated field in the bid request indicates that the field isn't available or relevant for the impression.

For example, Google doesn't populate the BidRequest.imp.video field for impressions that don't support the VAST video creative format. If you receive a bid request where the BidRequest.imp.video field isn't populated, your bidding endpoint must not place a bid containing a VAST video creative.

Select an ad category taxonomy

Ad categories let you identify the creatives to include in your bid for a given impression. Google uses IAB Content Taxonomy 1.0 as the default ad category taxonomy for Authorized Buyers and Open Bidding accounts, which affects how related OpenRTB and Real-time Bidding API fields are populated. IAB Content Taxonomy 1.0 is for integrations that prioritize compatibility with other exchanges, or minimize Google-specific logic. However, IAB Content Taxonomy 1.0 doesn't perfectly align with Google Ad Category Taxonomy, which publishers use to describe blocked categories.

Using IAB Content Taxonomy 1.0 can result in increased bid filtering when IAB Content Taxonomy 1.0 has no category equivalent to a Google Ad Category Taxonomy category. For example, if you use IAB Content Taxonomy 1.0, and you receive a bid request from a publisher that blocks gambling, the BidRequest.bcat field doesn't communicate that the publisher blocked gambling because IAB Content Taxonomy 1.0 doesn't have an equivalent category. Similarly, the detectedCategories field in the Real-time Bidding API's creatives resource doesn't communicate when a creative is detected to involve gambling if you use IAB Content Taxonomy 1.0. These limitations increase the difficulty of complying with the publisher's blocked categories for affected bid requests.

If your integration focuses on reduced bid filtering from bids using creatives with blocked categories, Google recommends that you use Google Ad Category Taxonomy, which includes all of the IDs found in the following data files:

You can enable Google Ad Category Taxonomy by contacting your account manager.

Understand Protobuf versus JSON serialization

Google's OpenRTB implementation supports JSON and Protobuf formats. The bid request and response references in this guide refer to the Protobuf format. We recommend using the Protobuf format for the reduced CPU costs of serialization and deserialization, and reduced network costs due to smaller wire size.

The following table compares the JSON and Protobuf formats:

Topic JSON behavior Protobuf behavior
Boolean values

Represented as integers where 1 is true and 0 is false.

Represented with boolean values true and false.
Enumerations

Represented as integers based on Enumerations defined in the OpenRTB spec, or Google enum types found in