interactiveadvertisingbureau / openrtb

Open RTB is a protocol for real time bidding on digital media

OpenRTB 3.0

About OpenRTB

https://iabtechlab.com/openrtb

About OpenMedia

https://iabtechlab.com/openmedia

AdCOM: Advertising Common Object Model

https://github.com/InteractiveAdvertisingBureau/AdCOM

About This Repository

At all times, the master branch of this repository contains the most recent release of OpenRTB. See "OpenRTB v3.0 Final.md" in the master branch for the latest specification.

Branches exist for prior releases. Use these to review detailed changes from one release to another. A brief change log is found in the spec itself.

The develop branch contains work-in-progress for an upcoming release. It may change at any time.

Contact

For more information, or to get involved, please email [email protected].

About IAB Tech Lab

The IAB Technology Laboratory is a nonprofit research and development consortium charged with producing and helping companies implement global industry technical standards and solutions. The goal of the Tech Lab is to reduce friction associated with the digital advertising and marketing supply chain while contributing to the safe growth of an industry. The IAB Tech Lab spearheads the development of technical standards, creates and maintains a code library to assist in rapid, cost-effective implementation of IAB standards, and establishes a test platform for companies to evaluate the compatibility of their technology solutions with IAB standards, which for 18 years have been the foundation for interoperability and profitable growth in the digital advertising supply chain.

Learn more about IAB Tech Lab here: https://www.iabtechlab.com/

Contributors and Technical Governance

OpenRTB Working Group members provide contributions to this repository. Participants in the Programmatic Supply Working group must be members of IAB Tech Lab. Technical Governance and code commits for the project are provided by the IAB Tech Lab Programmatic Supply Chain Commit Group.

Learn more about how to submit changes in our working group: So, You'd Like to Propose a Change...

License

OpenRTB Specification the IAB Tech Lab is licensed under a Creative Commons Attribution 3.0 License. To view a copy of this license, visit creativecommons.org/licenses/by/3.0/ or write to Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA.

By submitting an idea, specification, software code, document, file, or other material (each, a “Submission”) to the OpenRTB repository, to any member of the Programmatic Supply Chain Working Group, or to the IAB Tech Lab in relation to OpenRTB 3.0 you agree to and hereby license such Submission to the IAB Tech Lab under the Creative Commons Attribution 3.0 License and agree that such Submission may be used and made available to the public under the terms of such license.  If you are a member of the IAB Tech Lab then the terms and conditions of the IPR Policy may also be applicable to your Submission, and if the IPR Policy is applicable to your Submission then the IPR Policy will control  in the event of a conflict between the Creative Commons Attribution 3.0 License and the IPR Policy.

Disclaimer

THE STANDARDS, THE SPECIFICATIONS, THE MEASUREMENT GUIDELINES, AND ANY OTHER MATERIALS OR SERVICES PROVIDED TO OR USED BY YOU HEREUNDER (THE “PRODUCTS AND SERVICES”) ARE PROVIDED “AS IS” AND “AS AVAILABLE,” AND IAB TECHNOLOGY LABORATORY, INC. (“TECH LAB”) MAKES NO WARRANTY WITH RESPECT TO THE SAME AND HEREBY DISCLAIMS ANY AND ALL EXPRESS, IMPLIED, OR STATUTORY WARRANTIES, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AVAILABILITY, ERROR-FREE OR UNINTERRUPTED OPERATION, AND ANY WARRANTIES ARISING FROM A COURSE OF DEALING, COURSE OF PERFORMANCE, OR USAGE OF TRADE. TO THE EXTENT THAT TECH LAB MAY NOT AS A MATTER OF APPLICABLE LAW DISCLAIM ANY IMPLIED WARRANTY, THE SCOPE AND DURATION OF SUCH WARRANTY WILL BE THE MINIMUM PERMITTED UNDER SUCH LAW. THE PRODUCTS AND SERVICES DO NOT CONSTITUTE BUSINESS OR LEGAL ADVICE. TECH LAB DOES NOT WARRANT THAT THE PRODUCTS AND SERVICES PROVIDED TO OR USED BY YOU HEREUNDER SHALL CAUSE YOU AND/OR YOUR PRODUCTS OR SERVICES TO BE IN COMPLIANCE WITH ANY APPLICABLE LAWS, REGULATIONS, OR SELF-REGULATORY FRAMEWORKS, AND YOU ARE SOLELY RESPONSIBLE FOR COMPLIANCE WITH THE SAME, INCLUDING, BUT NOT LIMITED TO, DATA PROTECTION LAWS, SUCH AS THE PERSONAL INFORMATION PROTECTION AND ELECTRONIC DOCUMENTS ACT (CANADA), THE DATA PROTECTION DIRECTIVE (EU), THE E-PRIVACY DIRECTIVE (EU), THE GENERAL DATA PROTECTION REGULATION (EU), AND THE E-PRIVACY REGULATION (EU) AS AND WHEN THEY BECOME EFFECTIVE.

openrtb's Issues

Add the Global Privacy Control signal to the OpenRTB extensions

The Global Privacy Control is a specification that allows users to--at the browser or browser extension level--specify their preference to opt out of their data collection and into the available privacy regime that might support such a request. According to the specification:

the use of the GPC signal by an individual will be intended to communicate the individual's intention to invoke the following rights, as applicable:

• Under the CCPA, the GPC signal will be intended to communicate a Do Not Sell request from a global privacy control, as per [CCPA-REGULATIONS] §999.315 for that browser or device, or, if known, the consumer.

Where the GPC signal conflicts with the existing privacy settings a consumer has with the business, the business shall respect the GPC signal but may notify the consumer of the conflict and give the consumer an opportunity to confirm the business-specific privacy setting or participation in the financial incentive program [CCPA-REGULATIONS] §999.315(c)(2).

While still experimental, GPC could potentially be used to indicate rights in other jurisdictions as well.

Currently the California AG has stated that the GPC signal is a legitimate way to state a Do Not Sell directive under CCPA and as such the primary use for most publishers will be to read the GPC signal and use it to set the preexisting USPAPI signal. However, not all publishers may decide to do this, some may not know to, and some may have legal interpretations that state otherwise.

Additionally, downstream consumers of the OpenRTB signal may decide through their own legal analysis that GPC applies more broadly than just to California residents. At this time, there is no way to enable anyone outside of the publisher who is involved in the bidstream to make such a decision, since the GPC signal--while present on the network request as a header--may not be present on the signals passed through servers and other systems in the form of the OpenRTB objects.

By adding GPC to the OpenRTB spec in the form of an extension, it will enable other bidding system participants to make their own decision as to if they wish to apply a stricter standard of privacy.

qty should be a float

When referencing digital out of home, shouldn't we allow qty to be a float instead of an integer.

When using data from studies, they might need to break down the number of contacts to something between 0 and 1.

And even modern tracking systems are advanced enough to say, that a user just saw one third of the spot, so this can go into as 0.333 instead of 0 or 1.

eids missing in final spec ? Define recommendation spec for user.ext.eids

There was a good standardisation proposal of how extended ids (eids) can be passed through oRTB in the draft/proposal :
https://iabtechlab.com/wp-content/uploads/2017/09/OpenRTB-3.0-Draft-Framework-for-Public-Comment.pdf

Digitrust have also proposed using this standard in their oRTB spec:
https://github.com/digi-trust/dt-cdn/wiki/OpenRTB-extension

Is there a reason why we ditched this in final release?

Looking at the growing adoption of identity solution:

• If there is no eids object in AdCOM user object then let's include some recommendation around structure which industry should use under user.ext
• This will help streamline implementations if we plan to include this later in spec

Contradiction in the supply chain object spec

In the definition of the nodes attribute, it says the first node can be the the owner of the site. However, the owner of the site or the publisher doesn't have an sid that represents the upstream entity because it's the inventory creator, not the reseller, and the field sid is required so how can a node of publisher be included in the supply chain object?

DSA Query Params

Is dsaparams=1_2 equivalent to dsatransparency=~1_2? Why do we have both? Should one superseded the other?

@lamrowena @hillslatt

trustid_gln_result.png

Trust.id

Create community extension to support Trust.id

Payment ID in OpenRTB

Please see the attached for Payment ID support in OpenRTB.

OpenRTB PaymentID Advisory August 2016.pdf

Broken link for: "Advertising Common Object Model (AdCOM)"

On line 274 of OpenRTB 3.0 BETA.md, https://raw.githubusercontent.com/InteractiveAdvertisingBureau/AdCOM returns a 401

[INQUERY] Publishment about Japanese translation

I'm translating OpenRTB 3.0 spec personally, and eventually I would like to publish it for many Japanese engineers to get familier with ad-tech ;)
Of course, I figure out that no problem on the license. But I'm pleased to get your right comprehensions for this work.
Thanks !

Missing GPP Extension?

This document references the OpenRTB extensions in this repo:

Like other existing privacy signals (TCF and USPrivacy), the GPP string is also able to be transported via OpenRTB. This will be included in the Regs object in the November 2022 release. See this document for approved design prior to release.

However, there is no actual reference to GPP anywhere to be found, so far as I can tell. There is increasing pressure to support GPP by Jan 1, 2023, but I can't find any official information on the OpenRTB implementation.

Can anyone confirm the specification for OpenRTB 2.5? From some past proposals and discussion, I've gathered:

regs.ext.gpp (GPP string)
regs.ext.gpp_sid (array of relevant section IDs)

pmp in final 3.0?

Hello.

In OpenRTB 3.0 Draft (February 2017) there was pmp object in Item - private marketplace container. But it's missing in Final version. How can seller and buyer exchange Direct deal ID?

DigiTrust community extension

Document the spec currently defined at https://github.com/openrtb/OpenRTB/wiki/In-Progress-Extensions

Zeros should not be meaningfull values

Depending on the api framework a value can be zero (not null) if it hasn't been set.
Therefore 0 (zero) values should never be used as a meaningfull value to avoid unwanted behaviour.
I hope it's not too late for this change in the Digital Services Act specification

Mock up data for openrtb

Is there anywhere I can retrieve fake openrtb json data for native bid requests for testing integrations?

"Refer to Context"

Question about context field, on Object: Request.

the spec says: object: recomended

why not is defined as a Object: Context. with this spec, and with a reference "Refer to Context"

Context

• site: [Site],
• app: [App],
• dooh: [Dooh],
• user: [User],
• device: [Device],
• regs: [Regs],
• restrictions: [Restrictions]

Layer-4 domain object structure that provides context for the items being offered conforming to the specification and version referenced in openrtb.domainspec and openrtb.domainver.
For AdCOM v1.x, the objects allowed here all of which are optional are one of the DistributionChannel subtypes (i.e., Site, App, or Dooh), User, Device, Regs, Restrictions, and any objects subordinate to these as specified by AdCOM.

https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/OpenRTB%20v3.0%20FINAL.md#object--request-

thanks

Bid Request example JSON does not match Source object documentation

Source object does not have hb and fd fields.

But Bid Request example has these.

Not submitting PR just in case this was to illustrate something (what exactly then), but looks more just a "bad" copypaste.

URLs for Brand Safety

Create community extension to better support brand safety in cases where the ad may appear in a feed type environment.

Logical expression on restrictions

Sometimes we need logical expression on bcat, badv, battr, etc on block/allow restriction fields, For example, IF advertiser = X THEN allow_category = A ELSE block_category = [B, C], such logic is difficult to be expressed in existing structure of block/allow fields.

One solution is to use vendor specified cattax to express a logical value on other cattax, but this seems overloading cattax when there are many logical expression to support. Another solution is to use new extension to logical expression. Wantted to hear what the community and IAB working group think for such use cases.

<script async src="https://fundingchoicesmessages.google.com/i/pub-5328552429034223?ers=1" nonce="8v3euzFMkRnwVfHrCzv5eA"></script><script nonce="8v3euzFMkRnwVfHrCzv5eA">(function() {function signalGooglefcPresent() {if (!window.frames['googlefcPresent']) {if (document.body) {const iframe = document.createElement('iframe'); iframe.style = 'width: 0; height: 0; border: none; z-index: -1000; left: -1000px; top: -1000px;'; iframe.style.display = 'none'; iframe.name = 'googlefcPresent'; document.body.appendChild(iframe);} else {setTimeout(signalGooglefcPresent, 0);}}}signalGooglefcPresent();})();</script>

Per-Impression Transaction IDs for multi-impression bid requests

OpenRTB bid requests support an array of impression objects, which could correspond to multiple discrete transactions. However, the spec only supports 1 transaction ID via the source.tid field. I'm proposing a community extension that allows for specifying a transaction ID per item in the impression array.

SupplyChain Object tamper-prevention

Does the 3.0 specification in any way prevent malicious/unscrupulous sellers from modifying the SupplyChain Object that is passed to downstream demand sources?

The Ads.cert specification allows buyers to cryptographically verify the integrity of the BidRequest object, but it doesn't seem as if any signing of the SupplyChain Object takes place at downstream transactions. What prevents a seller from simply removing SupplyChainNodes from the list and misrepresenting the supply chain to a buyer?

This picture is broken

https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/skadnetwork.md#regulatory-guidance

Filename issue

Hi,

There is a possible issue on Windows devices with this URL :
https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/ads.cert:%20Signed%20Bid%20Requests%201.0%20BETA.md

Because of the ":" next to "ads.cert"

segtax review and field usage mixup concerns

Standardise referencing taxonomies

Based on Open RTB 2.6 "segtax" is an out of date reference. "cattax" has been added to many objects to refer to the list of categories in the Adcom 3.0 spec. It would be better to align/standardise how this centrally managed list of categories is referred to, see cattax usage in here: https://iabtechlab.com/wp-content/uploads/2021/12/OpenRTB-2.6.pdf

It appears data.ext.cattax would now be more suitable if needed.

Incorrect field usage

Regarding the need for this extension, there seems to be a conflict between this extension and open RTB itself, specifically between the use of data.segement.id and data.segment.value. To me it appears this spec is confused as to what each means.

• data.segment.id Specifies the ID of the segment, e.g. "502"
• data.segment.name Specifies the name e.g. "JW Player video content taxonomy"
• data.segment.value Specifies the data segment value from within the segment e.g. "1234"

Here's an illustrative example to demonstrate how such data passing currently works without the need for "segtax".

{
  "data":[
    {
      "id":"jwplayer",
      "name":"JW Player RTD Provider",
      "segment":[
        {
          "id":"502",
          "name":"JW Player video content taxonomy",
          "value":"1234"
        }
      ]
    },
    {
      "id":"dap",
      "name":"Akamai Data Activation Platform (DAP)",
      "segment":[
        {
          "id":"503",
          "name":"Akamai Data Activation Platform (DAP) - Buyer Defined Audiences (BDA), Scrambled",
          "value":"abc123"
        },
        {
          "id":"505",
          "name":"Akamai Data Activation Platform (DAP) - Custom Audiences, Reserved 1",
          "value":"def456"
        }
      ]
    }
  ]
}

Questions

• Can someone comment on the apparent misuse of the data.segment.id instead of data.segment.value field in this spec and whether this 'segtax' extension achieves what it sets out to achieve if the data.segment.id field already covers this requirement?
• If there is clarity of purpose for each of their fields, can you add an example where all 3 fields would be used together to demonstrate that clarity i.e. segment.id, segment.value, and data.ext.segtax

New object for dooh

Wouldn't it be better to introduce a new Object Type for dooh. Currently each SSP is using either site or app. But both are wrong.

Should we introduce something like

dooh: {
  player_id: "Some Unique Identifier per SSP",
  name: "Terminal A, Gate 52",
  location: {
    id: "42203".
    name: "Airport Citz XZY
  }, 
  network: {
     id: "3442",
     name: "GDNP Airport"
  }
}

If these information are not going into the standard, there should be at least a guidline about how to fill existing app or site object with these data. But I really prefer to add a new dooh type. I think dooh is a bigger evolution to openrtb then app has been to online.

I am open to discuss this. Happy to discuss this with you at Demexo. Just send me a message.

Restriction at placement level

The spec mentioned "The Placement group comprises objects that define the set of allowed ads and behaviors for a given placement. This might include mechanical information (e.g., sizes, supported mime types, and other rendering options), placement details and positioning, and various restrictions lists."

But I don't find where we can define restrictions of Restrictions object for a placement. Looks like Restrictions object only exist in Context object. Is this intended?

Wait, isn't segtax supposed to be a string?

In this document, segtax is an integer, but according to the spec (https://iabtechlab.com/wp-content/uploads/2022/02/IAB-Tech-Lab-Taxonomy-and-Data-Transparency-Standards-to-Support-Seller-defined-Audience-and-Context-Signaling.pdf) it seems to be a string.

That being said, on page 17 of the spec it's also used as an integer.

open rtb3.0 sample static request in JSON format

Hi,
Find out the below static JSON format of open rtb 3.0 request for reference.Please check and conform back.,
Request JSON Start
{
"openrtb": {
"ver": "3.0",
"domainspec": "adcom",
"domainver": "1.0",
"request": {
"id": "0123456789ABCDEF",
"tmax": 150,
"at": 2,
"cur": [ "USD", "EUR" ],
"source": {
"tid": "FEDCBA9876543210",
"ts": 1541796182157,
"ds": "AE23865DF890100BECCD76579DD4769DBBA9812CEE8ED90BF",
"dsmap": "...",
"cert": "ads-cert.1.txt",
"pchain": "..."
},
"package": 0,
"item": [
{
"id": "1",
"qty": 1,
"flr": 0.03,
"private": 0,
"deal": [
{
"id": "1234",
"flr": 1.50
}
],
"spec": {
"placement": {
"tagid": "plc-ftr-123abc",
"secure": 1,
"display": {
"bannerformat": [
{
"w": 728,
"h": 90,
"pos": 1,
"btype": [4],
"battr": [14]
}
],
"event": [
{
"type": 1,
"method": [ 1 ]
}
]
}
}
}
}
],
"context": {
"site": {
"id": "102855",
"name": "Example Site Name",
"domain": "http://www.example.com",
"cat" : [ "IAB15", "IAB15-10" ],
"sectioncat" : [ "IAB15", "IAB15-10" ],
"pagecat" : [ "IAB15", "IAB15-10" ],
"page": "http://easy.example.com/easy?cu=13824;cre=mu;target=_blank",
"ref" : "http://refer+url",
"amp" : "0",
"keywords" : "sports,education,business",
"publisher": {
"id": "qqwer1234xgfd",
"name": "site_name",
"domain": "my.site.com"
}
},
"app": {
"domain": "www.yahoo.com",
"cat" : [ "IAB15", "IAB15-10" ],
"sectioncat" : [ "IAB15", "IAB15-10" ],
"pagecat" : [ "IAB15", "IAB15-10" ],
"keywords" : "sports,education,business"
},

		"user": {  
					"buyeruid" : "89776897686798fwe87rtryt8976fsd7869678",
					"id": "55816b39711f9b5acf3b90e313ed29e51665623f",
					"gender": "M",
					"yob": 1975,
					"keywords": "sports,education,business",
					"data": {
						"id":"5581",
						"name":"Example data Name",
								"segment":{
											"name":"Example segment Name",
											"value":""
										}
							}
				},
	
		"device": {  
					"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13  (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2",
					"ip": "192.168.5.5",
					"ipv6": "FE80:0000:0000:0000:0202:B3FF:FE1E:8329",
					"devicetype": "",
					"make": "Apple",
					"model": "iphone",
					"os": "iOS",
					"language": "",
					"carrier": "VERIZON",
						"geo": {
								"lat": 37.789,
								"lon": -122.394,
								"country": "USA",
								"city": "San Francisco",
								"region": "CA",
								"zip" : "94105",
								"metro": "",
								"type": 2
						}  
				 },
				 
		"regs": {
					"gdpr": 0,
					"coppa": 0
				},
		"restrictions": {
					"bcat": [ "IAB24", "IAB25", "IAB26" ],
					"cattax": 1,
					"badv": [ "ford.com", "buick.com" ]
				}
 }

}
}
}
Request JSON End

Stricter versioning?

Hey,

Today I've found something interesting: 5a6aac5

Basically, List: Lost Reason Codes enum was shifted by one item in the middle.

And this is reflected in Change Log

Though version is not bumped - it's still 3.0, which surprises me (I consider such change not being back-compatible).

IMO such changes without version bump may prevent exchanges from adopting and fully adhering to the spec.

I understand that it's just a Loss Reason codes to be used in macro (like, it's not the "core" enum used in object props etc), but if spec defines such enum - I'd expect it to be more "stable".

Or is this spec supposed to be versioned not like 3.0, 3.1 or 3.0.1, but like 3.0 November 2018, 3.0 June 2020 etc?

I'd really love if this (reminding - supposed-to-be-industry-standard) spec would be versioned in a more strict way (I'd prefer semver).

CA Senta Bill 568

Create community extension for the CA Senate Bill 586 ext documented at https://github.com/openrtb/OpenRTB/wiki/In-Progress-Extensions

Extended Content IDs community extension

Issue to track any final discussion before committing pull request for extended content IDs.

Macro object clarification - is Bid Response macros example correct?

I personally understand Macro object documentation as this:

{
  "key": "${OPENRTB_ID}",
  "value": "XXX",
  "ext": {
    "custom": "data"
  }
}

But in Bid Response example it's:

{ "TIMESTAMP": "1127987134" },
{ "CLICKTOKEN": "A7D800F2716DB" }

Which is good for traffic saving.

Which is the correct variant to use it? (IMO, Macro section needs amendment then to eliminate such questions in future)

Item.id docs should use string examples

The description of Item.id field is:

A unique identifier for this item within the context of the offer (typically starts with 1 and increments).

But the field has type string, so the example would be more clear as:

A unique identifier for this item within the context of the offer (typically starts with "1" and increments).

Please consider replacing the references in section INTRODUCTION

In the file ads.cert 1.0 BETA.md the citations explaining the fraud scenario in section INTRODUCTION should be revised.

Please consider replacing references [1] and [2] in that section by a new reference to IAB US benchmarking study of Nov. 2015.

The section INTRODUCTION refers to [1][2][3] in order to avoid explaining the fraud problem in detail. [1] and [2] are Wikipedia articles on cryptographic algorithms and don't mention the word "fraud" at all. [3] is a techcrunch article which explains some aspects of fraud in short and refers to the comprehensive IAB study mentioned above.

Ada Issue

DSA example not fully correct

DSA PR was merged but I see one more thing should be fixed. Docs looks fine, but JSON response example doesn't.
In the response JSON example, transparency should be array of object, not object.

current

"ext": {
        "dsa": {
            "behalf": "Advertiser",
            "paid": "Advertiser",
            "transparency": {
                "domain": "dsp1domain.com",
                "params": [
                    1,
                    2
                ]
            },
            "adrender": 1
        }
    }

updated

 "ext": {
        "dsa": {
            "behalf": "Advertiser",
            "paid": "Advertiser",
            "transparency": [
                {
                    "domain": "dsp1domain.com",
                    "params": [
                        1,
                        2
                    ]
                }
            ],
            "adrender": 1
        }
    }

@lamrowena @hillslatt

https://github.com/InteractiveAdvertisingBureau/openrtb/blob/main/extensions/community_extensions/dsa_transparency.md#sample-openrtb-26-bid-response-with-dsa-transparency

schain or supplychain?

Hi IAB,

I'm working on implementing the SupplyChain object for our system and noticed that there is a paragraph in the text documentation referring to the object as "schain", and the examples show "supplychain".

Could you advise which is correct?