├── .gitignore ├── OpenRTB v3.0 FINAL.md ├── README.md ├── ads.cert: Signed Bid Requests 1.0 BETA.md ├── extensions ├── 2.x_official_extensions │ ├── README.md │ ├── eids.md │ └── gpc.md ├── README.md ├── community_extensions │ ├── Protected Audience Support.md │ ├── README.md │ ├── SCID.md │ ├── assets │ │ ├── extended-ids-diagram.png │ │ ├── test.txt │ │ ├── trustid_gln_result.png │ │ └── trustid_gln_search.png │ ├── ca-568.md │ ├── deprecation_test_label.md │ ├── digitrust.md │ ├── dsa_transparency.md │ ├── extended-content-ids.md │ ├── gpid.md │ ├── ifa_type.md │ ├── intrinsic-in-game.md │ ├── per-imp-tids.md │ ├── pla.md │ ├── seat-non-bid.md │ ├── segtax.md │ ├── skadnetwork.md │ └── urls-brand-safety.md ├── extensions.xmind └── extensions_lifecycle.png └── supplychainobject.md /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![IAB Tech Lab](https://drive.google.com/uc?id=10yoBoG5uRETSXRrnJPUDuONujvADrSG1) 2 | 3 | # **OpenRTB 3.0** 4 | 5 | #### About OpenRTB 6 | https://iabtechlab.com/openrtb 7 | 8 | #### About OpenMedia 9 | https://iabtechlab.com/openmedia 10 | 11 | #### AdCOM: Advertising Common Object Model 12 | https://github.com/InteractiveAdvertisingBureau/AdCOM 13 | 14 | #### About This Repository 15 | At all times, the **master** branch of this repository contains the most recent release of OpenRTB. See ["OpenRTB v3.0 Final.md"](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/OpenRTB%20v3.0%20FINAL.md) in the master branch for the latest specification. 16 | 17 | 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. 18 | 19 | The **develop** branch contains work-in-progress for an upcoming release. It may change at any time. 20 | 21 | #### Contact 22 | For more information, or to get involved, please email support@iabtechlab.com. 23 | 24 | #### About IAB Tech Lab 25 | 26 | The IAB Technology Laboratory is a nonprofit research and development consortium charged 27 | with producing and helping companies implement global industry technical standards and 28 | solutions. The goal of the Tech Lab is to reduce friction associated with the digital advertising 29 | and marketing supply chain while contributing to the safe growth of an industry. 30 | The IAB Tech Lab spearheads the development of technical standards, creates and maintains a 31 | code library to assist in rapid, cost-effective implementation of IAB standards, and establishes a 32 | test platform for companies to evaluate the compatibility of their technology solutions with IAB 33 | standards, which for 18 years have been the foundation for interoperability and profitable growth 34 | in the digital advertising supply chain. 35 | 36 | Learn more about IAB Tech Lab here: [https://www.iabtechlab.com/](https://www.iabtechlab.com/) 37 | 38 | 39 | #### Contributors and Technical Governance 40 | 41 | 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. 42 | 43 | Learn more about how to submit changes in our working group: [So, You'd Like to Propose a Change...](http://iabtechlab.com/blog/so-youd-like-to-propose-a-change-to-openrtb-adcom/) 44 | 45 | ### License 46 | 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. 47 | 48 | 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](https://iabtechlab.com/ipr-iab-techlab/acknowledge-ipr/) 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. 49 | 50 | #### Disclaimer 51 | 52 | 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. 53 | -------------------------------------------------------------------------------- /ads.cert: Signed Bid Requests 1.0 BETA.md: -------------------------------------------------------------------------------- 1 | ![](https://drive.google.com/uc?id=1MStOYYaZDqrvuOwlmecX0iayL0Jt_eAN) 2 | 3 | # ads.cert v2.0: 4 | 5 | 6 | 7 | **September 2021** 8 | 9 | The beta draft of ads.cert 1.0 was released November 2018, but never was released as a standard for a number of reasons. 10 | The IAB Tech Lab Cryptographic Security Foundations Working Group has decided to take ads.cert in a new direction, independent of OpenRTB 3.0 (and OpenRTB itself in some ways) and more directly modeled after other cryptographic security standards. The new specifications are available at [https://iabtechlab.com/ads-cert](https://iabtechlab.com/ads-cert) 11 | 12 | The 1.0 beta draft can be found in this history of this file, but we recommend that everyone follow the new specifications. 13 | 14 | 15 | -------------------------------------------------------------------------------- /extensions/2.x_official_extensions/README.md: -------------------------------------------------------------------------------- 1 | ![IAB Tech Lab](https://drive.google.com/uc?id=10yoBoG5uRETSXRrnJPUDuONujvADrSG1) 2 | 3 | # **Official 2.x Extensions** 4 | 5 | This folder contains the OpenRTB 2.x extensions that have been approved by the IAB Tech Lab Programmatic Supply Chain Working Group, after having demonstrated that they have been widely adopted as a community extension. 6 | 7 | ### Extended Identifiers(eids) 8 | 9 | #### Issue: [#27](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/27) 10 | 11 | #### Notes 12 | The goal with this extension is to support a standard protocol for multiple third party identity provider to the ecosystem for 2.x. This is same object which is part of native user object in [oRTB 3.0 extended identifiers](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#object_eids) 13 | 14 | See [eids.md](eids.md) for more details. 15 | 16 | #### Issue: [#98](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/98) 17 | 18 | #### Notes 19 | The goal with this extension is to support propagating the Global Privacy Control signal that originates in the HTTP headers from a web client, in order for all participants to have access to the same information on the privacy state of a user in regard to applicable regulations. 20 | 21 | See [gpc.md](gpc.md) for more details. 22 | -------------------------------------------------------------------------------- /extensions/2.x_official_extensions/eids.md: -------------------------------------------------------------------------------- 1 | # DEPRECATED as of OpenRTB 2.6 Use [Object: EID](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-) in OpenRTB 2 | 3 | ### Extended Identifiers(eids) 4 | 5 | **Issue**: [#27](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/27) 6 | 7 | **Sponsor**: PubMatic 8 | 9 | **Goal**: 10 | 11 | # DEPRECATED as of OpenRTB 2.6 Use [Object: EID](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-) in OpenRTB 12 | 13 | The goal is to support a standard protocol for multiple third party identity provider to the ecosystem for 2.x. 14 | This is same object which is part of native user object in [oRTB 3.0 extended identifiers](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#object_eids) 15 | 16 | # DEPRECATED as of OpenRTB 2.6 Use [Object: EID](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-) in OpenRTB 17 | 18 | **Requested Changes**: 19 | # DEPRECATED as of OpenRTB 2.6 Use [Object: EID](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-) in OpenRTB 20 | 21 | Addition to **User Extension** Object 22 | 23 | 24 | ### Object: Extended Identifiers 25 | 26 | # DEPRECATED as of OpenRTB 2.6 Use [Object: EID](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-) in OpenRTB 27 | 28 | Extended identifiers support in the OpenRTB specification allows buyers to use audience data in real-time bidding. The exchange should ensure that business agreements allow for the sending of this data. Note, it is assumed that exchanges and DSPs will collaborate with the appropriate regulatory agencies and ID vendor(s) to ensure compliance. 29 | 30 | # DEPRECATED as of OpenRTB 2.6 Use [Object: EID](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-) in OpenRTB 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 |
Attribute        Type                    Definition
sourcestringSource or technology provider responsible for the set of included IDs. Expressed as a top-level domain.
uidsobject arrayArray of extended ID UID objects from the given source. Refer to Object: Extended Identifier UIDs.
extobjectOptional vendor-specific extensions.
54 | 55 | # DEPRECATED as of OpenRTB 2.6 Use [Object: EID](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-) in OpenRTB 56 | 57 | ### Object: Extended Identifier UIDs 58 | 59 | # DEPRECATED as of OpenRTB 2.6 Use [Object: EID](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-) in OpenRTB 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 |
Attribute        Type                    Definition
idstringCookie or platform-native identifier.
atypeintegerType of user agent the match is from. It is highly recommended to set this, as many DSPs separate app-native IDs from browser-based IDs and require a type value for ID resolution. Refer to List: Agent Types.
extobjectOptional vendor-specific extensions.
83 | 84 | # DEPRECATED as of OpenRTB 2.6 Use [Object: EID](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-) in OpenRTB 85 | 86 | ### List: Agent Types 87 | 88 | # DEPRECATED as of OpenRTB 2.6 Use [List: Agent Types](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list--agent-types-) in AdCOM 89 | 90 | This list identifies the user agent types a user identifier is from. 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 |
ValueDefinition
1An ID which is tied to a specific web browser or device (cookie-based, probabilistic, or other).
2In-app impressions, which will typically contain a type of device ID (or rather, the privacy-compliant versions of device IDs).
3A person-based ID, i.e., that is the same across devices.
500+Vendor-specific codes.
113 | 114 | # DEPRECATED as of OpenRTB 2.6 Use [List: Agent Types](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list--agent-types-) in AdCOM 115 | 116 | Example Request 117 | 118 | # DEPRECATED as of OpenRTB 2.6 Use [Object: EID](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-) in OpenRTB and [List: Agent Types](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list--agent-types-) in AdCOM 119 | 120 | ``` 121 | { 122 | "user": { 123 | "id": "aaa", 124 | "buyerid": "xxx", 125 | "ext": { 126 | "eids": [ 127 | { 128 | "source": "x-device-vendor-x.com", 129 | "uids": [ 130 | { 131 | "id": "yyy", 132 | "atype": 1 133 | }, 134 | { 135 | "id": "zzz", 136 | "atype": 1 137 | }, 138 | { 139 | "id": "DB700403-9A24-4A4B-A8D5-8A0B4BE777D2", 140 | "atype": 2 141 | } 142 | ] 143 | }, 144 | { 145 | "source": "digitru.st", 146 | "uids": [ 147 | { 148 | "id": "IPl4zj44RhezVyNE83bYfoz59H5GCIQrfCdAVyN51zcsme0faoHqfLBijMQEazqGewXTZsMwMfZqwne8x4eAVeNmAx7iPpk7bpGYp71GUZyysbEEReDYEMJ2hNSldGTT9UExI62HvXuBM16X121r0i8Tko2Bps84tQFWb4lJeun/nRzYwj3ehUGjkE3UOxvHoplNqA43n25pRjgUkUVTRgrpTVLv5Vl4PJ4ir7twHLLow539N3ETb0cHt8GVweHBc2dGmqUTNQxGUZxBA21omEmotXpfqRKrHUo4fm/O9NFgYRN6W8LaCy3USy8dPQ==", 149 | "atype": 1, 150 | "ext": { 151 | "keyv": 4 152 | } 153 | } 154 | ] 155 | }, 156 | { 157 | "source": "stat-id-vendor-z.org", 158 | "uids": [ 159 | { 160 | "id": "0db20294a3908612bc7e732c2022095391074cf3", 161 | "atype": 1, 162 | "ext": { 163 | "confidence": 0.75 164 | } 165 | } 166 | ] 167 | } 168 | ] 169 | } 170 | } 171 | } 172 | ``` 173 | # DEPRECATED as of OpenRTB 2.6 Use [Object: EID](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-) in OpenRTB and [List: Agent Types](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list--agent-types-) in AdCOM 174 | -------------------------------------------------------------------------------- /extensions/2.x_official_extensions/gpc.md: -------------------------------------------------------------------------------- 1 | # Global Privacy Control 2 | 3 | Issue: [#98](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/98) 4 | 5 | Sponsor: Magnite 6 | 7 | ## Objective 8 | 9 | The purpose of this field is to support propagating the Global Privacy Control (GPC) signal that originates in the HTTP headers from a web client, in order for all participants to have access to the same information on the privacy state of a user in regard to applicable regulations. 10 | 11 | ## Request Changes 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 |
Content ObjectTypeExample valuesDescription
regs.ext.gpcstring1This is to be populated the value of the `Sec-GPC` HTTP header from the user agent where the ad will be shown. Vendors with access to that header must populate this field with that value. Vendors receiving an OpenRTB request must populate this with the value of the same field from the request. No other usage of this field is valid. E.g., vendors are not to copy the GPC signal from the GPP string to this field.
27 | 28 | ## Example Request 29 | 30 | ``` 31 | { 32 | "regs": { 33 | "ext": { 34 | "gpc": "1" 35 | } 36 | } 37 | } 38 | ``` 39 | -------------------------------------------------------------------------------- /extensions/README.md: -------------------------------------------------------------------------------- 1 | ![IAB Tech Lab](https://drive.google.com/uc?id=10yoBoG5uRETSXRrnJPUDuONujvADrSG1) 2 | 3 | # **Extensions** 4 | 5 | 6 | #### What is the lifecycle of an Extension? 7 | When individual companies want to solve a problem that isn't covered by the core OpenRTB (or AdCOM) specs, they can use OpenRTB's (and AdCOM's) extensions mechanism to implement a solution. They can work on it privately and limit usage between themselves, or they can make the OpenRTB "Community" aware of this extension to guage the usefulness of that extension. After a period of time, if there is sufficient support, the extension can be made part of the "official" specs by getting approval from the Programmatic Supply Chain Working Group. This path is slightly different for OpenRTB 2.x and 3.x because the Working Group has decided that there will be no more updates to 2.x. So with 2.x the extension gets moved to the "Official extensions" folder, while with 3.x it gets added to the OpenRTB/AdCOM specs and released as a new version of the spec. 8 | 9 | ![extensions lifecycle](extensions_lifecycle.png) 10 | 11 | 12 | 13 | #### How do I submit a "community extension"? 14 | 1. Submit an issue on the github repository for OpenRTB or AdCOM depending on where your extension belongs. (If you are submitting a 2.x extension, it belongs to OpenRTB. For 3.x, it will depend on what you are trying to "extend"). 15 | 2. Submit a PR associated with that issue, with files in the [extensions/community_extensions](../extensions/community_extensions) folder. Also include an entry in the [extensions/community_extensions/README.md](../extensions/community_extensions/README.md). 16 | 17 | #### How do I get a community extension formally adopted into the specs? 18 | 1. Submit an issue and PR with the desired changes on the github repository for OpenRTB or AdCOM. 19 | 2. Email us at support@iabtechlab.com with any information not in the issue/PR, including any adoption information for the community extension. 20 | 3. We will discuss in the Programmatic Supply Chain Working Group and (assuming you are a Tech Lab member) likely invite you to present. 21 | 4. Once approved, the extension will be either moved to the [extensions/2.x_official_extensions](../extensions/2.x_official_extensions) folder or made a part of the 3.x specs (to be released with the next official version of the specs). 22 | 23 | #### What are the current community extensions? 24 | You can find the current extensions in the [extensions/community_extensions](../extensions/community_extensions) folder. 25 | -------------------------------------------------------------------------------- /extensions/community_extensions/Protected Audience Support.md: -------------------------------------------------------------------------------- 1 | # Bid Request Values 2 | 3 | ## Object: InterestGroupAuctionSupport 4 | 5 | `BidRequest.imp.ext.igs`: This extension to "Object: Imp" allows sellers to signal Interest Group auction support for an Impression to buyers. 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 22 | 23 | 24 | 25 | 26 | 33 | 34 |
AttributeTypeDescription
aeinteger;
default 1		Interest Group auction environment support for this impression:
17 | 0 = Interest Group auction not supported
18 | 1 = on-device-orchestrated Interest Group auction
19 | 3 = server-orchestrated Interest Group auction
20 |
21 | Note that this only indicates that the Interest Group auction is supported, not that it is guaranteed to execute. If no buyer chooses to participate in the Interest Group auction, then the Interest Group auction will be skipped and the winner of the OpenRTB (aka contextual) auction, if any, will serve instead.
biddableinteger;
default 0		Indicates whether the buyer is allowed to participate in the Interest Group auction. Depending on account settings and other factors, a bidder might be disallowed from participating in an auction or submitting Interest Group bids, even though an Interest Group auction may ultimately decide the winning ad. The seller sets this.
27 | Example: the publisher intends to enable Interest Group, but the seller has not onboarded this buyer for Interest Group auctions. Buyers should only expect sellers to honor corresponding Interest Group Intent signals when this field is 1. 28 |
29 |
30 | 0 = no, the buyer is not allowed
31 | 1 = yes, the buyer is allowed 32 |
35 | 36 | 37 | # Bid Response Values 38 | 39 | ## Object: InterestGroupAuctionIntent 40 | 41 | `BidResponse.ext.igi`: This extension to "Object: BidResponse" allows buyers and sellers to provide necessary signals in order to operate an Interest Group auction for a given ad slot.
42 | Must include at least a buyer object (`igb`, in the bid response from the buyer to the seller) or seller object (`igs`, from the seller to the publisher), but not both. 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 |
AttributeTypeDescription
impidstring; required*ID of the Imp object in the related bid request. Used to link Interest Group buyer information to the specific ad slot.
54 | *Only required in the bid response from the buyer to the seller
igbarray; requiredOne or more InterestGroupAuctionBuyer objects. Required and mutually exclusive with igs.
igsarray; requiredOne or more InterestGroupAuctionSeller objects. Required and mutually exclusive with igb.
67 | 68 | ## Object: InterestGroupAuctionBuyer 69 | 70 | `BidResponse.ext.igi.igb`: Information provided by the buyer and necessary for the seller to build the associated `config`. 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 116 | 117 |
AttributeTypeDescription
originstring; requiredOrigin of the Interest Group buyer to participate in the IG auction. See https://developer.mozilla.org/en-US/docs/Glossary/Origin.
maxbiddoubleMaximum Interest Group bid price expressed in CPM currency that a bidder agrees to pay if they win an in-browser Interest Group auction expressed expressed in the currency denoted by the cur attribute. Actual winning bid in the in-browser auction that determines the amount a bidder pays for the impression may be lower than this amount. This constraint reduces the risks from in-browser auction bids submitted in error or reported due to fraud and abuse.
curstring;
default "USD"		 92 | The buyer's currency signals, an object mapping string keys to Javascript numbers. If specified, the seller will add to its auction config perBuyerCurrencies attribute map, keyed by the Interest Group buyer origin. Indicates the currency in which Interest Group bids will be placed. The maxbid should always match the cur value. 93 |

94 | Value must be a three digit ISO 4217 alpha currency code (e.g. "USD"). 95 |
pbsany valid JSON expressionBuyer-specific signals ultimately provided to this buyer's generateBid() function as the perBuyerSignals argument. If specified, the seller will add to its auction config perBuyerSignals attribute map, keyed by the Interest Group buyer Origin. Per PA API spec, the value may be any valid JSON serializable value.
psobjectThe buyer’s priority signals, an object mapping string keys to Javascript numbers. If specified, the seller will add to its auction config perBuyerPrioritySignals attribute map, keyed by the Interest Group buyer origin. See https://github.com/WICG/turtledove/blob/main/FLEDGE.md#35-filtering-and-prioritizing-interest-groups
begidintThe buyer’s experiment group ID, an integer between zero and 65535 (16 bits). If specified, the seller will add to its auction config perBuyerExperimentGroupIds attribute map, keyed by the Interest Group buyer origin. See https://github.com/WICG/turtledove/blob/main/FLEDGE.md#21-initiating-an-on-device-auction 114 | NOTE: Assuming the auction is not run in parallel, the seller will provide the value via the perBuyerExperimentGroupIds auction configuration, provided the seller does not start the auction in parallel with OpenRTB requests. 115 |
118 | 119 | 120 | ## Object: InterestGroupAuctionSeller 121 | 122 | `BidResponse.ext.igi.igs`: Information provided by the seller and necessary to initiate an Interest Group component auction.
123 | Component seller auction configuration should be submitted to the top-level seller's on-page library for inclusion in the Interest Group auction. 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 |
AttributeTypeDescription
impidstring; requiredID of the Imp object in the related bid request. Used to link Interest Group seller information to the specific ad slot.
configobject; requiredAuction config for a component seller
142 | 143 | # Non-OpenRTB Signaling 144 | The objects coming from sellers or publishers are expected to be ‘namespaced.’ If OpenRTB is reused it is under the "ortb2" key. 145 | 146 | NOTES: 147 | * If the publisher shares some vendor info that would be namespaced within the pub's windowHostname key, e.g. "prebid.org" or "vendor.com". 148 | * If sellers are using directFromSellerSignals to communicate this information, they should follow the same naming convention. 149 | * If ortb2 namespace is used, it is expected that the structured request matches OpenRTB object model and definitions. All deviations should be done as extensions and negotiated apriori between the parties wanting to send/receive non-standard signals. 150 | 151 | ## Object: InterestGroupAuctionBuyerSignals 152 | Early PAAPI auction provisioning practice was for buyers to supply their perBuyerSignals to seller partners as a passthrough value BidResponse.ext.igbid[].igbuyer[].buyerdata or some other means. The seller places this in the buyer’s key in auctionConfig.perBuyerSignals and PA then provides the value as the perBuyerSignals parameter to generateBid. This does not afford a clean way for the seller to provide signals to a specific buyer, such as Deals. 153 | 154 | To accommodate this, the community extensions support a more open perBuyerSignals handling. In an OpenRTB BidRequest sellers can signal their ability to provide and in the BidResponse buyers may opt in to receive an InterestGroupAuctionBuyerSignals object in the interest group auction. 155 | 156 | This object is a dictionary with support for some combination of the following enteries: 157 | 158 | ```javascript 159 | { 160 | let signalsFromMyOrigin = perBuyerSignals[browserSignals.interestGroupOwner]; 161 | let signalsFromComponentSeller = perBuyerSignals[browserSignals.seller]; 162 | let signalsFromTopLevelSeller = perBuyerSignals[browserSignals.topLevelSeller]; 163 | let signalsFromPublisher = perBuyerSignals[browserSignals.topWindowHostname]; 164 | } 165 | ``` 166 | 167 | The presence and placement of these entries determine the role of the Origin listed. 168 | 169 | While the entities listed above and their associated Origins are defined values established and recognized by the PA APIs, others may be included based on specific agreement between partners that have been negotiated a priori. In that case, the canonical domain of the parties should be used. 170 | 171 | See Namespacing section of implementation guidance for additional detail https://github.com/hillslatt/examplefork/edit/hillslatt-ig-support-ext/extensions/community_extensions/Protected%20Audience%20Support.md?pr=%2FInteractiveAdvertisingBureau%2Fopenrtb%2Fpull%2F175#namespacing 172 | 173 | # Implementation Guidance 174 | 175 | ## Bid Request 176 | 177 | ### Signaling Interest Group Auction Support 178 | 179 | Following extends the basic banner example to advertise Interest Group auction support. 180 | 181 | ```javascript 182 | { 183 | "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22", 184 | "at": 1, 185 | "cur": [ 186 | "USD" 187 | ], 188 | "imp": [ 189 | { 190 | "id": "1", 191 | "bidfloor": 0.03, 192 | "banner": { 193 | "h": 250, 194 | "w": 300, 195 | "pos": 0 196 | }, 197 | "ext": { 198 | "igs":{ 199 | "ae": 1 200 | } 201 | } 202 | }], 203 | "site": { 204 | "id": "102855", 205 | "cat": [ 206 | "IAB3-1" 207 | ], 208 | "domain": "www.example.com", 209 | "page": "http://www.example.com/1234.html", 210 | "publisher": { 211 | "id": "8953", 212 | "name": "example.com", 213 | "cat": [ 214 | "IAB3-1" 215 | ], 216 | "domain": "example.com" 217 | }, 218 | "user": { 219 | "id": "55816b39711f9b5acf3b90e313ed29e51665623f" 220 | } 221 | } 222 | } 223 | ``` 224 | 225 | ## Bid Response 226 | 227 | ### Bid Placed with Interest Group Auction Intent by the Buyer 228 | 229 | Following extends the Ad Served On Win Notice example to demonstrate a bidder placing a bid into the standard OpenRTB auction and also signaling intent to the seller for one IG owner/buyer to participate in potential on-device auction. 230 | 231 | 232 | ```json 233 | { 234 | "id": "1234567890", 235 | "bidid": "abc1123", 236 | "cur": "USD", 237 | "seatbid": [ 238 | { 239 | "seat": "512", 240 | "bid": [ 241 | { 242 | "id": "1", 243 | "impid": "102", 244 | "price": 9.43, 245 | "nurl": "http://adserver.com/winnotice?impid=102", 246 | "iurl": "http://adserver.com/pathtosampleimage", 247 | "adomain": [ 248 | "advertiserdomain.com" 249 | ], 250 | "cid": "campaign111", 251 | "crid": "creative112", 252 | "attr": [ 253 | 1, 254 | 2, 255 | 3, 256 | 4, 257 | 5, 258 | 6, 259 | 7, 260 | 12 261 | ] 262 | } 263 | ] 264 | } 265 | ], 266 | "ext": { 267 | "igi":[{ 268 | "impid": "1", 269 | "igb":[{ 270 | "origin": "https://paapi.dsp.com", 271 | "pbs": "{\"key\": \"value\"}" 272 | }] 273 | }] 274 | } 275 | } 276 | ``` 277 | 278 | ### No Bid with Interest Group Auction Intent by the Buyer 279 | 280 | Following is an example where a bidder places no bid in the standard OpenRTB auction, but does signal intent to participate in potential on-device IG auction. 281 | 282 | ```json 283 | { 284 | "id": "1234567890", 285 | "seatbid": [], 286 | "ext": { 287 | "igi":[{ 288 | "impid": "1", 289 | "igb":[{ 290 | "origin": "https://paapi.dsp.com", 291 | "pbs": "{\"key\": \"value\"}" 292 | }] 293 | }] 294 | } 295 | } 296 | ``` 297 | 298 | ### Auction Config Placed with Interest Group Auction Intent by the Seller 299 | 300 | Following extends the Ad Served On Win Notice example to demonstrate a seller placing an auction config into the standard OpenRTB auction and also signaling intent to the publisher to participate in potential on-device auction. 301 | 302 | 303 | ```json 304 | { 305 | "id": "1234567890", 306 | "bidid": "abc1123", 307 | "cur": "USD", 308 | "seatbid": [ 309 | { 310 | "seat": "512", 311 | "bid": [ 312 | { 313 | "id": "1", 314 | "impid": "102", 315 | "price": 9.43, 316 | "nurl": "http://adserver.com/winnotice?impid=102", 317 | "iurl": "http://adserver.com/pathtosampleimage", 318 | "adomain": [ 319 | "advertiserdomain.com" 320 | ], 321 | "cid": "campaign111", 322 | "crid": "creative112", 323 | "attr": [ 324 | 1, 325 | 2, 326 | 3, 327 | 4, 328 | 5, 329 | 6, 330 | 7, 331 | 12 332 | ] 333 | } 334 | ] 335 | } 336 | ], 337 | "ext": { 338 | "igi":[{ 339 | "igs":[{ 340 | "impid": "1", 341 | "config": { 342 | "key": "value" 343 | } 344 | }] 345 | }] 346 | } 347 | } 348 | ``` 349 | 350 | ### Namespacing 351 | Where participants in the auction are using the OpenRTB object model, the seller atrribute should always always have a sub-attribute called .ortb2. 352 | 353 | #### Namespacing in auctionSignals 354 | The auctionSignals metadata may originate from diverse sources, so this map should be ‘namespaced’ by the providing entity. Where an entity is using OpenRTB objects, it should provide them in an attribute named ortb2. For example: 355 | 356 | ```jsonc 357 | { 358 | ... 359 | "auctionSignals": { 360 | "prebid": { 361 | "ortb2": { 362 | ... // sparse OpenRTB Bid Request attributes 363 | } 364 | }, 365 | "seller": { 366 | "ortb2": { 367 | ... 368 | } 369 | } 370 | } 371 | ... 372 | } 373 | ``` 374 | 375 | ### Name Spaced Multi-seller Auction 376 | ```javascript 377 | { 378 | 'seller': 'https://www.example-toplevelseller.com', 379 | 'componentAuctions': [ 380 | { 381 | "seller": "https://www.example-ssp.com", 382 | "interestGroupBuyers": ["https://www.example-dsp.com"], 383 | "perBuyerSignals": { 384 | "https://www.example-dsp.com": { 385 | "https://www.example-toplevelseller.com": {}, /* top-level seller’s origin */ 386 | "https://www.example-ssp.com": { /* seller’s origin */ 387 | "ortb2":{ 388 | "imp":[ 389 | "pmp":{ 390 | "deals":[...] 391 | } 392 | ] 393 | } 394 | }, 395 | "https://www.example-dsp.com": igi.igb[].pbs, /* buyer’s origin */ 396 | "www.example-publisher.com": {}, /* publisher host without scheme */ 397 | } 398 | }, 399 | ... 400 | }, 401 | ... 402 | ] 403 | } 404 | ``` 405 | 406 | **Within generateBid** 407 | generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals, directFromSellerSignals) 408 | ```javascript 409 | { 410 | let signalsFromMyOrigin = perBuyerSignals[browserSignals.interestGroupOwner]; 411 | let signalsFromComponentSeller = perBuyerSignals[browserSignals.seller]; 412 | let signalsFromTopLevelSeller = perBuyerSignals[browserSignals.topLevelSeller]; 413 | let signalsFromPublisher = perBuyerSignals[browserSignals.topWindowHostname]; 414 | } 415 | ``` 416 | 417 | ### Name Spaced Single-seller Auction 418 | ```javascript 419 | { 420 | 'seller': 'https://www.example-seller.com', 421 | "interestGroupBuyers": ["https://www.example-dsp.com"], 422 | "perBuyerSignals": { 423 | "https://www.example-dsp.com": { 424 | "https://www.example-seller.com": {}, /* single-seller’s origin */ 425 | "https://www.example-dsp.com": igi.igb[].pbs, /* buyer’s origin */ 426 | "www.example-publisher.com": {}, /* publisher host without scheme */ 427 | } 428 | }, 429 | ... 430 | } 431 | ``` 432 | 433 | **Within generateBid** 434 | ```javascript 435 | generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals, directFromSellerSignals) 436 | { 437 | let signalsFromMyOrigin = perBuyerSignals[browserSignals.interestGroupOwner]; 438 | let signalsFromSingleSeller = perBuyerSignals[browserSignals.seller]; 439 | let signalsFromPublisher = perBuyerSignals[browserSignals.topWindowHostname]; 440 | } 441 | ``` 442 | -------------------------------------------------------------------------------- /extensions/community_extensions/README.md: -------------------------------------------------------------------------------- 1 | ![IAB Tech Lab](https://drive.google.com/uc?id=10yoBoG5uRETSXRrnJPUDuONujvADrSG1) 2 | 3 | # **Community Extensions** 4 | 5 | 6 | ### Digitrust 7 | 8 | #### Issue: [#33](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/33) 9 | 10 | #### Notes 11 | 12 | See [digitrust.md](digitrust.md) for details. 13 | 14 | ### CA Senate Bill 568: Privacy: Internet: minors 15 | 16 | #### Issue: [#35](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/35) 17 | 18 | #### Notes 19 | 20 | See [ca-568.md](ca-568.md) for deatils. 21 | 22 | ### URLs for Brand Safety 23 | 24 | #### Issue: [#39](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/39) 25 | 26 | #### Notes 27 | 28 | See [urls-brand-safety.md](urls-brand-safety.md) for deatils. 29 | 30 | ### SKAdNetwork Support 31 | 32 | #### Issue: [#43](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/43) 33 | 34 | #### Notes 35 | 36 | See [skadnetwork.md](skadnetwork.md) for deatils. 37 | 38 | ### SCID.id 39 | 40 | #### Issue: [#50](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/50) 41 | 42 | #### Notes 43 | 44 | See [SCID.md](SCID.md) for deatils. 45 | 46 | ### Extended Content IDs 47 | 48 | #### Issue: [#82](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/82) 49 | 50 | #### Notes 51 | 52 | See [extended-content-ids.md](extended-content-ids.md) for deatils. 53 | 54 | ### Seat Non Bid Response 55 | 56 | #### Issue: [#115](https://github.com/InteractiveAdvertisingBureau/openrtb/pull/115) 57 | 58 | #### Notes 59 | 60 | See [seat-non-bid.md](seat-non-bid.md) for deatils. -------------------------------------------------------------------------------- /extensions/community_extensions/SCID.md: -------------------------------------------------------------------------------- 1 |

Cross-platform campaign identification : SCID (Shared Campaign Identifier)

2 | 3 | Sponsors: Smart Adserver, Xandr 4 | 5 |

Version History

6 | 7 | | Date | Version | Comments | 8 | | :-- | :-- | :-- | 9 | | Sept 2021 | 1.0 | Added use of alternatives to GLN as Advertiser ID | 10 | | June 2021 | 1.0 | Trust.id name changes to SCID (Shared Campaign Identifier) | 11 | 12 | 13 |

Overview

14 | 15 | By using SCID, Advertisers and Publishers will get more transparency and tracking for their programmatic buying and selling. 16 | 17 | Several advertising associations, representing all stakeholders involved in the buying process, including Edipub, stand together to make sure to find consensual solutions, to meet compliance and to define best practices, in responses to transparency requirements. 18 | SCID: A worldwide approach for a shared need. 19 | 20 |

Problem statement

21 | Lack of transparency in campaigns,where publishers or advertisers cannot track campaigns effectively. 22 | 23 |

Definition

24 | SCID is a key enabling identification and tracking throughout a campaign lifecycle. The goal is to keep following a campaign, provide more transparency, and bring the links in the programmatic chain closer during the reporting operations. 25 |

26 | The trading desk is used to working with many DSPs. This unique and dedicated SCID field helps to efficiently track the campaign, regardless of the DSPs and SSPs used. 27 | 28 |

Who is involved?

29 | 30 | - Advertisers 31 | - Trading desks (independent and agencies / disclosed and undisclosed) 32 | - DSP 33 | - SSP 34 | - Publishers (direct or through saleshouses) 35 | 36 |

The genuine specification

37 | 38 | ``` 39 | SCID = Advertiser ID + Advertiser brand + Advertiser product code + Customer Product Estimate + Ext (optional) 40 | ``` 41 | 42 | See below the description of each piece from the genuine specification : 43 | 44 | - Advertiser ID : It contains the acronym or name of the registry and the registration number which is an existing international ID used to identify a company (advertiser). For example, GLN-123 or SIRET-456. 45 |
As an identifier, an advertiser can have a [GLN](https://en.wikipedia.org/wiki/Global_Location_Number) and/or a [DUNS](https://en.wikipedia.org/wiki/Data_Universal_Numbering_System) and/or a [SIRET](https://en.wikipedia.org/wiki/SIRET_code)/[SIREN](https://en.wikipedia.org/wiki/SIREN_code) or can use any other registry as long as this registration number is reputed unique. 46 |

Below is an example of a request using GLN. The registry of GLNs is managed by [GEPIR](https://gepir.gs1.org/) (Global Electronic Party Information Registry) which allows identification of a company thanks to its GLN :
![Search](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/assets/trustid_gln_search.png)

Result :
![Result](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/assets/trustid_gln_result.png) 47 | 48 | - Advertiser brand, Advertiser product code and Customer Product Estimate are defined at the advertiser's discretion. 49 | 50 |

Example with a media brief from Nestlé

51 | 52 | The trading desk Publicis has a campaign with Nestlé for the Olympics Games in 2020 : 53 | - Advertiser ID = GLN-0050000000951 54 | - Advertiser Brand = Nestlé
Note : We do not use the adomain field in OpenRTB because a lot of different adomains are created and linked to the same brand. Allowing the buyer to put the advertiser brand from the media brief will help to give more transparency about the campaign. 55 | - Advertiser Product = OG2020 56 | - Customer Product Estimate = Publicis 57 | 58 | At the end, the SCID is GLN-0050000000951+Nestlé+OG2020+Publicis 59 | 60 |

How SCID works

61 | 62 | 63 | 1. The advertiser sends a media brief with its own information (brand, product, targeting etc...) to the trading desk. This brief must contain enough data to generate SCID. 64 | 65 | 2. With the advertiser’s brief, the trading desk sets and gives the input to the campaign within the DSPs. During the setup, the trading desk ensures to set correctly SCID. 66 | 67 | 3. DSPs deliver the campaign. 68 | 69 | 4. SCID is carried within the Bid response. Campaign is tracked by SSPs and the publishers, thanks to SCID received in the bid response. 70 | 71 | 5. During and/or at the end of the campaign display, **all the intermediaries in the programmatic chain** can compare the data with SCID.
72 | 73 | Below is the brief media from an advertiser to a trading desk : 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 |
SCIDCreative ID
GLN-3015619200106+Booking+MTEL+CPExxxCreative Id 1
GLN-3015619200106+Booking+MTEL+CPExxxCreative Id 2
GLN-3015619200106+Booking+MTEL+CPExxxCreative Id 3
93 | 94 | The trading desk puts the unique SCID (GLN-3015619200106+Booking+MTEL+CPExxx) within the DSP to identify and track the campaign with the 3 creatives (Creative Id 1, Creative Id 2, Creative Id 3). 95 | 96 |

SCID support flow

97 | 98 | 99 | Following the OpenRTB protocol, BidResponse.seatbid.bid.cid was first evaluated as a potential way to communicate the SCID in the bid response. However, this one is used in many ways by the DSPs: 100 | 101 | - DSP generates automatically cid for each new campaign (a technical ID vs SCID who is a business ID). 102 | 103 | - DSP sends other data via this field (ex: buyer info) 104 | 105 | - DSP does not use this field because it does not want to share sensitive data. 106 | 107 | - DSP does not use/support this field at all. 108 | 109 | As we can see above, cid is used for many different reasons or is not used at all. **That’s why we need to create a new field in order to track** SCID. This new field will help to get an official process and will avoid custom and costly developments on the SSP and DSP. 110 | 111 |

Extension details

112 | 113 |

Bid response :

114 | 115 | #### Object: `BidResponse.seatbid.bid.ext` 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 |
AttributeDescriptionTypeExample
SCIDUnique key enabling to identify and track a campaign during its lifecycle regardless of the SSP and DSP used.

Note : scid contains the AdvertiserID (Global location number) + Advertiser brand + Advertiser product code + Customer Product Estimate + Ext (optional)		string"scid": "GLN-3015619200106+Booking+MTEL+CPExxx"
131 | 132 | 133 | 134 |

Example bid response

135 | 136 | ```javascript 137 | { 138 | "id": "1234567890", 139 | "bidid": "abc1123", 140 | "cur": "USD", 141 | "seatbid": [{ 142 | "seat": "512", 143 | "bid": [{ 144 | "id": "1", 145 | "impid": "102", 146 | "price": 9.43, 147 | "nurl": "http://adserver.com/winnotice?impid=102", 148 | "iurl": "http://adserver.com/pathtosampleimage", 149 | "adomain": ["advertiserdomain.com"], 150 | "cid": "campaign111", 151 | "crid": "creative112", 152 | "ext": { 153 | "scid": "GLN-3015619200106+Booking+MTEL+CPExxx" 154 | } 155 | ] 156 | } 157 | ] 158 | } 159 | } 160 | ``` 161 | -------------------------------------------------------------------------------- /extensions/community_extensions/assets/extended-ids-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/InteractiveAdvertisingBureau/openrtb/7f8b96a1860dea3680137c8f1042eefd5ba1b27e/extensions/community_extensions/assets/extended-ids-diagram.png -------------------------------------------------------------------------------- /extensions/community_extensions/assets/test.txt: -------------------------------------------------------------------------------- 1 | Test 2 | -------------------------------------------------------------------------------- /extensions/community_extensions/assets/trustid_gln_result.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/InteractiveAdvertisingBureau/openrtb/7f8b96a1860dea3680137c8f1042eefd5ba1b27e/extensions/community_extensions/assets/trustid_gln_result.png -------------------------------------------------------------------------------- /extensions/community_extensions/assets/trustid_gln_search.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/InteractiveAdvertisingBureau/openrtb/7f8b96a1860dea3680137c8f1042eefd5ba1b27e/extensions/community_extensions/assets/trustid_gln_search.png -------------------------------------------------------------------------------- /extensions/community_extensions/ca-568.md: -------------------------------------------------------------------------------- 1 | ### CA Senate Bill 568: Privacy: Internet: minors 2 | 3 | #### Issue: [#35](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/35) 4 | 5 | Sponsor: Rubicon Project 6 | 7 | The goal is to support [California Senate Bill No. 568](http://leginfo.legislature.ca.gov/faces/billNavClient.xhtml?bill_id=201320140SB568). 8 | 9 | Request Changes 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 |
Regulations ObjectTypeExample valuesDescription
regs.ext.s22580Integer0, 1A value of 1 indicates that the content is directed at minors and that specific types of products should not be advertised.
25 | 26 | Example Request 27 | 28 | ``` 29 | { 30 | "regs":{ 31 | "ext":{ 32 | "s22580": 1 33 | } 34 | } 35 | } 36 | ``` -------------------------------------------------------------------------------- /extensions/community_extensions/deprecation_test_label.md: -------------------------------------------------------------------------------- 1 | ### Cookie Deprecation: Pass Chrome-facilitated cookie deprecation test label 2 | 3 | **Sponsor**: Epsilon 4 | 5 | **Background**: 6 | Google recently published [an update](https://developer.chrome.com/docs/privacy-sandbox/chrome-testing/) regarding the UK CMA-aligned Chrome cookie deprecation testing labels announced in May. Chrome intends to label 9.5% percent of Chrome Stable browsers globally. A browser instance, if labeled, is either Mode A (8.5%, opt-in testing beginning Q4 2023) or Mode B (1%, forced cookie deprecation beginning Q1 2024). Two means are offered to access the label. One can read a request header after setting a special partitioned (CHIPS) cookie or client-side via a new `Navigator` script API promise. 7 | 8 | **Proposal**: 9 | Entities are encouraged to access the label and to share the value unmodified with partners via the following `Device` extension. 10 | 11 | ### Object: `Device.ext` 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 |
Attribute        Type                    Description
cdepstringthe label as received from Chrome or an upstream partner
24 | 25 |

26 | 27 | **Notes** 28 | No requirement to communicate label provenance, header versus API access. 29 | 30 | Privacy Sandbox enrollment is _not_ required to access the labels. 31 | 32 | If you have opinions or feedback about the test group labeling plans, the Chrome team has encouraged interested parties to weigh in on the Privacy Sandbox Developer Support “chrome-testing” issues. Link below. 33 | 34 | 35 |
36 | 37 | **References** 38 | Chrome-facilitated testing (Chrome Developer Relations) 39 | [https://developer.chrome.com/docs/privacy-sandbox/chrome-testing/](https://developer.chrome.com/docs/privacy-sandbox/chrome-testing/) 40 | 41 | Privacy Sandbox Developer Support “chrome-testing” issues, Github 42 | [https://github.com/GoogleChromeLabs/privacy-sandbox-dev-support/labels/chrome-testing](https://github.com/GoogleChromeLabs/privacy-sandbox-dev-support/labels/chrome-testing) 43 | 44 | Chrome implementation Monorail issues 45 | `Sec-Cookie-Deprecation` header access 46 | [https://bugs.chromium.org/p/chromium/issues/detail?id=1479071](https://bugs.chromium.org/p/chromium/issues/detail?id=1479071) 47 | Implement JS API for `navigator.cookieDeprecationLabel.getValue()` 48 | [https://bugs.chromium.org/p/chromium/issues/detail?id=1479119](https://bugs.chromium.org/p/chromium/issues/detail?id=1479119) 49 | 50 | Chromium Dash Schedule (Chrome milestone releases) 51 | [https://chromiumdash.appspot.com/schedule](https://chromiumdash.appspot.com/schedule) 52 | 53 | UK Competition and Markets Authority (CMA) Test Guidelines 54 | [https://www.gov.uk/cma-cases/investigation-into-googles-privacy-sandbox-browser-changes#industry-testing](https://www.gov.uk/cma-cases/investigation-into-googles-privacy-sandbox-browser-changes#industry-testing) 55 | 56 | Privacy Sandbox enrollment and attestations model, GitHub 57 | [https://github.com/privacysandbox/attestation/blob/main/README.md](https://github.com/privacysandbox/attestation/blob/main/README.md) 58 | 59 | PSA: Third-party cookie deprecation for 1% of Chrome Stable starting Q1 2024 (blink-dev) 60 | [https://groups.google.com/a/chromium.org/g/blink-dev/c/GJl_aMO6Qt4/m/gFEMFo8FAgAJ](https://groups.google.com/a/chromium.org/g/blink-dev/c/GJl_aMO6Qt4/m/gFEMFo8FAgAJ) 61 | 62 | Intent to Prototype: Third-Party Cookie Phaseout (blink-dev) 63 | [https://groups.google.com/a/chromium.org/g/blink-dev/c/8mlWTOcEzcA/m/NZJSW0weAQAJ](https://groups.google.com/a/chromium.org/g/blink-dev/c/8mlWTOcEzcA/m/NZJSW0weAQAJ) 64 | 65 | Deprecate Third-Party Cookies (Chrome feature card) 66 | [https://chromestatus.com/feature/5133113939722240](https://chromestatus.com/feature/5133113939722240) 67 | -------------------------------------------------------------------------------- /extensions/community_extensions/digitrust.md: -------------------------------------------------------------------------------- 1 | ### DigiTrust 2 | 3 | Issue: [#33](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/33) 4 | 5 | Sponsor: Rubicon Project 6 | 7 | The goal is to support [Digitru.st](http://www.digitru.st/) as a third party identity provider to the ecosystem. 8 | 9 | Request Changes 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 |
User ObjectTypeExample valuesDescription
user.ext.digitrustObject{ }Container object for DigiTrust ID and related attributes.
user.ext.digitrust.idStringT4MNpfKqn9D9sMuPuH/e3c+14heCiUWXjbg+vN5OqYlYFmh3V8GAtQhQRYx2vuUJ8wJ7nEtFgkmX0jAKW+0i3dvm4Ak/GraYN92IsGHofjubb5zxShu8kQgUQzGn8pSZoNnNOt6OfXy5MiJ5izmM/wSeoA3hwbSaiLaNwbksYcNGrbbxQtDD+ni6hyRsS2vdrqKLE4gGob4MqcZBQQ95YhGr0Ix22EJs2CgD9KnDJ+O9X53d36vi2qbEtFi9+w7tG+LwTfLqTqq6XK30UAc9HxtuWBM1HQFdP9JvDShRo5V0yFZ0PsLgay3puVIHzAaQhj6gBkjsjRzG10CW8DnrHA==Encrypted user ID as provided by DigiTrust.
user.ext.digitrust.keyvInteger2Key version responsible for encryption of the ID.
37 | 38 | Example Request 39 | 40 | ``` 41 | { 42 | "user":{ 43 | "ext":{ 44 | "digitrust": { 45 | "id":"F6vrzeiV625KD2WaTcGs68ajfRYokPFm6jNUSsawIKAdo/K8vOCPQ24l7hvEatiOBnsBOABTCjmcMe7C2PkzWgZ4zQeZ6qA5ZfmOVfRbdWjxSO2T+wAuMrLkczqHeXCSLBlR4iyz5ho1o44IPwXyxuYI7iXehBk7F/4QJvnSmK1pCyhp+7UszarryqwGVAjIwwekBxmYm/sU8OZeiUOe8iLa/ggQwf0S1Gl5WpFB7IecyrxGF5fu1jRsbmiF5viYTDUBAiq9Q5TlnA2uawkaNYJGmFT83GEIbYjt27ZiEXMru1NzzaaQBdZA1u97LPDQekj/bvCARwQxbrr1P/uJbA==", 46 | "keyv": 1 47 | } 48 | } 49 | } 50 | } 51 | ``` 52 | -------------------------------------------------------------------------------- /extensions/community_extensions/dsa_transparency.md: -------------------------------------------------------------------------------- 1 |

DSA Transparency

2 | This specification is stewarded by IAB Tech Lab's Global Privacy Working Group. IAB Tech Lab and IAB Europe will continue partnership to steward this solution. IAB Tech Lab will maintain the technical specifications. IAB Europe will provide policy guidance, such as implementation guidelines. 3 | 4 |

Introduction

5 |

The Digital Services Act (DSA) was adopted in October 2022, and the date of applicability for Platform companies is 16 February 2024.  Along with the Digital Markets Act (DMA), the DSA is intended to improve the confidence of both private consumers and business users of Online Platforms in the products and services they access via those platforms, as well as the advertising they are exposed to on them, and to ensure a level playing field between platforms.  The DSA lays down transparency obligations in relation to advertising; these obligations apply to Online Platforms, “Very Large Online Platforms” (VLOPs), and “Very Large Online Search Engines” (VLOSEs) as defined by the Digital Services Act.  

6 |

Article 26 of the DSA requires Online Platforms to ensure that users have real-time access to certain elements of information about any ad shown to them on an Online Platform:

7 | 14 |

Although the legal obligation to provide the user-facing information disclosures applies to Online Platforms, it is clear that in many advertising scenarios, those platforms will need to rely on third-party vendors for the data that will be required to populate the disclosures.  To ensure that the third parties are equipped to provide this support, this technical specification standardizes the collection, compilation and transport of the data, leaving Online Platforms free to decide how they wish to make the user-facing disclosures, including if they want to delegate the disclosures to another party.  

15 |

This technical specification provides data formats and transport for the advertising industry to implement relevant DSA transparency information. This solution should be applicable across most relevant use cases including; programmatic and non-programmatic media buys, channels including desktop web, mobile (web/app), video, CTV.

16 |

Object Specification for OpenRTB 2.X

17 |

Bid Request

18 |

Object: Regs

19 |
20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 |
AttributeTypeDescription
ext.dsaobject Extension for DSA transparency information
34 |
35 |

Object: DSA

36 |
37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 52 | 53 | 54 | 55 | 56 | 60 | 61 | 62 | 63 | 64 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 |
AttributeTypeDescription
dsarequiredintegerFlag to indicate if DSA information should be made available. This will signal if the bid request belongs to an Online Platform/VLOP, such that a buyer should respond with DSA Transparency information based on the pubrender value. 48 |

0 = Not required

49 |

1 = Supported, bid responses with or without DSA object will be accepted

50 |

2 = Required, bid responses without DSA object will not be accepted

51 |

3 = Required, bid responses without DSA object will not be accepted, Publisher is an Online Platform

pubrenderintegerFlag to indicate if the publisher will render the DSA Transparency info. This will signal if the publisher is able to and intends to render an icon or other appropriate user-facing symbol and display the DSA transparency info to the end user. 57 |

0 = Publisher can't render

58 |

1 = Publisher could render depending on adrender

59 |

2 = Publisher will render

datatopubintegerIndependent of pubrender, the publisher may need the transparency data for audit purposes. 65 |

0 = do not send transparency data

66 |

1 = optional to send transparency data

67 |

2 = send transparency data

transparencyarray of objectArray of objects of the entities that applied user parameters and the parameters they applied.
76 |
77 |

Object: Transparency 

78 |
79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 |
AttributeTypeDescription
domainstring Domain of the entity that applied user parameters 
dsaparamsarray of integerArray for platform or sell-side use of any user parameters (using the list provided by DSA Transparency Taskforce). Note; See definition and list of possible user parameters as listed here, applied consistently in both bid request and/or bid response.
98 |
99 |

Sample OpenRTB 2.6 Bid Request with DSA transparency:

100 | 101 | ``` 102 | { 103 | "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22", 104 | "at": 1, 105 | "cur": [ 106 | "USD" 107 | ], 108 | "regs": { 109 | "ext": { 110 | "dsa": { 111 | "dsarequired": 3, 112 | "pubrender": 0, 113 | "datatopub": 2, 114 | "transparency": [{ 115 | "domain": "platform1domain.com", 116 | "dsaparams": [1]}, 117 | {"domain": "SSP2domain.com", 118 | "dsaparams": [1,2] 119 | }] 120 | } 121 | } 122 | }, 123 | "imp": [{ 124 | "id": "1" 125 | }], 126 | "site": { 127 | "id": "102855" 128 | }, 129 | "user": { 130 | "id": "55816b39711f9b5acf3b90e313ed29e51665623f" 131 | } 132 | } 133 | 134 | ``` 135 | 136 |

Bid Response

137 |

Object: Bid

138 |
139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 |
AttributeTypeDescription
ext.dsaobject DSA Ad Transparency information
153 |
154 |

Object: DSA

155 |
156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 184 | 185 | 186 |
AttributeTypeDescription
behalfstringAdvertiser Transparency: Free UNICODE text string with a name of whose behalf the ad is displayed. Maximum 100 characters.
paidstringAdvertiser Transparency: Free UNICODE text string of who paid for the ad. Must always be included even if it's the same as what is listed in the behalf attribute. Maximum 100 characters
transparencyarray of objectArray of objects of the entities that applied user parameters and the parameters they applied.
adrenderintegerFlag to indicate that buyer/advertiser will render their own DSA transparency information inside the creative. 182 |

0 = buyer/advertiser will not render

183 |

1 = buyer/advertiser will render

187 |
188 |

Object: Transparency

189 |
190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 |
AttributeTypeDescription
domainstringDomain of the entity that applied user parameters 
dsaparamsarray of integerArray of buy-side applied user parameter targeting (using the list provided by DSA Transparency Taskforce). Include support for multiple vendors who may add their own user-targeting parameters.
209 |
210 |

Sample  OpenRTB 2.6 Bid Response with DSA transparency:

211 | 212 | ``` 213 | { 214 | "id": "1234567890", 215 | "bidid": "abc1123", 216 | "seatbid": [{ 217 | "seat": "512", 218 | "bid": [{ 219 | "id": "1", 220 | "nurl": "http://adserver.com/winnotice?impid=102", 221 | "iurl": "http://adserver.com/pathtosampleimage", 222 | "adomain": [ 223 | "advertiserdomain.com" 224 | ], 225 | "ext": { 226 | "dsa": { 227 | "behalf": "Advertiser", 228 | "paid": "Advertiser", 229 | "transparency": [{ 230 | "domain": “dsp1domain.com”, 231 | "dsaparams": [1,2] 232 | }], 233 | "adrender": 1 234 | } 235 | } 236 | }] 237 | }] 238 | } 239 | ``` 240 | 241 |

List of User Parameters

242 |

The definitions below are not meant to be consumer-facing messages.

243 |
244 | 245 | 246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255 | 256 | 257 | 258 | 259 | 260 | 261 | 262 | 263 | 264 | 265 | 266 | 267 | 268 | 269 | 270 | 271 |
User Parameter IDUser ParameterDefinitionTCF Purpose IDs
1ProfilingInformation about the user, collected and used across contexts, that is about the user's activity, interests, demographic information, or other characteristics.TCF Purposes 4
2Basic advertisingUse of real-time information about the context in which the ad will be shown, to show the ad, including information about the content and the device, such as: device type and capabilities, user agent, URL, IP address, non-precise geolocation data. Additionally, use of basic cross-context information not based on user behavior or user characteristics, for uses such as frequency capping, sequencing, brand safety, anti-fraud.TCF Purpose 2
3Precise geolocationThe precise real-time geolocation of the user, i.e. GPS coordinates within 500 meter radius precision.TCF Special Feature 1
272 |
273 |

URL-based support

274 |

Some ad systems may depend on URLs to communicate information. The following parameters and macros can be used to carry relevant DSA information in these cases.

275 |
276 | 277 | 278 | 279 | 280 | 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 |
URL ParameterCorresponding MacroRepresentation in URL
dsarequiredDSAREQUIRED&dsarequired=${DSAREQUIRED}
dsabehalfDSABEHALF&dsabehalf=${DSABEHALF}
dsapaidDSAPAID&dsapaid=${DSAPAID}
dsaparamsDSAPARAMS&dsaparams=${DSAPARAMS}
dsatransparencyDSATRANSPARENCY&dsatransparency=${DSATRANSPARENCY}
dsapubrenderDSAPUBRENDER&dsapubrender=${DSAPUBRENDER}
dsadatatopubsDSADATATOPUBS&dsadatatopubs=${DSADATATOPUBS}
320 |
321 | 322 |
323 | 324 | 325 | 326 | 327 | 328 | 329 | 330 | 331 | 332 | 336 | 337 | 338 | 339 | 340 | 342 | 343 | 344 | 345 | 346 | 348 | 349 | 350 | 351 | 352 | 354 | 355 | 356 | 357 | 358 | 360 | 361 | 362 | 363 | 364 | 367 | 368 | 369 | 370 | 371 | 374 | 375 | 376 | 377 |
MacroPossible ValuesDefinition
${DSAREQUIRED}

0 = Not required 333 |

1 = Supported, bid responses with or without DSA object will be accepted

334 |

2 = Required, bid responses without DSA object will not be accepted

335 |

3 = Required, bid responses without DSA object will not be accepted, Publisher is an Online Platform

Indicates if DSA information should be made available. 
${DSABEHALF}Free UNICODE text string with a name of whose behalf the ad is displayed. 341 |

Example: Advertiser

Populated from the DSP bid response.
${DSAPAID}Free UNICODE text string of who paid for the ad 347 |

Example: Advertiser

Populated from the DSP bid response.
${DSAPARAMS}Any combination of the integer values representing the user parameters. When multiple values are included, they should be separated by an underscore “_”.  353 |

Example: 1_2_3

Populated based on the combination of information from the bid request and bid response user parameters. 
${DSATRANSPARENCY}Composed of the two items from the transparency object; the domain string and the params array. These two items are separated by a tilde “~”. Values in the params array are separated by an underscore “_”. Multiple transparency objects are separated by two tildes “~~”. 359 |

Example: &dsatransparency=platform1domain.com~1~~SSP2domain.com~1_2

Populated based on the transparency object from the bid request and the bid response.  
${DSAPUBRENDER}

0 = Publisher can’t render

365 |

1 = Publisher could render depending on adrender

366 |

2 = Publisher will render

Signals if the publisher is able to and intends to render an icon or other appropriate user-facing symbol and display the DSA transparency info to the end user.
${DSADATATOPUBS}

0 = do not send transparency data

372 |

1 = optional to send transparency data

373 |

2 = send transparency data

Independent of pubrender, the publisher may need the transparency data for audit purposes.
378 |
379 | 380 | Changelog 381 | 382 | 383 | 384 | 385 | 386 | 387 | 388 | 389 | 393 | 394 | 395 | 396 | 397 | 398 | 399 |
DateComments
January 26, 2024Updates to attributes to avoid reserved words: 390 |
  • Update of the required attribute name to dsarequired
    • 391 |
  • Update of the params attribute name to dsaparams
    • 392 |
    January 16, 2024Original publish
    400 | 401 | -------------------------------------------------------------------------------- /extensions/community_extensions/extended-content-ids.md: -------------------------------------------------------------------------------- 1 | # DEPRECATED as of OpenRTB 2.6-202504 Use `cids` [in Object: Data]([https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/develop/2.6.md#3221---object-data-)) in OpenRTB 2 | 3 | # Extended Content Identifiers 4 | 5 | 2022-01-19 6 | 7 | 8 | ## Sponsors 9 | 10 | * Ian Trider, Basis Technologies 11 | * Joseph Hirsch, SpringServe 12 | * Gerry Swinton, Magnite, Inc. 13 | * Mark Rogers, Oracle Advertising 14 | * Rob Caliolo, JW Player 15 | * C.J. Leonard, IRIS.TV 16 | * Kwun Choy, Freewheel 17 | * Daniel Church, Beachfront 18 | * Emera Trujillo, MediaMath 19 | * Nate Leaf, Comscore 20 | * Patrick McCann, CafeMedia 21 | 22 | 23 | ## Background 24 | 25 | There is a market desire to target by video/audio content metadata or contextual classifications thereof. This requires some sort of scheme for identifying individual pieces of content, transmitting that in a bid request, and enabling lookup or classification of that piece of content’s metadata. 26 | 27 | There are several companies/services which act as a clearinghouse or aggregator of metadata from publishers ("*Content Data Platform*"). Examples include IRIS.TV and JWPlayer. These services ingest video content metadata from publishers and assign an ID for each piece of content that is unique within that content data platform. There are contextual data vendors, such as Oracle and comScore, who have access to this aggregated metadata and, if provided a content ID, can return classifications of the content based on what is available in that metadata. 28 | 29 | The following diagram illustrates how this works. The numbers indicate the essential flow/sequence from the perspective of the DSP. Data flow between publishers and the content data platform is out of band from the RTB process. 30 | 31 | 32 | ![diagram](assets/extended-ids-diagram.png) 33 | 34 | 35 | In the RTB process, the sequence is as follows: 36 | 37 | 38 | 39 | 1. The publisher includes a content ID (and the source of that ID) in its request to the exchange for ad fill. This will be a content ID previously assigned by the content data platform. 40 | 2. The exchange includes this in the bid request to the DSP. 41 | 3. The DSP queries its contextual vendor with this. 42 | 4. The contextual vendor requests the metadata from the content data platform. 43 | 5. The content data platform returns it. 44 | 6. The contextual vendor returns classifications to the DSP. These classifications are as agreed upon between the contextual vendor and DSP, and are based on transforming or classifying information from the metadata in some way. For example, the vendor could perform topic classification on a synopsis, or perform video/audio recognition on a content URL. 45 | 46 | In practice, one or more layers of caching may be involved in steps 3-6 due to the real-time constraint of RTB. 47 | 48 | 49 | ## What this document is – and is not 50 | 51 | This community extension addresses #2 -- how the content ID information is to be conveyed in bid requests, so that DSPs can request classifications from contextual vendors. 52 | 53 | It addresses passing a unique ID for a single piece of video/audio content. **It does not address passing categorizations of the content (“Comedy”, “Personal Finance”, etc.) according to some taxonomy.** For that, see [Segment Taxonomies community extension](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/segtax.md) and the IAB [Seller-defined Audience and Context Signalling](https://iabtechlab.com/wp-content/uploads/2021/03/IABTechLab_Taxonomy_and_Data_Transparency_Standards_to_Support_Seller-defined_Audience_and_Context_Signaling_2021-03.pdf) standard. 54 | 55 | This is an extension for OpenRTB 2.x that describes where SSPs/exchanges should place these vendor-specific content IDs that they receive from publishers. DSPs who wish to consume these IDs should look for these in this extension. Additionally, SSPs/exchanges could act as a vendor for content IDs if desired -- for example, if they also act as the content management platform for publishers. 56 | 57 | # DEPRECATED as of OpenRTB 2.6-202504 Use `cids` [in Object: Data]([https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/develop/2.6.md#3221---object-data-)) in OpenRTB 58 | 59 | ## Specification 60 | 61 | In the “ext” object of the “data” object array of the “content’ object of OpenRTB 2.x bid requests: 62 | 63 | 64 | 65 | 66 | 68 | 70 | 72 | 73 | 74 | 76 | 78 | 80 | 81 |
    Field 67 | Type 69 | Description 71 |
    cids 75 | string array 77 | An array of content IDs, representing one or more identifiers for the video or audio content from the ID source specified in the “name” field of the “data” object. 79 |
    82 | 83 | 84 | Specifically **not** used is the existing “id” field in the “content” object, as this is known to conflict with internal uses of this field by publishers and exchanges, and does not provide for a way to communicate the source of the ID. 85 | 86 | In practice, it is expected that a typical request will have only one content ID from one source, however there are theoretically cases for multiple IDs, or multiple ID sources, and thus an array is used. 87 | 88 | # DEPRECATED as of OpenRTB 2.6-202504 Use `cids` [in Object: Data]([https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/develop/2.6.md#3221---object-data-)) in OpenRTB 89 | 90 | 91 | ### Identifying source 92 | 93 | The “data” object itself contains a “name” string field which shall be used to convey the domain of the content ID provider/source, expressed as “root domain” (public suffix list + 1, aka “[top private domain](https://github.com/google/guava/wiki/InternetDomainNameExplained#public-suffixes-and-private-domains)”). This is consistent with the [Seller-defined Audience and Context Signalling](https://iabtechlab.com/wp-content/uploads/2021/03/IABTechLab_Taxonomy_and_Data_Transparency_Standards_to_Support_Seller-defined_Audience_and_Context_Signaling_2021-03.pdf) standard, thus allowing for bid requests that contain both the actual content ID, as well as any seller-supplied categorizations. 94 | 95 | Providers/sources of content IDs shall decide on a root domain which they own and will consistently use to identify themselves. Typically, this should be the business or operational domain of the provider. If a publisher is passing its own content IDs which do not come from some metadata aggregator, it should likewise choose and consistently use a root domain that it owns as the way it identifies itself. 96 | 97 | It is not assumed that the content ID string or name string (representing ID source) has any meaning whatsoever to exchanges and DSPs. They need only pass it onwards to contextual vendors, who are responsible for making their own arrangements to source metadata from the content ID sources that their DSP partners will observe. It is also possible that DSPs could make arrangements with content data platforms themselves instead of sending to contextual vendors. 98 | 99 | # DEPRECATED as of OpenRTB 2.6-202504 Use `cids` [in Object: Data]([https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3227---object-eid-](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/develop/2.6.md#3221---object-data-)) in OpenRTB 100 | 101 | ### Example 102 | 103 | 104 | ``` 105 | { 106 | "site": { 107 | "content": { 108 | "data": [ 109 | { 110 | "name": "iris.tv", 111 | "ext": { 112 | "cids": [ 113 | "iris_c73g5jq96mwso4d8" 114 | ] 115 | } 116 | } 117 | ] 118 | } 119 | } 120 | } 121 | ``` 122 | 123 | 124 | 125 | ### Example - Content ID and Seller-Defined Context 126 | 127 | **NOTE:** Seller-Defined Context is out of scope of this extension, but this example is provided to show how this extension is aligned with, and can be used in tandem with seller-defined context. See [Segment Taxonomies community extension](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/segtax.md) and the IAB [Seller-defined Audience and Context Signalling](https://iabtechlab.com/wp-content/uploads/2021/03/IABTechLab_Taxonomy_and_Data_Transparency_Standards_to_Support_Seller-defined_Audience_and_Context_Signaling_2021-03.pdf) standard. 128 | 129 | 130 | ``` 131 | { 132 | "site": { 133 | "content": { 134 | "data": [ 135 | { 136 | "name": "iris.tv", 137 | "segment": [ 138 | { 139 | "id": "ic_5784065" 140 | }, 141 | { 142 | "id": "ic_5711828" 143 | } 144 | ], 145 | "ext": { 146 | "segtax": 501, 147 | "cids": [ 148 | "iris_c73g5jq96mwso4d8" 149 | ] 150 | } 151 | } 152 | ] 153 | } 154 | } 155 | } 156 | ``` 157 | -------------------------------------------------------------------------------- /extensions/community_extensions/gpid.md: -------------------------------------------------------------------------------- 1 | ### Global Placement Id(gpid) 2 | 3 | **Sponsor**: The Trade Desk 4 | 5 | **Background**: 6 | A global placement identifier (GPID) is a publisher-specified placement (tag) ID that is passed unchanged by all supply-side platforms (SSPs). 7 | In programmatic auctions, the OpenRTB TagId property of the Impression object traditionally contains an exchange-specific placement ID. No two exchanges share the same set of placement IDs. Now with header bidding, however, buyers can buy inventory from different sources, but the challenge is that they have no way of knowing which placement is being transacted in a given auction. The solution is to use GPIDs—a publisher specifies a GPID, exchanges propagate it, and buyers know exactly which placement is being transacted via all auctions for the impression. 8 | 9 | **Goal**: 10 | The Global Placement ID (GPID) was an initiative in the Fall of 2021 led by the TradeDesk which aims to give buyers a way to identify a given ad slot on a page across SSPs and header bidding integrations. 11 | 12 | ### Object: `Imp.ext.gpid` 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 |
    Attribute        Type                    Description
    gpidstringDistinct, persistent id for each ad unit on a page
    25 | 26 | ### Implementation notes 27 | While there is no single format for GPID syntax, it is important to keep GPIDs unique to each ad slot on the page, consistent in syntax, and informative, as placements are included in reporting and are used by sophisticated buyers for targeting. 28 | 29 | General Guidelines 30 | * Focus on the placement that is being sold. 31 | * Avoid including any information that that's already in another part of the bid request. For example, there is no need to include domain, ad format, seller, if it's a mobile placement, and so on. 32 | * Provide a descriptive, named placement rather than a numerical or alphanumerical one. 33 | * Use delimiters, preferably forward slashes (/). 34 | * Apply consistent formatting. 35 | 36 | IMPORTANT: If you choose to include additional information in a GPID, make sure that the placement portion can be easily identified and extracted in a consistent manner for all placements transacted. 37 | 38 | For ease of adoption, where applicable, a Google Ad Manager (GAM) or DoubleClick For Publishing (DFP) ad unit code alone can serve as an effective GPID. 39 | 40 | * If the ad unit code alone is sufficient to uniquely identify a placement, use it as a GPID 41 | * If the ad unit code alone is not sufficient to uniquely identify a placement, append the Div ID of the placement after its ad unit code to construct a GPID 42 | 43 | ### Getting to gpid using Ad Unit Code only 44 | 45 | Some publishers have unique and consistent GPIDs within ad unit codes. In these cases, there is no need to include Div IDs in GPIDs, as ad unit codes suffice. Here are some GPID examples constructed using only ad unit codes. 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 |
    Ad Unit Code Code        Example gpid
    123456/unique-placement-name123456/unique-placement-name
    57 | 58 | #### Example Request - Ad Unit Code only 59 | 60 | ``` 61 | { 62 | "imp": [{ 63 | "ext": { 64 | "gpid": "123456/unique-placement-name" 65 | } 66 | }] 67 | } 68 | ``` 69 | 70 | ### Using Ad Unit Codes and Div IDs as GPIDs 71 | 72 | For details on how publishers typically pass Div IDs to their respective SSPs and exchanges, see the [Prebid documentation](https://docs.prebid.org/features/pbAdSlot.html). 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 |
    Ad Unit Code        DIV ID                    gpid
    123456/example.com/homepageimage_top123456/example.com/homepage/image_top
    86 | 87 | #### Example Request - Ad Unit Codes and Div IDs 88 | 89 | ``` 90 | { 91 | "imp": [{ 92 | "ext": { 93 | "gpid": "123456/example.com/homepage/image_top" 94 | } 95 | }] 96 | } 97 | ``` 98 | -------------------------------------------------------------------------------- /extensions/community_extensions/ifa_type.md: -------------------------------------------------------------------------------- 1 | # IFA_TYPE 2 | **Sponsors:** 3 | 4 | Basis Technologies
    5 | Global
    6 | Unruly
    7 | Index Exchange
    8 | Undertone
    9 | Pulsepoint
    10 | OpenX
    11 | Triplelift
    12 | 13 | 14 | ## Overview 15 | The `ifa_type` field was originally introduced by IAB Tech Lab in:
    16 | [Guidelines for Identifier for Advertising (IFA) on CTV/OTT platforms](https://iabtechlab.com/wp-content/uploads/2018/12/OTT-IFA-guidelines.final_Dec2018.pdf) 17 | (Dec. 2018, updated Sept. 2020). 18 | 19 | It has been in use by a number of companies, and is frequently seen in OpenRTB requests. However, the need for such a field has evolved beyond CTV. 20 | An updated [proposal](https://docs.google.com/document/d/1ko5l88-sS-7HC7TZJW_BwvCAk9f7gzLsFXRp1QjHimM/edit) was presented to the Supply Chain Group in 2020. Since its original introduction in 2018, `ifa_type` has yet to be formally incorporated into OpenRTB. 21 | 22 | **Request Change** 23 | 24 | This extension provides a means to indicate the source of the ID passed in `device.ifa`, with the goal of formally adopting previous proposals for an attribute that has already been in use by the community for many years. 25 | 26 | ## Specification 27 | ### Bid Request 28 | #### Object: `device.ext` 29 | 30 | 31 | 32 | 35 | 38 | 41 | 42 | 43 | 44 | 45 | 48 | 51 | 54 | 55 | 56 |
    33 | Attribute 34 | 36 | Type 37 | 39 | Description 40 |
    46 | ifa_type 47 | 49 | string 50 | 52 | Declared source of the device.ifa provided in the bid request. Refer to List: IFA Types for values. 53 |
    57 | 58 | ### List: IFA Types 59 | 60 | This list identifies the source type of the IFA. 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 |
    ValueDefinition
    dpidDevice provided ID
    ppidPublisher provided ID
    sspidSSP provided ID
    sessionid1Session ID / Synthetic ID
    84 | 85 | *1sessionids are defined as IFAs with a more limited life span than standard user/device identifiers - and are intended for use within shorter time intervals.* 86 | 87 | **NOTE:** The following values from the original ifa_type proposal shall be considered deprecated: 88 | 89 | rida - Roku id
    90 | aaid - Android id
    91 | idfa - Apple id
    92 | afai - Amazon Fire id
    93 | msai - Microsoft id 94 | 95 | Implementers who wish to know this can infer it. When ifa_type = dpid, look to device information to then determine if it is a RIDA, IDFA, etc. 96 | 97 | ### Example 98 | ``` 99 | "device": { 100 | "devicetype": 3, 101 | "ifa": "75a6ab8d-4698-1234-1234-446fa01b5f62", 102 | "ext": { 103 | "ifa_type": "dpid" 104 | } 105 | ... 106 | ``` 107 | 108 | -------------------------------------------------------------------------------- /extensions/community_extensions/intrinsic-in-game.md: -------------------------------------------------------------------------------- 1 | ### Intrinsic in-game 2 | 3 | Sponsor: The Trade Desk 4 | 5 | **Background** 6 | 7 | As intrinsic in-game inventory picks up momentum from both the supply side and the buy side, it's important for there to be a signal to accurately identify this nuanced inventory. The IAB recognized the lack of standards in the space recently by establishing specific measurement guidelines in 2022 and this signal aims to further recognize this type of inventory as an established channel. 8 | 9 | **Goal** 10 | 11 | The goal of this signal is to have all SSP's correctly identify intrinsic in-game inventory in order for the DSP or other parties to segment this inventory accordingly. 12 | 13 | **Definition** 14 | 15 | Ad space that modifies the environment of a game, such as a billboard or skin. 16 | 17 | **Request Changes** 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 32 | 33 |
    Impression ObjectTypeExample valuesDescription
    imp.ext.intrinsicinteger0,1Indicates whether the inventory is intrinsic in-game, modifying the environment of the game, for instance through a billboard or skin. 31 |
    34 | 35 | Example Request 36 | 37 | ``` 38 | { 39 | "imp":{ 40 | "ext":{ 41 | "intrinsic": "1" ] 42 | } 43 | } 44 | } 45 | ``` 46 | 47 | -------------------------------------------------------------------------------- /extensions/community_extensions/per-imp-tids.md: -------------------------------------------------------------------------------- 1 | # Per-Impression Transactions IDs for Multi-Impression Bid Requests 2 | 3 | Issue: [#104](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/104) 4 | 5 | Sponsor: Index Exchange, Cafemedia 6 | 7 | ## Background 8 | 9 | OpenRTB bid requests support an array of impression objects, which may correspond to multiple discrete transactions, or all relate to 1 transaction. However, the 2.X spec only supports 1 transaction ID per request via the source.tid field. This community extension allows for specifying a transaction ID per item in the impression array, so that multiple transaction IDs can be transmitted in a single bid request. 10 | 11 | ## Request Changes 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 26 | 27 |
    Imp ObjectTypeExample valuesDescription
    imp.ext.tidstringe8348715-9221-4483-8615-3471ec0fb77bA string representing a transaction ID, which is expected to be common across all participants in 25 | this bid request (e.g., potentially multiple exchanges).
    28 | 29 | ## How To Use This Field 30 | 31 | ### If source.tid is NOT provided and imp.ext.tid IS 32 | The seller may either set the same `imp.ext.tid` across all items in the impression array (which is functionally equivalent to using `source.tid`). 33 | 34 | OR 35 | 36 | The seller may set a different `imp.ext.tid` for some/all items in the impression array. 37 | 38 | ### If BOTH source.tid and imp.ext.tid are provided 39 | `imp.ext.tid` should override, with `source.tid` used as a fallback for any items in the impression array that don't specify a `imp.ext.tid`. 40 | 41 | 42 | ## Example Request 43 | 44 | ``` 45 | { 46 | "imp": [ 47 | { 48 | "id": 1, 49 | "banner": { 50 | "w": 300, 51 | "h": 250 52 | }, 53 | "ext": { 54 | "tid": "e8348715-9221-4483-8615-3471ec0fb77b" 55 | } 56 | }, 57 | { 58 | "id": 2, 59 | "banner": { 60 | "w": 250, 61 | "h": 250 62 | }, 63 | "ext": { 64 | "tid": "678b925c-1abd-4651-abe2-806018eeffa9" 65 | } 66 | } 67 | ] 68 | ... 69 | } 70 | ``` 71 | -------------------------------------------------------------------------------- /extensions/community_extensions/pla.md: -------------------------------------------------------------------------------- 1 | # Executive Summary 2 | The Commerce Media Product Listing Ads use case is one that aligns with concepts already enabled by OpenRTB and native creative. However, it does have a few nuances that need acknowledgment within the programmatic ecosystem before trading commences. 3 | 4 | We’d highlight the following: 5 | * The most critical component to the transaction is the understanding of the product feed that is in use. In the current use case: no creative is provided by the buyer - the creative is understood and surfaced by the platform based on feed-specific product codes provided in the bid response. 6 | * Contextual requirements (allowed & blocked products and categories) are only understood through the feed. 7 | 8 | 9 | While the current use case fits best with Native creative type, this option remains creative agnostic, so as not to prevent future iterations. This solution focuses on the fact that the bid request cannot be responded to appropriately without the buyer understanding the product feed. Therefore, prodfeed is the central component to this solution. 10 | 11 | # Bid Request Object: Prodfeed 12 | In an effort to ensure bidders understand the requirements to participate in this auction as early as possible, AND to remain creative agnostic, we propose placing key details about the product feed in a new prodfeed object within bidrequest. 13 | 14 | This gives a clear, high level signal that special treatment of the request is required, and may help future proof creative use cases beyond the native spec (for example audio creative in a grocery store limited to the allowed products). Other similar fields already live in the top level ‘bidrequest’ object, such as acat, bcat. 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 |
    AttributeTypeDescription
    prodfeedobjectIf understanding of a product feed or catalog is required to bid on this opportunity, then use this object to declare required details.
    28 | 29 | ## Object: prodfeed 30 | Presence of this object indicates that the bid request can only be responded to appropriately if the buyer has an understanding of the product feed and product codes detailed in this object. 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 45 | 46 | 47 | 48 | 49 | 53 | 54 | 55 | 56 | 57 | 61 | 62 | 63 | 64 | 65 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 |
    AttributeTypeDescription
    idstringAn identifier uniquely identifying the product feed that pertains to the ad request.

    42 | If the feed owner maintains more than one product feed they may provide version specific details in this attribute.

    43 | It is expected that if a feedid is used, the use case has been implemented by the buyer a priori to the request. 44 |
    domainstringCanonical domain of the owner of the product feed related to the ad request.

    50 | Required if prodfeed parent object is present

    51 | It is expected that the product feed has been implemented by the buyer a priori to the request. 52 |
    aprodstring, arrayProduct codes from product feed that are eligible to serve.

    58 | Demand partners should only return products in their bid response included on this list.

    59 | Sellers should use aprod only for items that are not already contained in aprodcat 60 |
    bprodstring, arrayProduct codes from feeddomain or feedid product feed that are not are eligible to serve.

    66 | Demand partners should not return any product in their bid response included on this list.

    67 |
    aprodcatstring, arrayProduct categories from the product feed that are eligible to serve.
    bprodcatstring, arrayProduct categories from the product feed that are not eligible to display.

    79 | Sellers should use bprod only for items that are not already contained in bprodcat 80 |
    extobjectPlaceholder for vendor specific extensions to this object.
    89 | 90 | 91 | 92 | # Implementation Guidance 93 | Bidding on PLAs (Product Listing Ads) differs from most ad placements in that the creative assets are provided by the publisher. The buyer need only provide a product ID to signal the product to be displayed. The native spec has been leveraged for this, we are currently suggesting data type '13': Product ID, although it is not an official update to the Native Spec at this time, we hope with adoption of this ext to promote it over time. 94 | 95 | ## Bid Request 96 | ### Prodfeed Object 97 | At time of publication, no standard product feed specification exists, so attributes relating to products and categories are strings not IDs. Buyers must have some knowledge of the schema of any product feed they want to bid on a priori to the auction. 98 | 99 | This creates a significant risk for very large bids. Best efforts should be made by implementers to minimize the number of products and/or product categories 100 | 101 | It is assumed that some knowledge of the product feed and/or the product IDs within that feed are understood by the buying system. At the very least, the Product ID (SKU, GTIN, etc.) as signaled by the prodid attribute must be known so the buyer can return a bid. 102 | 103 | It is strongly recommended that the buying system have some understanding of how specific products are categorized within a given product feed to enable support foraprodcat and bprodcat and avoid sending bids for all possible Product IDs. 104 | 105 | Where possible, bids requests that allow an entire category of items to be bid on should avoid sending individual product ids (aprod) that are already in the category associated with `aprodcat` and not send any Product IDs already within that category individually. 106 | 107 | To prevent bloat in the ad request, the number of product ids and/or categories should be reasonably constrained to the smallest possible number of values. For example, if a user is on a category section of a retail or commerce website or application, it is reasonable to send only the allowed product category (aprodcat) for the page where the user is. 108 | 109 | ### Native Markup Request Object 110 | 111 | It is assumed that some knowledge of the product feed exists a priori to the bid request, but a mechanism is necessary to point to the Product Feed containing information about product being bid on is necessary. Requests for PLAs where the creative is provided by the publisher will require using a datatype of 13 in the Native Ads API Data Asset Type Object. 112 | 113 | The context attribute will have a value of ‘3’ (Product context such as product listings, details, recommendations, reviews, or similar.) 114 | 115 | ## Bid Response 116 | 117 | ### Native Markup Response Object 118 | PLAs will typically require the declaration of a product ID. 119 | The link object is required in the Native Ads API Response Object When bidding useing a product feed using the Product Feed enumeration of 13, in the Native Ads API Data Asset Type Object , it is acceptable to leave the ‘link.url’ field empty. 120 | 121 | # Examples 122 | 123 | ## Request: 124 | ```` 125 | { 126 | "id": "13423", 127 | "prodfeed": { 128 | "domain": "store.com", 129 | "bprod": ["sku1234", "sku1235"], 130 | "aprdodcat": ["abc"] 131 | }, 132 | "site": { 133 | "id": "123456", 134 | "publisher": { 135 | "id": "seller123" 136 | }, 137 | "cattax": "7", 138 | "cat": ["1123"], 139 | "domain": "store.com", 140 | "page": "https://store.com/search" 141 | }, 142 | "cattax": "7", 143 | "bcat": ["1000", "1001", "1002"], 144 | "imp": [{ 145 | "id": "1", 146 | "tagid": "IYAwpstnsVuJQTpdnzJkhIWq", 147 | "native": { 148 | "request": { 149 | "native": { 150 | "ver": "1.2", 151 | "context": 3, 152 | "plcmttype": 1, 153 | "plcmtcnt": 1, 154 | "assets": [{ 155 | "id": 1, 156 | "required": 1, 157 | "data":{ 158 | "type":13, 159 | } 160 | } 161 | ], 162 | } 163 | } 164 | }, 165 | "bidfloor": 0.9, 166 | "secure": 1 167 | } 168 | ], 169 | "tmax": 300, 170 | "at": 1 171 | } 172 | ```` 173 | 174 | ## Response: 175 | 176 | ```` 177 | { 178 | "id": "24711", 179 | "bidid": "6629493c000a958f04e60053", 180 | "seatbid": [{ 181 | "bid": [{ 182 | "id": "102", 183 | "price": 0.5131, 184 | "impid": "1", 185 | "burl": "http://example.com/billingnotice?p=${AUCTION_PRICE}&impid=1", 186 | "adm": "\"native\":{\"link\":{\"url\":\"\"},\"assets\":[{\"id\":1,\"required\":1,\"data\":{\"value\":\"sku123\"}}],"eventtrackers":[{"event":1,"method":2,"url":"http:tracker.com/track}]}" 187 | }, 188 | "adomain": ["brand.com"], 189 | "crid": "12345", 190 | "cid": "67890", 191 | "cattax": "7", 192 | "cat": ["1123"] 193 | } 194 | ], 195 | "seat": "12345" 196 | } 197 | ], 198 | "cur": "USD" 199 | } 200 | ```` 201 | -------------------------------------------------------------------------------- /extensions/community_extensions/seat-non-bid.md: -------------------------------------------------------------------------------- 1 | # Seat Non Bid Response 2 | 3 | Sponsors: Xandr, Magnite, CafeMedia, Media.net 4 | 5 | ## Overview 6 | 7 | There’s an ongoing effort in the industry for exchanges to provide publishers with insights into why seats do not bid. Insights include reasons why the exchange did not request a bid from a seat, why a seat did not bid, and why a bid was considered invalid. Publishers want to use this information to learn how to improve performance and increase efficiency. 8 | 9 | This proposal introduces an extension on the `BidResponse` object to enable each seat to provide a reason for not bidding, or for the exchange to provide a reason for not requesting a bid or rejecting a bid from a particular seat. 10 | 11 | ## Why Something New 12 | 13 | The OpenRTB 2.x `BidResponse` object defines the `nbr` field to provide one reason for not bidding. There's no structure defined to convey granular information when some seats bid and others do not. 14 | 15 | The `Bid` object cannot be extended for non bid scenarios since it constitutes an offer to buy an impression and requires a price. Similarly, the `SeatBid` object cannot be extended as it requires at least one `Bid`. 16 | 17 | ## Considerations 18 | 19 | Exchanges and publishers who do not wish to emit or act upon these insights may choose to ignore this extension. Exchanges may provide an option to publishers for including this level of detail. 20 | 21 | There are many reasons for a non bid scenario and it is understood not all can be included in a standardized enumeration. Exchanges may use 500+ values to define their own reason codes as appropriate. 22 | 23 | ## Specification 24 | 25 | ### Example Bid Response 26 | 27 | ``` 28 | { 29 | "id": "1234567890", 30 | "ext": { 31 | "seatnonbid": [{ 32 | "seat": "512", 33 | "nonbid": [{ 34 | "impid": "102", 35 | "statuscode": 301 36 | }] 37 | }] 38 | } 39 | } 40 | ``` 41 | 42 | ### Object: BidResponse 43 | 44 | 45 | 46 | 47 | 50 | 53 | 56 | 57 | 58 | 59 | 60 | 63 | 66 | 69 | 70 | 71 |
    48 | Attribute 49 | 51 | Type 52 | 54 | Description 55 |
    61 | ext.seatnonbid 62 | 64 | object array 65 | 67 | Optional array of SeatNonBid objects. 68 |
    72 | 73 | ### Object: SeatNonBid 74 | 75 | 76 | 77 | 78 | 81 | 84 | 87 | 88 | 89 | 90 | 91 | 94 | 97 | 101 | 102 | 103 | 106 | 109 | 112 | 113 | 114 | 117 | 120 | 123 | 124 | 125 |
    79 | Attribute 80 | 82 | Type 83 | 85 | Description 86 |
    92 | nonbid 93 | 95 | object array; required 96 | 98 | Array of 1+ NonBid objects each related to an impression. Multiple non bids may relate to the same 99 | impression. 100 |
    104 | seat 105 | 107 | string 108 | 110 | ID of the buyer seat (e.g., advertiser, agency) on whose behalf this bid is made. 111 |
    115 | ext 116 | 118 | object 119 | 121 | Placeholder for future extensions. 122 |
    126 | 127 | ### Object: NonBid 128 | 129 | 130 | 131 | 132 | 135 | 138 | 141 | 142 | 143 | 144 | 145 | 148 | 151 | 154 | 155 | 156 | 159 | 162 | 165 | 166 | 167 | 170 | 173 | 176 | 177 | 178 |
    133 | Attribute 134 | 136 | Type 137 | 139 | Description 140 |
    146 | impid 147 | 149 | string; required 150 | 152 | ID of the Imp object in the related bid request. 153 |
    157 | statuscode 158 | 160 | integer; required 161 | 163 | Reason for non bid. Refer to the Non Bid Status Codes list in this document. 164 |
    168 | ext 169 | 171 | object 172 | 174 | Placeholder for future extensions. 175 |
    179 | 180 | ### List: Non Bid Status Codes 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | 225 | 226 | 227 | 228 | 229 | 230 | 231 | 232 | 233 | 234 | 235 | 236 | 237 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255 | 256 | 257 | 258 | 259 | 260 | 261 | 262 | 263 | 264 | 265 | 266 | 267 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | 277 | 278 | 279 | 280 | 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 330 | 331 | 332 | 333 | 334 | 335 | 336 | 337 | 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | 347 | 348 | 349 | 350 | 351 | 352 | 353 | 354 | 355 |
    ValueDescription
    0No Bid - General
    1No Bid - Internal Technical Error
    2No Bid - Invalid Request
    3No Bid - Known Web Crawler
    4No Bid - Suspected Non-Human Traffic
    5No Bid - Cloud, Data Center, or Proxy IP
    6No Bid - Unsupported Device
    7No Bid - Blocked Publisher or Site
    8No Bid - Unmatched User
    9No Bid - Daily User Cap Met
    10No Bid - Daily Domain Cap Met
    11No Bid - Ads.txt Authorization Unavailable
    12No Bid - Ads.txt Authorization Violation
    13No Bid - Ads.cert Authentication Unavailable
    14No Bid - Ads.cert Authentication Violation
    15No Bid - Insufficient Auction Time
    16No Bid - Incomplete SupplyChain
    17No Bid - Blocked SupplyChain Node
    100Error - General
    101Error - Timeout
    102Error - Invalid Bid Response
    103Error - Bidder Unreachable
    200Request Blocked - General
    201Request Blocked - Unsupported Channel (app/site/dooh)
    202Request Blocked - Unsupported Media Type (banner/video/native/audio)
    203Request Blocked - Optimized
    204Request Blocked - Privacy
    300Response Rejected - General
    301Response Rejected - Below Floor
    302Response Rejected - Duplicate
    303Response Rejected - Category Mapping Invalid
    304Response Rejected - Below Deal Floor
    350Response Rejected - Invalid Creative
    351Response Rejected - Invalid Creative (Size Not Allowed)
    352Response Rejected - Invalid Creative (Not Secure)
    353Response Rejected - Invalid Creative (Incorrect Format)
    354Response Rejected - Invalid Creative (Malware)
    355Response Rejected - Invalid Creative (Advertiser Exclusions)
    356Response Rejected - Invalid Creative (Advertiser Blocked)
    357Response Rejected - Invalid Creative (Category Exclusion)
    500+Vendor-specific codes.
    356 | 357 | *Advertiser Exclusions vs Advertiser Blocked*: "Exclusion" refers to scenarios of competitive separation, while "Blocked" refers to publisher driven block lists. 358 | 359 | ## Non Bid Status Codes Guidance 360 | 361 | - Exchanges are encouraged to provide as much detail as possible, but it is acceptable to use the general codes (0, 100, 200, 300) when details aren't known. 362 | 363 | - The values 1-17 intentionally overlap with the OpenRTB 3.0 [No-Bid Reason Codes](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/OpenRTB%20v3.0%20FINAL.md#list--no-bid-reason-codes-) such that seats which provide a `nbr` can easily mapping to a `statuscode`. 364 | 365 | 366 | Non Bid Status Code values are purposefully organized into the following ranges to assist with high level classification: 367 | 368 | 369 | 370 | 371 | 372 | 373 | 374 | 375 | 376 | 377 | 378 | 379 | 380 | 381 | 382 | 383 | 384 | 385 | 386 | 387 | 388 | 389 | 390 | 391 | 392 | 393 | 394 | 396 | 397 | 398 | 399 | 400 | 401 | 402 | 403 | 404 |
    Range        Description                 InterpretationAction
    0-99No BidAuction ran successfully without demand for the impression.Seats with low demand may be re-evaluated or optimized.
    100-199ErrorTechnical problem occurred during the auction.Seat may need investigation to determine root cause.
    200-299Request RejectedImpression was explicitly not sent to the seat.Bid Request should be re-evaluated for unsupported impressions. May be expected due to exchange configuration. 395 |
    300-399Response RejectedSeat responded with a bid that was rejected by the exchange.Seat may need to resolve.
    -------------------------------------------------------------------------------- /extensions/community_extensions/segtax.md: -------------------------------------------------------------------------------- 1 | # Segment Taxonomies 2 | 3 | Sponsors: CafeMedia, Magnite (formerly Rubicon Project), PubMatic, Audigent 4 | 5 | ## Overview 6 | 7 | The goal of this change is to support publisher, proprietary, and standardized segments, with a simple structure that avoids significant repetitive text. This necessitates a means to communicate the applicable taxonomy which, in turn, necessitates a process for maintenance of the set of taxonomies. 8 | 9 | ## Request change 10 | 11 | This extension provides a means to qualify the Segment IDs in Data objects, specifying the taxonomy for those IDs. For backward compatibility, segment IDs should (still) be considered fully proprietary when no `segtax` is provided. 12 | 13 | ### Specification 14 | 15 | #### Object: `Data.ext`https://docs.prebid.org/features/firstPartyData.html 16 | 17 | Per the OpenRTB 2.x API, the Data and Segment objects together allow additional data about the related object (e.g., User, Content) to be specified. The Data object can appear in several places in an OpenRTB 2.x request, and the same extension is supported in all cases. 18 | 19 | 20 | 21 | 22 | 25 | 28 | 31 | 34 | 35 | 36 | 37 | 38 | 41 | 44 | 47 | 50 | 51 | 52 |
    23 | Attribute 24 | 26 | Description 27 | 29 | Type 30 | 32 | Example 33 |
    39 | segtax 40 | 42 | The ID for a taxonomy that is registered centrally, in a list maintained below. 43 | 45 | integer 46 | 48 | 3 49 |
    53 | 54 | #### Example 55 | 56 | The following example illustrates the usage of the new field in `BidRequest.user.data`, though the equivalent applies to other appearances of the same structure, e.g., in `BidRequest.app.content.data` and `BidRequest.site.content.data`. 57 | 58 | ``` 59 | { 60 | ..., 61 | "user": { 62 | "data": [ 63 | { 64 | "name": "a-data-provider.com", 65 | "ext": { 66 | "segtax": 3 67 | }, 68 | "segment": [ 69 | { "id": "1001" }, 70 | { "id": "1002" } 71 | ] 72 | } 73 | } 74 | } 75 | } 76 | ``` 77 | 78 | ### Taxonomies 79 | 80 | #### Process 81 | 82 | The aim of this process is to provide flexibility and quick turnaround on approvals without red tape (i.e., no dependency on IAB Tech Lab schedules or public comment periods): 83 | 84 | * This document is the official definition of the enumeration for vendor specific taxonomies. 85 | * The values for vendor specific taxonomies should be 500+ 86 | * Pull requests (PRs) can be submitted by anyone on an ongoing basis. 87 | * The approvers are jill@iabtechlab.com and/or hillary@iabtechlab.com and some other leaders on the Tech Lab Working Group if needed. 88 | * The PR submitter must notify the approvers of the PR submission. 89 | * The approvers will review for ID conflicts, and otherwise will approve the PR on the spot (i.e., no need for a formal Working Group review). 90 | 91 | #### Enumeration of Taxonomies 92 | 93 | ##### Standard Taxonomies 94 | Source : AdCOM [https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list_categorytaxonomies](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list_categorytaxonomies). 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 |
    ValueDescription
    1IAB Tech Lab Content Category Taxonomy 1.0. - Deprecated, and recommend NOT be used since it does not have SCD flags.
    2IAB Tech Lab Content Category Taxonomy 2.0: Deprecated, and recommend NOT be used since it does not have SCD flags.
    3 IAB Tech Lab Ad Product Taxonomy 1.0.
    4IAB Tech Lab Audience Taxonomy 1.1
    5IAB Tech Lab Content Taxonomy 2.1
    6IAB Tech Lab Content Taxonomy 2.2
    7IAB Tech Lab Content Taxonomy 3.0
    500+Vendor-specific codes.
    136 | 137 | 138 | ##### Approved Vendor specific Taxonomies 139 | 140 | 141 | 142 | 145 | 148 | 149 | 150 | 151 | 152 | 153 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | 225 | 226 | 227 | 228 | 229 | 230 | 231 | 232 | 233 | 234 | 235 | 236 | 237 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255 | 256 | 257 | 258 | 259 | 260 | 261 | 262 | 263 | 264 | 265 | 266 | 267 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | 277 | 278 | 279 | 280 | 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 330 | 331 | 332 | 333 | 334 | 335 | 336 | 337 | 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | 347 | 348 | 349 | 350 | 351 | 352 | 353 | 354 | 355 | 356 | 357 | 358 | 359 | 360 | 361 | 362 | 363 | 364 | 365 | 366 | 367 | 368 | 369 | 370 | 371 | 372 | 373 | 374 | 375 | 376 | 377 | 378 | 379 | 380 | 381 | 382 | 383 | 384 | 385 | 386 | 387 | 388 | 389 | 390 | 391 | 392 | 395 | 396 | 397 | 398 | 399 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 419 | 420 | 421 | 422 | 423 | 424 | 425 | 426 | 427 | 428 | 429 | 430 | 431 | 432 | 433 | 434 | 435 | 436 | 437 | 438 | 439 | 440 | 441 | 442 | 443 | 444 | 445 | 446 | 447 | 448 | 449 | 450 | 451 | 452 | 453 | 454 | 455 | 456 | 457 | 458 | 459 | 460 | 461 | 462 | 463 | 464 | 465 | 466 | 467 | 468 | 469 | 470 | 471 | 472 | 473 | 474 | 475 | 476 | 477 | 478 | 479 | 480 | 481 | 482 | 483 | 484 | 485 | 488 | 489 | 490 | 491 | 494 | 495 | 496 | 497 | 500 | 501 | 502 | 503 | 506 | 507 | 508 | 509 | 512 | 513 | 514 | 515 | 518 | 519 | 520 | 521 | 524 | 525 | 526 | 527 | 530 | 531 | 532 | 533 | 534 | 537 | 538 | 539 | 540 | 543 | 544 | 545 |
    143 | Value 144 | 146 | Description 147 |
    501 154 | IRIS.TV-enabled Video context taxonomy - More info - https://support.iris.tv 155 |
    502JW Player video content taxonomy
    503Akamai Data Activation Platform (DAP) - Buyer Defined Audiences (BDA), Scrambled
    504Akamai Data Activation Platform (DAP) - Buyer Defined Audiences (BDA), Encrypted TRUSTX Spectrum Custom Audiences
    505Akamai Data Activation Platform (DAP) - Custom Audiences, Reserved 1
    506Akamai Data Activation Platform (DAP) - Custom Audiences, Reserved 2
    507Magnite Custom Audiences
    508Magnite Standard Audiences
    5251plusX - Taxonomies
    5261plusX - Custom Audience Taxonomy
    5271plusX - Custom Content Taxonomy
    528 - 5391plusX - Custom Taxonomies Reserved range
    540AirGrid Custom Taxonomy
    541Captify Custom Taxonomy
    542Weborama Custom Taxonomy
    543Raptive Custom Audience Taxonomy
    544Raptive Custom Content Taxonomy
    545Ad Generation Custom Audience Taxonomy
    546Ad Generation Custom Content Taxonomy
    550Sirdata - Public Audience Taxonomy
    551Sirdata - Public Content Taxonomy
    552Sirdata - Private Audience Taxonomy (Equativ)
    553Sirdata - Private Content Taxonomy (Equativ)
    554Sirdata - Private Audience Taxonomy (DV360)
    555Sirdata - Private Content Taxonomy (DV360)
    556Sirdata - Private Audience Taxonomy (Index Exchange)
    557Sirdata - Private Content Taxonomy (Index Exchange)
    558Sirdata - Private Audience Taxonomy (Pubmatic)
    559Sirdata - Private Content Taxonomy (Pubmatic)
    560Sirdata - Private Audience Taxonomy (Magnite)
    561Sirdata - Private Content Taxonomy (Magnite)
    562Sirdata - Private Audience Taxonomy (Teads)
    563Sirdata - Private Content Taxonomy (Teads)
    564Sirdata - Private Audience Taxonomy (Yahoo!)
    565Sirdata - Private Content Taxonomy (Yahoo!)
    566Sirdata - Private Audience Taxonomy (Xandr)
    567Sirdata - Private Content Taxonomy (Xandr)
    568Sirdata - Private Audience Taxonomy (Criteo)
    569Sirdata - Private Content Taxonomy (Criteo)
    570Sirdata - Private Audience Taxonomy (Proxistore)
    571Sirdata - Private Content Taxonomy (Proxistore)
    572Sirdata - Private Audience Taxonomy (Mediasquare)
    573Sirdata - Private Content Taxonomy (Mediasquare)
    574Sirdata - Private Audience Taxonomy (E-novate)
    575Sirdata - Private Content Taxonomy (E-novate)
    576Sirdata - Private Audience Taxonomy (Triplelift)
    577Sirdata - Private Content Taxonomy (Triplelift)
    578Sirdata - Private Audience Taxonomy (Adform)
    579Sirdata - Private Content Taxonomy (Adform)
    580Sirdata - Private Audience Taxonomy (Unruly Media)
    581Sirdata - Private Content Taxonomy (Unruly Media)
    582Sirdata - Private Audience Taxonomy (Azerion / Improve Digital / Yield360)
    583Sirdata - Private Content Taxonomy (Azerion / Improve Digital / Yield360)
    584Sirdata - Private Audience Taxonomy (Smile Wanted)
    585Sirdata - Private Content Taxonomy (Smile Wanted)
    586-599Sirdata - Held for coming Private Audience & Content Taxonomies
    600Chromium Topics API taxonomy
    601Chromium Topics API Taxonomy V2
    602-609Held for future Chromium Topics API taxonomies
    700 393 | Groundtruth Taxonomies 394 |
    708Symitri Custom Audience Taxonomy
    709Symitri Standard Audience Taxonomy
    710-712Symitri Reserved Audience Taxonomy
    800NumberEight Audience Taxonomy
    900A1Media Audience Taxonomy
    1000Anonymised Custom Audience
    1001Anonymised Custom Audience Reserved 1
    1002Anonymised Custom Audience Reserved 2
    1003Anonymised Custom Audience Reserved 3
    2000Start.io Custom Audiences
    2001Start.io Standard Audiences
    3000Outbrain Audiences - Demographics
    3001Outbrain Audiences - Interests
    3002Outbrain Audiences - Household Income
    3003-3010Outbrain Audiences - Reserved
    5000Optable Data Collaboration Platform - Public Audiences
    5001Optable Data Collaboration Platform - Private Member Defined Audiences
    5002Optable Data Collaboration Platform - Test Audiences
    6000-6010Permutive Standard Audiences
    103000 486 | Audigent Warner Music Group Artists Taxonomy 1.0 487 |
    103001 492 | Audigent Bands in Town Artists Taxonomy 1.0 493 |
    103002 498 | Audigent Fandom Interests & Audiences Taxonomy 1.0 499 |
    103003 504 | Audigent Big Machine Label Group Artists Taxonomy 1.0 505 |
    103004 510 | Audigent Music Festival Partner Taxonomy 1.0 511 |
    103005 516 | Audigent Fashion & Apparel Taxonomy 1.0 517 |
    103006-103008 522 | Audigent Private Audience Taxonomies 523 |
    103009-103011 528 | Audigent Private Contextual Taxonomies 529 |
    103012-103014 535 | Audigent Campaign Taxonomies 536 |
    103015 541 | Rayn Persona Taxonomy 542 |
    546 | -------------------------------------------------------------------------------- /extensions/community_extensions/skadnetwork.md: -------------------------------------------------------------------------------- 1 | # SKAdNetwork 2 | 3 | Sponsors: MoPub, Chartboost, PubMatic, Digital Turbine (formerly Fyber), Magnite (formerly Rubicon Project) 4 | 5 | Document verison support: SKAdNetwork versions 2.0 to 4.0. Support for newer versions will be brought up for consideration within the IAB TL Programmatic working group subcommittee. 6 | 7 | ## Overview 8 | 9 | The IAB Tech Lab has introduced technical specifications aimed at adapting Apple’s [SKAdNetwork][1], a method for validating advertiser app installations, for programmatic ad buying. The OpenRTB object extensions, APIs and file formats described in this document together enable the advertising ecosystem to communicate and manage the information needed to use the SKAdNetwork capabilities in iOS 14 and above. 10 | 11 | The following are the updates provided in this document 12 | 1. A [SKAdNetwork extension][10] to support programmatic buying 13 | * Bid Request extension (`BidRequest.imp.ext.skadn`) 14 | * Bid Response extension (`BidResponse.seatbid.bid.ext.skadn`) 15 | 2. A [Device extension][11] (`BidRequest.device.ext`) to support IDFV and authorization status 16 | 3. [IABTL managed SKAdNetwork list][15] 17 | 4. Guidance for app developers to help [manage their Info.plists][12] and work with various SDKs. 18 | 19 | ## SKAdNetwork Extension 20 | 21 | ### Participant responsibilities 22 | 23 | The responsibilities of each participant when using the SKAdNetwork specifications are as follows. 24 | 25 | #### IABTL responsibilities are to: 26 | 1. Organize SKAdNetwork IDs as well as define an automated self-serve registration process 27 | - Will not validate the ID with Apple, but will verify that the domain matches the domain of the verified email address of the submitter. Will also provide an offline/non-automated process in case the email domain is different. 28 | - IABTL will lowercase all received SKAdNetwork IDs upon appending to the master list 29 | 2. Perform releases in batches at "x" cadence to ensure as many partners publishers have the most up-to-date lists 30 | - List should be in both JSON and XML formats to allow publishers to build to the IABTL list as well as other lists 31 | 3. Assign a permanent ID for each registered `SKAdNetwork ID` 32 | - Each registrant may have more than one `SKAdNetwork ID`. In this scenario, each `SKAdNetwork ID` will be assigned its own unique IABTL ID 33 | 4. Provide a tool for publishers to build their `Info.plist` files and express IABTL signaling from various URLs and / or raw SKAdNetwork ID (Tool available at https://tools.iabtechlab.com/skadnetwork) 34 | 35 | 36 | #### SSP/SDK responsibilities are to: 37 | 38 | 1. Provide publishers with access to their buying entities SKAdNetwork IDs through a publicly hosted lists on their own business domain 39 | 2. Support OpenRTB extension objects: `BidRequest.imp.ext.skadn` & `BidResponse.imp.ext.skadn` 40 | 3. Provide signed ads to the source app by calling `loadProduct()` with the appropriate data returned on the bid response 41 | 42 | #### DSP/intermediary/buying entities responsibilities are to: 43 | 44 | 1. Provide SKAdNetwork IDs to each supply partner and register on the IAB Tech Lab list at https://tools.iabtechlab.com/skadnetwork 45 | 2. Support OpenRTB extension objects: `BidRequest.imp.ext.skadn` & `BidResponse.imp.ext.skadn` 46 | 3. Determine if their entity is eligible for attribution postbacks 47 | 4. Return all necessary signed parameters to SSP/SDK to facilitate ad signatures and receive install validation postbacks at endpoint established during SKAdNetwork registration with Apple 48 | 49 | #### Publishers/source app’s responsibilities are to: 50 | 51 | 1. Add the ad network’s ID to its Info.plist in all lower case characters. 52 | 2. Update Info.plist with new entries added to the IAB Tech Lab / SSP / SDK publicly hosted lists when publishing new app versions to the App Store 53 | 3. Supply the supported `versions`, raw `skadnetids`, IABTL `max` and / or `excl` to the SSP / SDK on the device at runtime 54 | 55 | ### Regulatory Guidance 56 | 57 | OpenRTB implementations will need to ensure compliance on every transaction with all applicable regional legislation. 58 | 59 | ### Bid Request 60 | 61 | #### Object: `BidRequest.imp.ext.skadn` 62 | 63 | If a DSP has at least one SKAdNetworkItem in the publisher app’s `Info.plist` we would include a new object in the bid request that provides the necessary information to create a signature. Object would only be present if both the SSP SDK version and the OS version (iOS 14.0+) support SKAdNetwork. 64 | 65 | 66 | 67 | 68 | 71 | 74 | 77 | 80 | 81 | 82 | 83 | 84 | 87 | 90 | 93 | 96 | 97 | 98 | 101 | 104 | 107 | 110 | 111 | 112 | 115 | 118 | 121 | 124 | 125 | 126 | 129 | 132 | 135 | 138 | 139 | 140 | 143 | 146 | 149 | 155 | 156 | 157 | 160 | 163 | 166 | 169 | 170 | 171 | 174 | 177 | 180 | 183 | 184 | 185 | 188 | 191 | 194 | 197 | 198 | 199 |
    69 | Attribute 70 | 72 | Description 73 | 75 | Type 76 | 78 | Example 79 |
    85 | versions 86 | 88 | Array of strings containing the supported skadnetwork versions. Always "2.0" or higher. Dependent on both the OS version and the SDK version. 89 | 91 | array of strings 92 | 94 | "versions": ["2.0", "2.1", "2.2", "3.0", "4.0"] 95 |
    99 | version 100 | 102 | Version of skadnetwork supported. Always "2.0" or higher. Dependent on both the OS version and the SDK version.

    Note: With the release of SKAdNetwork 2.1, this field is deprecated in favor of the BidRequest.imp.ext.skadn.versions to support an array of version numbers. 103 |     		105 | string 106 | 108 | "version": "2.0" 109 |
    113 | sourceapp 114 | 116 | ID of publisher app in Apple’s App Store. Should match app.bundle in OpenRTB 2.x and app.storeid in AdCOM 1.x 117 | 119 | string 120 | 122 | "sourceapp": "880047117" 123 |
    127 | skadnetids 128 | 130 | A subset of SKAdNetworkItem entries in the publisher app’s Info.plist, expressed as lowercase strings, that are relevant to the bid request. Recommended that this list not exceed 10.

    Note:BidRequest.imp.ext.skadn.skadnetlist.addl is the preferred method to express raw SKAdNetwork IDs. 131 |     		133 | array of strings 134 | 136 | "skadnetids": ["cdkw7geqsh.skadnetwork", "qyjfv329m4.skadnetwork"] 137 |
    141 | skadnetlist 142 | 144 | Object containing the IABTL list definition 145 | 147 | object 148 | 150 | "skadnetlist": { 151 | "max":306, 152 | "excl":[2,8,10,55] 153 | } 154 |
    158 | productpage 159 | 161 | Custom Product Page support. See Apple's Custom Product Page doc for details. 162 | 164 | integer 165 | 167 | "productpage": 1 168 |
    172 | skoverlay 173 | 175 | SKOverlay support. If set, SKOverlay is supported. 176 | 178 | integer 179 | 181 | "skoverlay": 1 182 |
    186 | ext 187 | 189 | Placeholder for exchange-specific extensions to OpenRTB. 190 | 192 | object 193 | 195 | "ext": {} 196 |
    200 | 201 | 202 | 203 | #### Object: `BidRequest.imp.ext.skadn.skadnetlist` 204 | 205 | IABTL skadnetwork object list attributes. 206 | 207 | 208 | 209 | 210 | 213 | 216 | 219 | 222 | 223 | 224 | 225 | 226 | 229 | 234 | 237 | 240 | 241 | 242 | 245 | 248 | 251 | 254 | 255 | 256 | 259 | 262 | 265 | 268 | 269 | 270 | 273 | 276 | 279 | 282 | 283 | 284 |
    211 | Attribute 212 | 214 | Description 215 | 217 | Type 218 | 220 | Example 221 |
    227 | max 228 | 230 | IABTL list containing the max entry ID of SKAdNetwork ID. 231 | Format will be: 232 | "max entity ID" where 306 in the example on the right will be all SKAdNetwork IDs entry number 306 and below. 233 | 235 | integer 236 | 238 | "max":306 239 |
    243 | excl 244 | 246 | Comma separated list of integer IABTL registration IDs to be excluded from IABTL shared list. 247 | 249 | array of integers 250 | 252 | "excl": [44,14,18] 253 |
    257 | addl 258 | 260 | Comma separated list of string SKAdNetwork IDs, expressed as lowercase strings, not included in the IABTL shared list. The intention of addl is to be the permanent home for raw SKAdNetwork IDs, migrating away from BidRequest.imp.ext.skadn.skadnetids. Recommended that this list not exceed 10. 261 | 263 | array of strings 264 | 266 | "addl": ["cdkw7geqsh.skadnetwork", "qyjfv329m4.skadnetwork"] 267 |
    271 | ext 272 | 274 | Placeholder for exchange-specific extensions to OpenRTB. 275 | 277 | object 278 | 280 | "ext":{} 281 |
    285 | 286 | 287 | #### Example 288 | 289 | Used for direct SSP to DSP connections where a DSP wants to only consume their own relevant SKAdNetwork IDs. 290 | 291 | ``` 292 | { 293 | "imp": [ 294 | { 295 | "ext": { 296 | "skadn": { 297 | "versions": ["2.0", "2.1", "2.2", "3.0", "4.0"], 298 | "sourceapp": "880047117", 299 | "productpage": 1, 300 | "skadnetlist":{ 301 | "max":306, 302 | "excl":[2,8,10,55], 303 | "addl": [ 304 | "cdkw7geqsh.skadnetwork", 305 | "qyJfv329m4.skadnetwork" 306 | ] 307 | }, 308 | "skoverlay": 1 309 | } 310 | } 311 | } 312 | ] 313 | } 314 | ``` 315 | 316 | ### Bid Response 317 | 318 | If the bid request included the `BidRequest.imp.ext.skadn` object, then a DSP could choose to add the following object to their bid response. Please refer to Apple’s documentation for submitting the [correctly formatted values][4]. If the object is present in the response, then SSP would submit the click data and signature to [loadProduct()][7] for attribution. 319 | 320 | **Note:** Due to breaking changes introduced by Apple in SKAdNetwork v2.2 to support [View Through Attribution and fidelity-type][14], several structural changes to the bid response were required to support multiple fidelity types. 321 | 322 | #### Object: `BidResponse.seatbid.bid.ext.skadn` 323 | 324 | 325 | 326 | 327 | 330 | 333 | 336 | 339 | 340 | 341 | 342 | 343 | 346 | 349 | 352 | 355 | 356 | 357 | 360 | 363 | 366 | 369 | 370 | 371 | 374 | 377 | 380 | 383 | 384 | 385 | 388 | 391 | 394 | 397 | 398 | 399 | 402 | 405 | 408 | 411 | 412 | 413 | 416 | 419 | 422 | 425 | 426 | 427 | 430 | 433 | 436 | 446 | 447 | 448 | 451 | 456 | 459 | 462 | 463 | 464 | 467 | 470 | 473 | 476 | 477 | 478 | 481 | 486 | 489 | 492 | 493 | 494 | 497 | 504 | 507 | 510 | 511 | 512 | 515 | 518 | 521 | 524 | 525 | 526 | 529 | 532 | 535 | 538 | 539 | 540 |
    328 | Attribute 329 | 331 | Description 332 | 334 | Type 335 | 337 | Example 338 |
    344 | version 345 | 347 | Version of SKAdNetwork desired. Must be 2.0 or above. 348 | 350 | string 351 | 353 | "version": "4.0" 354 |
    358 | network 359 | 361 | Ad network identifier used in signature. Should match one of the items in the skadnetids array in the request 362 | 364 | string 365 | 367 | "network": "cdkw7geqsh.skadnetwork" 368 |
    372 | sourceidentifier 373 | 375 | A four-digit integer that ad networks define to represent the ad campaign. Used in SKAdNetwork 4.0+, replaces Campaign ID `campaign`. DSPs must generate signatures in 4.0+ using the Source Identifier. Please refer to the SKAdNetwork 4 release notes for more details. 376 | 378 | string 379 | 381 | "sourceidentifier": "4321" 382 |
    386 | campaign 387 | 389 | Campaign ID compatible with Apple’s spec. As of 2.0, should be an integer between 1 and 100, expressed as a string.

    Note: Used in SKAdNetwork 3.0 and below. Replaced by Source Identifier sourceidentifier in 4.0 and above 390 |     		392 | string 393 | 395 | "campaign": "45" 396 |
    400 | itunesitem 401 | 403 | ID of advertiser’s app in Apple’s app store. Should match BidResponse.seatbid.bid.bundle 404 | 406 | string 407 | 409 | "itunesitem": "123456789" 410 |
    414 | productpageid 415 | 417 | Custom Product Page ID (UUID) 418 | 420 | string 421 | 423 | "productpageid": "45812c9b-c296-43d3-c6a0-c5a02f74bf6e" 424 |
    428 | fidelities 429 | 431 | Supports multiple fidelity types introduced in SKAdNetwork v2.2 432 | 434 | object array 435 | 437 | "fidelities": [ 438 | { 439 | "fidelity": 0, 440 | "signature": "MEQCIEQlmZRNfYzK…", 441 | "nonce": "473b1a16…", 442 | "timestamp": "1594406341" 443 | } 444 | ] 445 |
    449 | nonce 450 | 452 | An id unique to each ad response. Refer to Apple’s documentation for the proper UUID format requirements 453 |

    454 | Note: With the release of SKAdNetwork v2.2, this field is deprecated in favor of the BidResponse.seatbid.bid.ext.skadn.fidelities.nonce to support multiple fidelity-types. 455 |     		457 | string 458 | 460 | "nonce": "473b1a16-b4ef-43ad-9591-fcf3aefa82a7" 461 |
    465 | sourceapp 466 | 468 | ID of publisher’s app in Apple’s app store. Should match BidRequest.imp.ext.skad.sourceapp 469 | 471 | string 472 | 474 | "sourceapp": "880047117" 475 |
    479 | timestamp 480 | 482 | Unix time in millis string used at the time of signature 483 |

    484 | Note: With the release of SKAdNetwork 2.2, this field is deprecated in favor of the BidResponse.seatbid.bid.ext.skadn.fidelities.timestamp to support multiple fidelity-types. 485 |     		487 | string 488 | 490 | "timestamp": "1594406341232" 491 |
    495 | signature 496 | 498 | SKAdNetwork signature as specified by Apple 499 |

    500 | Note: Apple requires that both the ad network nonce and ad network identifier be lowercase when signing for either fidelity type (impressions or clicks), as per SKAdNetwork specifications. 501 |

    502 | Note: With the release of SKAdNetwork 2.2, this field is deprecated in favor of the BidResponse.seatbid.bid.ext.skadn.fidelities.signature to support multiple fidelity-types. 503 |     		505 | string 506 | 508 | "signature": "MEQCIEQlmZRNfYzK…" 509 |
    513 | skoverlay 514 | 516 | SKOverlay support. 517 | 519 | object 520 | 522 | "skoverlay": {"delay": 5, "endcarddelay": 0, "dismissible": 0, "pos": 1} 523 |
    527 | ext 528 | 530 | Placeholder for exchange-specific extensions to OpenRTB. 531 | 533 | object 534 | 536 | "ext": {} 537 |
    541 | 542 | #### Object: `BidResponse.seatbid.bid.ext.skadn.fidelities` 543 | 544 | Fields that should have different values for the different fidelity types (e.g. `fidelity`, `nonce`, `signature`) are wrapped into an array of objects. 545 | 546 | **Note:** Adding `timestamp` to this list allows bidders to parallelize the cryptography portions of creating their bid response when supporting multiple fidelities. The same timestamp can be used across fidelities if desired but this move provides bidders with greater implementation flexiblity. 547 | 548 | 549 | 550 | 551 | 554 | 557 | 560 | 563 | 564 | 565 | 566 | 567 | 570 | 573 | 576 | 579 | 580 | 581 | 584 | 587 | 590 | 593 | 594 | 595 | 598 | 601 | 604 | 607 | 608 | 609 | 612 | 615 | 618 | 621 | 622 | 623 | 626 | 629 | 632 | 635 | 636 | 637 |
    552 | Attribute 553 | 555 | Description 556 | 558 | Type 559 | 561 | Example 562 |
    568 | fidelity 569 | 571 | The fidelity-type of the attribution to track 572 | 574 | integer 575 | 577 | "fidelity": 0 578 |
    582 | nonce 583 | 585 | An id unique to each ad response. Refer to Apple’s documentation for the proper UUID format requirements 586 | 588 | string 589 | 591 | "nonce": "473b1a16-b4ef-43ad-9591-fcf3aefa82a7" 592 |
    596 | timestamp 597 | 599 | Unix time in millis string used at the time of signature 600 | 602 | string 603 | 605 | "timestamp": "1594406341" 606 |
    610 | signature 611 | 613 | SKAdNetwork signature as specified by Apple 614 | 616 | string 617 | 619 | "signature": "MEQCIEQlmZRNfYzK…" 620 |
    624 | ext 625 | 627 | Placeholder for exchange-specific extensions to OpenRTB. 628 | 630 | object 631 | 633 | "ext": {} 634 |
    638 | 639 | 640 | **Note:** Apple also introduced `adtype`, `addescription`, and `adpurchasername` for fidelity-type 0 in v2.2. Until more clarity is provided by Apple about their use, these APIs have been intentionally omitted from the SKAdNetwork Extension. 641 | 642 | #### Object: `BidResponse.seatbid.bid.ext.skadn.skoverlay` 643 | 644 | Presents an [SKOverlay][17] StoreKit Ad during an ad experience using the `SKOverlay.AppConfiguration` Storekit API. 645 | 646 | 647 | 648 | 649 | 652 | 655 | 658 | 661 | 662 | 663 | 664 | 665 | 668 | 671 | 674 | 677 | 678 | 679 | 682 | 685 | 688 | 691 | 692 | 693 | 696 | 699 | 702 | 705 | 706 | 707 | 710 | 713 | 716 | 719 | 720 | 721 | 724 | 727 | 730 | 733 | 734 | 735 |
    650 | Attribute 651 | 653 | Description 654 | 656 | Type 657 | 659 | Example 660 |
    666 | delay 667 | 669 | Delay before presenting the SKOverlay in seconds. If set to 0, the overlay will be shown immediately. If this field is not set, the overlay will not be shown. 670 | 672 | integer 673 | 675 | "delay": 0 676 |
    680 | endcarddelay 681 | 683 | Delay before presenting the SKOverlay on an endcard in seconds. If set to 0, the overlay will be shown immediately. If this field is not set, the overlay will not be shown. 684 | 686 | integer 687 | 689 | "endcarddelay": 0 690 |
    694 | dismissible 695 | 697 | Whether the overlay can be dismissed by the user, where 0 = no, 1 = yes 698 | 700 | integer 701 | 703 | "dismissible": 0 704 |
    708 | pos 709 | 711 | Position of the Overlay. 0 = bottom, 1 = bottomRaised 712 | 714 | integer 715 | 717 | "pos": 1 718 |
    722 | ext 723 | 725 | Placeholder for exchange-specific extensions to OpenRTB. 726 | 728 | object 729 | 731 | "ext": {} 732 |
    736 | 737 | #### Example v4.0 738 | 739 | ``` 740 | { 741 | "seatbid": [ 742 | { 743 | "bid": [ 744 | { 745 | "ext": { 746 | "skadn": { 747 | "version": "4.0", 748 | "network": "cdkw7geqsh.skadnetwork", 749 | "sourceidentifier": "4321", 750 | "itunesitem": "123456789", 751 | "sourceapp": "880047117", 752 | "productpageid": "45812c9b-c296-43d3-c6a0-c5a02f74bf6e", 753 | "fidelities": [ 754 | { 755 | "fidelity": 0, 756 | "signature": "MEQCIEQlmZRNfYzKBSE8QnhLTIHZZZWCFgZpRqRxHss65KoFAiAJgJKjdrWdkLUOCCjuEx2RmFS7daRzSVZRVZ8RyMyUXg==", 757 | "nonce": "473b1a16-b4ef-43ad-9591-fcf3aefa82a7", 758 | "timestamp": "1594406341" 759 | }, 760 | { 761 | "fidelity": 1, 762 | "signature": "GRlMDktMmE5Zi00ZGMzLWE0ZDEtNTQ0YzQwMmU5MDk1IiwKICAgICAgICAgICAgICAgICAgInRpbWVzdGTk0NDA2MzQyIg==", 763 | "nonce": "e650de09-2a9f-4dc3-a4d1-544c402e9095", 764 | "timestamp": "1594406342" 765 | } 766 | ], 767 | "skoverlay":{ 768 | "delay": 5, 769 | "endcarddelay": 0, 770 | "dismissible": 1, 771 | "pos": 1 772 | } 773 | } 774 | } 775 | } 776 | ] 777 | } 778 | ] 779 | } 780 | ``` 781 | 782 | #### Example v2.2 783 | 784 | ``` 785 | { 786 | "seatbid": [ 787 | { 788 | "bid": [ 789 | { 790 | "ext": { 791 | "skadn": { 792 | "version": "2.2", 793 | "network": "cdkw7geqsh.skadnetwork", 794 | "campaign": "45", 795 | "itunesitem": "123456789", 796 | "sourceapp": "880047117", 797 | "productpageid": "45812c9b-c296-43d3-c6a0-c5a02f74bf6e", 798 | "fidelities": [ 799 | { 800 | "fidelity": 0, 801 | "signature": "MEQCIEQlmZRNfYzKBSE8QnhLTIHZZZWCFgZpRqRxHss65KoFAiAJgJKjdrWdkLUOCCjuEx2RmFS7daRzSVZRVZ8RyMyUXg==", 802 | "nonce": "473b1a16-b4ef-43ad-9591-fcf3aefa82a7", 803 | "timestamp": "1594406341" 804 | }, 805 | { 806 | "fidelity": 1, 807 | "signature": "GRlMDktMmE5Zi00ZGMzLWE0ZDEtNTQ0YzQwMmU5MDk1IiwKICAgICAgICAgICAgICAgICAgInRpbWVzdGTk0NDA2MzQyIg==", 808 | "nonce": "e650de09-2a9f-4dc3-a4d1-544c402e9095", 809 | "timestamp": "1594406342" 810 | } 811 | ] 812 | } 813 | } 814 | } 815 | ] 816 | } 817 | ] 818 | } 819 | ``` 820 | 821 | #### Example v2.0 822 | 823 | ``` 824 | { 825 | "seatbid": [ 826 | { 827 | "bid": [ 828 | { 829 | "ext": { 830 | "skadn": { 831 | "version": "2.0", 832 | "network": "cdkw7geqsh.skadnetwork", 833 | "campaign": "45", 834 | "itunesitem": "123456789", 835 | "nonce": "473b1a16-b4ef-43ad-9591-fcf3aefa82a7", 836 | "sourceapp": "880047117", 837 | "timestamp": "1594406341232", 838 | "signature": "MEQCIEQlmZRNfYzKBSE8QnhLTIHZZZWCFgZpRqRxHss65KoFAiAJgJKjdrWdkLUOCCjuEx2RmFS7daRzSVZRVZ8RyMyUXg==" 839 | } 840 | } 841 | } 842 | ] 843 | } 844 | ] 845 | } 846 | ``` 847 | 848 | ### Loss Reason Code 849 | 850 | Bid responses that contain invalid or malformed SKAdNetwork extensions may be rejected. This rejection can be communicated in loss notifications (lurl) using [Loss Reason Code][16] `214`. 851 | 852 | 853 | 854 | 855 | 856 | 857 | 858 | 859 | 860 | 861 |
    ValueDefinition
    214Creative Filtered - Invalid SKAdNetwork
    862 | 863 | ### SKAdNetwork Support Flow 864 | 865 | ![iOS 14 SKAdNetwork Flowchart][3] 866 | 867 | _Flow diagram of SSP SDK’s SKAdNetwork support. Objects in blue have a change required to pre-iOS-14 ad flows._ 868 | 869 | 1. SSP SDK retrieves the SKAdNetworkItems from the publisher app’s Info.plist 870 | 2. SDK makes ad request to ad server including SKAdNetworkItems 871 | 3. SSP determines from Info.plist which DSPs have SKAdNetwork capabilities. Bid request to eligible DSPs includes the imp.ext.skadn object, defined above 872 | 4. DSP responds, including `BidResponse.seatbid.bid.ext.skadn` if the campaign requires SKAdNetwork support 873 | 5. Ad response to SDK includes `skadn` object 874 | 6. If the impression is shown and the user clicks, SSP calls `loadProduct()` with the appropriate data, including the DSP-signed signature. If valid, Apple will consider the app for install attribution 875 | 7. Target app must register that user for SKAdNetwork attribution on app launch. 876 | 8. (Optional). Target app can choose to provide an additional 6 bits of conversion value information. 877 | 9. If SKAdNetwork determines that the DSP’s click led to the install, Apple will send a postback to the DSP’s registered endpoint with the ids of the source app, target app and campaign, and conversion value if provided by the target app. 878 | 879 | ## Device Extension 880 | 881 | ### Bid request 882 | 883 | #### Object: `BidRequest.device.ext` 884 | 885 | If the IDFA is not available, DSPs require an alternative, limited-scope identifier in order to provide basic frequency capping functionality to advertisers. The [IDFV][5] is the same for apps from the same vendor but different across vendors. Please refer to Apple's Guidelines for further information about when it can be accessed and used. 886 | 887 | DSPs may also want to understand what is the status of a user on iOS 14+. The `atts` field will pass the AppTrackingTransparency Framework's [authorization status][6]. 888 | 889 | 890 | 891 | 892 | 895 | 898 | 901 | 904 | 905 | 906 | 907 | 908 | 911 | 918 | 921 | 924 | 925 | 926 | 929 | 932 | 935 | 938 | 939 | 940 |
    893 | Attribute 894 | 896 | Description 897 | 899 | Type 900 | 902 | Example 903 |
    909 | atts 910 | 912 | (iOS Only) An integer passed to represent the app's app tracking authorization status, where
    913 | 0 = not determined
    914 | 1 = restricted
    915 | 2 = denied
    916 | 3 = authorized 917 |     		919 | integer 920 | 922 | "atts": 3 923 |
    927 | ifv 928 | 930 | IDFV of the device in that publisher. Listed as ifv to match ifa field format. 931 | 933 | string 934 | 936 | "ifv": "336F2BC0-245B-4242-8029-83762AB47B15" 937 |
    941 | 942 | #### Example 943 | 944 | ``` 945 | { 946 | "device": { 947 | "ext": { 948 | "atts": 2, 949 | "ifv": "336F2BC0-245B-4242-8029-83762AB47B15" 950 | } 951 | } 952 | } 953 | ``` 954 | 955 | ### DNT, LMT and App Tracking Transparency Guidance 956 | 957 | (Pending iOS 14 Golden Master) For iOS 14 and above, the 'DNT' and 'LMT' parameters will be informed by the 'ATTS' status, where 958 | * "DNT" or "LMT" = 1 when "ATTS" = 0, 1, 2 959 | * "LMT" or "DNT" = 0 when "ATTS" = 3 960 | 961 | 962 | ## IABTL managed SKAdnetwork ID list 963 | 964 | The IABTL managed list of SKAdNetwork IDs is available at https://tools.iabtechlab.com/skadnetwork, and is intended to address the communication of large lists across complex programmatic supply chains where the use of `skadnetids` is not feasible. 965 | * IABTL SKAdNetwork ID List is used to transmit a range of IDs supported by an IAB Tech Lab SKAdNetwork ID List up to the max ID. This list would serve a similar purpose that the TCF 2.0 [Global Vendor List][8] serves to identify common IDs in a compact range. Primary use case is "intermediary" SSP to SSP to DSP integrations where sending a subset of IDs is not feasible. 966 | 967 | 968 | "IABTL SKAdNetwork ID List" is a common list of networks, DSPs, Advertisers and others who support Apple’s SKAdNetwork API. This list would serve a similar purpose that the TCF 2.0 [Global Vendor List][8] serves to identify common IDs in a compact range. It can be used in addition to the distributed lists supplied by SSPs and Networks or in place of those. 969 | 970 | In the IABTL list model, the total list of SKAdNetworks on a device should be the union of the IABTL list and raw SKAdNetworks IDs supplied in the bid stream minus those in the exclude list 971 | 972 | 973 | ### IABTL SKAdNetwork ID Format 974 | 975 | This list would use the same format as the [SKANetwork ID Lists for App Developers][9] with the possible addition of an "id" field for the JSON metadata that would autoincrement for each added SKAdNetwork ID. The details of how this list would be maintained (pull requests / submission, who would check and approve etc) are yet to be determined. We would like to first get feedback on the need for (and arguments against) such a centralized list. 976 | 977 | #### Example 978 | 979 | 980 | ``` 981 | { 982 | "company_name": "IAB Tech Lab", 983 | "company_address": "116 East 27th Street, 7th Floor, New York, New York 10016", 984 | "company_domain": "iabtechlab.com", 985 | "skadnetwork_ids": [ 986 | { 987 | "id": 1, 988 | "entity_name": "DSP1", 989 | "entity_domain": "DSP1.com", 990 | "skadnetwork_id": "4fzdc2evr5.skadnetwork", 991 | "creation_date": "2020-08-21T00:00:00Z" 992 | }, 993 | { 994 | "id": 2, 995 | "entity_domain": "MMP1.com", 996 | "skadnetwork_id": "v72qych5uu.skadnetwork", 997 | "creation_date": "2020-08-25T00:00:00Z" 998 | } 999 | ] 1000 | } 1001 | ``` 1002 | 1003 | 1004 | ## SKAdNetwork ID Lists for App Developers 1005 | 1006 | SKAdNetwork ID Lists is a list of SKAdNetwork IDs published by a hosting company (e.g. SSP/SDK). App developers who work with the hosting company should use this file when generating a consolidated list of SKAdNetwork IDs to include in their app’s Info.plist file. For convenience, the SKAdNetwork IDs are provided in both XML and JSON formats. See each format for details and use cases. 1007 | 1008 |
    1009 | Warning: SKAdNetwork IDs should be stored on the device (in info.plist) as lowercase even if received in upper case or mixed case characters. Failure to do so can result in postbacks to not occur, potentially causing a loss in revenue as advertiers shift spend away from inventory that does not result in any attribution. 1010 |
    1011 | 1012 | ### URL Path 1013 | 1014 | Hosting companies should publish the SKAdNetwork ID files at the following locations: 1015 | * domain.com/skadnetworkids.xml 1016 | * domain.com/skadnetworkids.json 1017 | 1018 | If the server response indicates an HTTP/HTTPS redirect (301, 302, 307 status codes), entities 1019 | should follow the redirect and consume the data as authoritative for the source of the redirect. Multiple redirects are valid. 1020 | 1021 | ### skadnetworkids.xml 1022 | 1023 | The XML uses Apple’s Info.plist format. This provides developers with SKAdNetwork IDs in the exact SKAdNetworkItems array format for easy copy/paste into their Info.plist file. 1024 | 1025 | #### File Format 1026 | 1027 | All data in the file is serialized using XML (Extensible Markup Language) 1028 | 1029 | #### Objects 1030 | 1031 | Please refer to [Apple documentation][2] for details. 1032 | 1033 | #### Example 1034 | 1035 | ``` 1036 | 1037 | 1038 | 1039 | 1040 | SKAdNetworkItems 1041 | 1042 | 1043 | SKAdNetworkIdentifier 1044 | 4dzt52r2t5.skadnetwork 1045 | 1046 | 1047 | SKAdNetworkIdentifier 1048 | bvpn9ufa9b.skadnetwork 1049 | 1050 | 1051 | 1052 | 1053 | ``` 1054 | 1055 | ### skadnetworkids.json 1056 | 1057 | The JSON provides developers with additional metadata about the SKAdNetwork IDs that they will add to the Info.plist SKAdNetworkItems array. Helpful data like the entity name will ensure app developers know who the owners of each SKAdNetwork ID. 1058 | 1059 | #### File Format 1060 | 1061 | All data in the file is serialized using JSON (JavaScript Object Notation) 1062 | 1063 | #### Objects 1064 | 1065 | ##### Object: Parent top-level object 1066 | 1067 | 1068 | 1069 | 1070 | 1073 | 1076 | 1079 | 1082 | 1083 | 1084 | 1085 | 1086 | 1089 | 1092 | 1095 | 1098 | 1099 | 1100 | 1103 | 1106 | 1109 | 1112 | 1113 | 1114 | 1117 | 1120 | 1123 | 1126 | 1127 | 1128 | 1131 | 1134 | 1137 | 1140 | 1141 | 1142 |
    1071 | Attribute 1072 | 1074 | Description 1075 | 1077 | Type 1078 | 1080 | Example 1081 |
    1087 | company_name 1088 | 1090 | Name describing the hosting company 1091 | 1093 | string (recommended) 1094 | 1096 | SSP 1097 |
    1101 | company_address 1102 | 1104 | The business address of the hosting company 1105 | 1107 | string 1108 | 1110 | SSP, 1234 Advertising Lane, San Francisco, CA 94121 1111 |
    1115 | company_domain 1116 | 1118 | The business website of the hosting company 1119 | 1121 | string (required) 1122 | 1124 | company.com 1125 |
    1129 | skadnetwork_ids 1130 | 1132 | List of SKAdNetwork IDs 1133 | 1135 | object array (required) 1136 | 1138 | [{ "entity_name": "DSP1", "entity_domain": "DSP1.com", "skadnetwork_id": "4fzdc2evr5.skadnetwork", "creation_date": "2020-08-21T00:00:00Z" }] 1139 |
    1143 | 1144 | ##### Object: skadnetwork_ids 1145 | 1146 | 1147 | 1148 | 1149 | 1152 | 1155 | 1158 | 1161 | 1162 | 1163 | 1164 | 1165 | 1168 | 1171 | 1174 | 1177 | 1178 | 1179 | 1182 | 1185 | 1188 | 1191 | 1192 | 1193 | 1196 | 1199 | 1202 | 1205 | 1206 | 1207 | 1210 | 1213 | 1216 | 1219 | 1220 | 1221 |
    1150 | Attribute 1151 | 1153 | Description 1154 | 1156 | Type 1157 | 1159 | Example 1160 |
    1166 | entity_name 1167 | 1169 | Name of entity with SKAdNetwork ID 1170 | 1172 | string (recommended) 1173 | 1175 | DSP Name 1176 |
    1180 | entity_domain 1181 | 1183 | Domain of the entity with SKAdNetwork ID. For joint SKAdNetwork ID, entity owning Apple Developer account should be listed (this field may not be unique) 1184 | 1186 | string (recommended) 1187 | 1189 | DSP.com 1190 |
    1194 | skadnetwork_id 1195 | 1197 | SKAdNetwork ad network ID (this field should be unique) 1198 | 1200 | string (required) 1201 | 1203 | 4gwi8v3kwu.skadnetwork 1204 |
    1208 | creation_date 1209 | 1211 | Date entity(s) added to JSON file 1212 | 1214 | String in ISO 8601 (YYYY-MM-DDThh:mm:ssZ) 1215 | 1217 | 2020-08-21T00:00:00Z 1218 |
    1222 | 1223 | #### Example 1224 | 1225 | ``` 1226 | { 1227 | "company_name": "SSP", 1228 | "company_address": "SSP, address, country", 1229 | "company_domain": "company.com", 1230 | "skadnetwork_ids": [ 1231 | { 1232 | "entity_name": "DSP1", 1233 | "entity_domain": "DSP1.com", 1234 | "skadnetwork_id": "4fzdc2evr5.skadnetwork", 1235 | "creation_date": "2020-08-21T00:00:00Z" 1236 | }, 1237 | { 1238 | "entity_name": "MMP1", 1239 | "entity_domain": "MMP1.com", 1240 | "skadnetwork_id": "v72qych5uu.skadnetwork", 1241 | "creation_date": "2020-08-25T00:00:00Z" 1242 | } 1243 | ] 1244 | } 1245 | ``` 1246 | 1247 | ### SDK Guidance 1248 | 1249 | SDKs and/or app developers are encouraged to develop scripts to automate the process of retrieving the SKAdNetwork IDs from each SDK partner by parsing either the XML or JSON files to generate a complete list of IDs for their app’s Info.plist file. To aid in that process of ID retrieval from each SDK partner, include a file in your SDK named SKAdNetworks (with no extension), with each line in the file pointing to a publicly available SKAdNetworks.xml or SKAdNetworks.json. 1250 | 1251 | #### Example 1252 | 1253 | ``` 1254 | https://domain.com/skadnetworks.xml 1255 | https://domain.com/skadnetworks.json 1256 | ``` 1257 | 1258 | ## Changelog 1259 | 1260 | * **[11/11/2023]** 1261 | * Added support for SKOverlay in the Bid Request and Bid Response. 1262 | * **[11/16/2022]** 1263 | * Updated for v4.0 1264 | * Added `sourceidentifier` string to support SKAdNetwork 4.0 in the Bid Response. 1265 | * Deprecated `campaign`, use `sourceidentifier` in 4.0 1266 | * Added updated examples for 4.0 in Bid Request and Bid Response examples. 1267 | * **[10/19/2022]** 1268 | * Added `productpage` for Bid Requests and `productpageid` for Bid Responses to support Apple's Custom Product Page 1269 | * **[03/01/2021]** 1270 | * Updated for v2.2 1271 | * Added `fidelities` object array to support multiple fidelity types in the Bid Response. 1272 | * `signature`, `nonce` and `timestamp` moved to `fidelities` and deprecated root `skadn` versions of the values. 1273 | * Added `fidelity` within `fidelities` 1274 | * Removed Version Compatibility since IABTL approved of that proposal. 1275 | * **[02/01/2021]** 1276 | * Updated for v2.1 1277 | * Added `versions` for Bid Requests and deprecated `version` 1278 | * Add guidance for lowercasing values based on Apple clarifications 1279 | * **[11/02/2020]** 1280 | * Added `skadnetlist` 1281 | * **[09/16/2020]** 1282 | * Original release for public comment 1283 | 1284 | 1285 | 1286 | [1]: https://developer.apple.com/documentation/storekit/skadnetwork 1287 | [2]: https://developer.apple.com/documentation/storekit/skadnetwork/configuring_the_participating_apps 1288 | [3]: https://d2al1opqne3nsh.cloudfront.net/images/skadnetwork-flow@2x.png 1289 | [4]: https://developer.apple.com/documentation/storekit/skadnetwork/generating_the_signature_to_validate_an_installation 1290 | [5]: https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor 1291 | [6]: https://developer.apple.com/documentation/apptrackingtransparency/attrackingmanager/authorizationstatus 1292 | [7]: https://developer.apple.com/documentation/storekit/skstoreproductviewcontroller/1620632-loadproduct 1293 | [8]: https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/ 1294 | [9]: #skadnetwork-id-lists-for-app-developers 1295 | [10]: #skadnetwork-extension 1296 | [11]: #device-extension 1297 | [12]: #skadnetwork-id-lists-for-app-developers 1298 | [13]: #proposals-for-large-skadnetwork-id-list-management 1299 | [14]: https://developer.apple.com/documentation/storekit/skadnetwork/generating_the_signature_to_validate_view-through_ads 1300 | [15]: #IABTL-managed-SKAdnetwork-ID-list 1301 | [16]: https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/OpenRTB%20v3.0%20FINAL.md#list--loss-reason-codes- 1302 | [17]: https://developer.apple.com/documentation/storekit/skoverlay 1303 | -------------------------------------------------------------------------------- /extensions/community_extensions/urls-brand-safety.md: -------------------------------------------------------------------------------- 1 | ### URLs for Brand Safety 2 | 3 | Issue: [#39](https://github.com/InteractiveAdvertisingBureau/openrtb/issues/39) 4 | 5 | Sponsor: Flipboard 6 | 7 | The goal is to support brand safety in feed type environments where ads may appear between links (or previews) of various other pieces of content. 8 | 9 | Request Changes 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 24 | 25 |
    Content ObjectTypeExample valuesDescription
    content.ext.feedurlsstring array{ }An array of URLs of content that are _directly_ adjacent to the ad placement, for buy-side contextualization or review. For example, in a typical vertical feed, there would be 2 URLs provided as adjacent to the ad (above & below). In a 9-tile example, there would be 8 URLs provided.
    23 | Note : the URL to the main page (in which the feed and the ad appear) in the case of web content should be provided in the content.url field.
    26 | 27 | Example Request 28 | 29 | ``` 30 | { 31 | "content":{ 32 | "ext":{ 33 | "feedurls": [ "https://www.puba.com/content1.html", "https://www.pubb.com/content2", "https://www.pubc.com/content3/abc" ] 34 | } 35 | } 36 | } 37 | ``` 38 | -------------------------------------------------------------------------------- /extensions/extensions.xmind: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/InteractiveAdvertisingBureau/openrtb/7f8b96a1860dea3680137c8f1042eefd5ba1b27e/extensions/extensions.xmind -------------------------------------------------------------------------------- /extensions/extensions_lifecycle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/InteractiveAdvertisingBureau/openrtb/7f8b96a1860dea3680137c8f1042eefd5ba1b27e/extensions/extensions_lifecycle.png -------------------------------------------------------------------------------- /supplychainobject.md: -------------------------------------------------------------------------------- 1 | # OpenRTB SupplyChain object 2 | 3 | 4 | ## Abstract 5 | 6 | As part of a broader effort to eliminate the ability to profit from invalid traffic, ad fraud, and counterfeit inventory in the open digital advertising ecosystem, the SupplyChain object enables buyers to see all parties who are selling or reselling a given bid request. This extension object can be used with OpenRTB 2.5. It was officially added to the source object for OpenRTB 2.6 and 3.0. 7 | 8 | 9 | ## Introduction 10 | 11 | Ads.txt has been extremely successful in allowing publishers and app makers to define who is authorized to sell a given set of impressions via the programmatic marketplace. Ads.txt does not however make any attempt at revealing or authorizing all parties that are part of the transacting of those impressions. This information can be important to buyers for a number of reasons including transparency of the supply chain, ensuring that all intermediaries are entities with which the buyer wants to transact and that inventory is purchased as directly as possible. The implementation should be as transparent as possible to buyers. It should enable them to easily understand who it is that is participating in the sale of any piece of inventory. 12 | 13 | 14 | ## Implementation 15 | 16 | The SupplyChain object is composed primarily of a set of nodes where each node represents a specific entity that participates in the transacting of inventory. The entire chain of nodes from beginning to end represents all entities who are involved in the direct flow of payment for inventory. Future versions of the specification may also include entities who are involved in the transaction but are not involved in payment. 17 | 18 | 19 | ## Node Definition 20 | 21 | A node contains two required properties; the advertising system identifier (asi) and the seller ID (sid). The advertising system identifier is the domain name of the advertising system. The seller ID is used to identify the seller of the inventory; who the advertising system pays for this inventory. Both the advertising system identifier and the seller ID should be the same values that are provided in ads.txt files. It is invalid for a Seller ID to represent multiple entities. Every Seller ID must map to only a single entity that is paid for inventory transacted with that Seller ID. It is valid for a selling entity to have multiple Seller IDs within an advertising system. 22 | 23 | 24 | ## OpenRTB Object: SupplyChain 25 | 26 | This object represents both the links in the supply chain as well as an indicator whether or not the supply chain is complete. 27 | 28 | The SupplyChain object should be included in the BidRequest.Source.schain attribute in OpenRTB 2.6 or later, and BidRequest.Source.ext.schain attribute in OpenRTB 2.5. For OpenRTB 2.4 or prior, the BidRequest.ext.schain attribute should be used. 29 | 30 | The SupplyChain object includes the following attributes: 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 |
    AttributeTypeDescription
    completeinteger; requiredFlag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app or other medium of the inventory, where 0 = no, 1 = yes.
    nodesobject array; requiredArray of SupplyChainNode objects in the order of the chain. In a complete supply chain, the first node represents the initial advertising system and seller ID involved in the transaction, i.e. the owner of the site, app, or other medium. In an incomplete supply chain, it represents the first known node. The last node represents the entity sending this bid request.
    verstring; requiredVersion of the supply chain specification in use, in the format of “major.minor”. For example, for version 1.0 of the spec, use the string “1.0”.
    extobject; optionalPlaceholder for advertising-system specific extensions to this object.
    60 | 61 | 62 | ## OpenRTB Object: SupplyChainNode 63 | 64 | This object is associated with a SupplyChain object as an array of nodes. These nodes define the identity of an entity participating in the supply chain of a bid request. The SupplyChainNode object contains the following attributes: 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 78 | 79 | 80 | 81 | 82 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 105 | 106 | 107 | 108 | 109 | 111 | 112 |
    AttributeTypeDescription
    asiString; requiredThe canonical domain name of the SSP, Exchange, Header Wrapper, etc system that bidders connect to. This may be the operational domain of the system, if that is different than the parent corporate domain, to facilitate WHOIS and reverse IP lookups to establish clear ownership of the delegate system. This should be the same value as used to identify sellers in an ads.txt file if one exists. 77 |
    sidstring; requiredThe identifier associated with the seller or reseller account within the advertising system. This must contain the same value used in transactions (i.e. OpenRTB bid requests) in the field specified by the SSP/exchange. Typically, in OpenRTB, this is publisher.id. For OpenDirect it is typically the publisher’s organization ID.Should be limited to 64 characters in length. 83 |
    ridString; optionalThe OpenRTB RequestId of the request as issued by this seller.
    nameString; optionalThe name of the company (the legal entity) that is paid for inventory transacted under the given seller_id. This value is optional and should NOT be included if it exists in the advertising system’s sellers.json file.
    domainstring; optionalThe business domain name of the entity represented by this node. This value is optional and should NOT be included if it exists in the advertising system’s sellers.json file.
    hpinteger; requiredIndicates whether this node will be involved in the flow of payment for the inventory. When set to 1, the advertising system in the asi field pays the seller in the sid field, who is responsible for paying the previous node in the chain. When set to 0, this node is not involved in the flow of payment for the inventory. For version 1.0 of SupplyChain, this property should always be 1. It is explicitly required to be included as it is expected that future versions of the specification will introduce non-payment handling nodes. Implementers should ensure that they support this field and propagate it onwards when constructing SupplyChain objects in bid requests sent to a downstream advertising system. 104 |
    extobject; optionalPlaceholder for advertising-system specific extensions to this object. 110 |
    113 | 114 | Note that the asi and domain fields are to be populated with only the canonical domains of the advertising system or seller, and these should be the same domains used in OpenRTB Site .domain, sellers.json, ads.txt for reconciliation. Full URLs (or even schemas, i.e. http:// or https://) should not be used. For the purposes of this document the “root domain” is defined as the “public suffix” plus one string in the name. Implementers should incorporate Public Suffix list [16] to derive the root domain. 115 | 116 | Valid examples: 117 | example.com 118 | example.co.uk 119 | 120 | Invalid examples: 121 | http://example.com 122 | https://example.com/about-us.html 123 | 124 | 125 | ## Implementation Details 126 | 127 | It is invalid for a reseller to copy the SupplyChain object from the previous seller to their request for that inventory without also inserting their node into the chain. If a reseller doesn’t insert themselves in the chain, their bid request should not include the SupplyChain object. 128 | 129 | If a seller is reselling inventory that didn’t previously contain a SupplyChain object, they should create the SupplyChain object themselves, mark the “complete” attribute with a value of 0 and insert their node into the “nodes” array. 130 | 131 | If a seller is reselling inventory that has a SupplyChain object, the reseller should copy the existing object, keeping the original value of the “complete” and append their node to the end of the “nodes” array. 132 | 133 | If this is the originating bid request for this inventory, the SupplyChain object should be created with the “complete” attribute set to 1 and their information being the only node in the “nodes” array. 134 | 135 | 136 | ## Examples: 137 | 138 | ## Valid, complete SupplyChain objects 139 | 140 | ### Sample originating bid request. (BidRequest1, seller = “directseller.com”): 141 | 142 | 143 | ``` 144 | "bidrequest" : { 145 | "id": "BidRequest1", 146 | "app": { 147 | "publisher": { 148 | "id": "00001" 149 | } 150 | } 151 | "source": { 152 | "ext": { 153 | "schain": { 154 | "ver":"1.0", 155 | "complete": 1, 156 | "nodes": [ 157 | { 158 | "asi":"directseller.com", 159 | "sid":"00001", 160 | "rid":"BidRequest1", 161 | "hp":1 162 | } 163 | ] 164 | } 165 | } 166 | } 167 | } 168 | ``` 169 | 170 | ### Sample resale of BidRequest1 (BidRequest2, seller = “reseller.com”): 171 | 172 | ``` 173 | "bidrequest" : { 174 | "id": "BidRequest2", 175 | "app": { 176 | "publisher": { 177 | "id": "aaaaa" 178 | } 179 | } 180 | "source": { 181 | "ext": { 182 | "schain": { 183 | "ver":"1.0", 184 | "complete": 1, 185 | "nodes": [ 186 | { 187 | "asi":"directseller.com", 188 | "sid":"00001" 189 | "rid":"BidRequest1", 190 | "hp":1 191 | }, 192 | { 193 | "asi":"reseller.com", 194 | "sid":"aaaaa", 195 | "rid":"BidRequest2", 196 | "hp":1 197 | } 198 | ] 199 | } 200 | } 201 | } 202 | } 203 | 204 | ``` 205 | 206 | ## Valid, incomplete SupplyChain objects 207 | 208 | ### Sample originating bid request from advertising system that doesn’t support SupplyChain object. (BidRequest3, seller = “directseller.com”): 209 | 210 | ``` 211 | "bidrequest" : { 212 | "id": "BidRequest3", 213 | "app": { 214 | "publisher": { 215 | "id": "00001" 216 | } 217 | } 218 | "source": { 219 | "ext": { 220 | } 221 | } 222 | } 223 | ``` 224 | 225 | ### Sample resale of BidRequest3 by advertising system that does support SupplyChain object. (BidRequest4, seller = “reseller.com”): 226 | 227 | 228 | ``` 229 | "bidrequest" : { 230 | "id": "BidRequest4", 231 | "app": { 232 | "publisher": { 233 | "id": "aaaaa" 234 | } 235 | } 236 | "source": { 237 | "ext": { 238 | "schain": { 239 | "ver":"1.0", 240 | "complete": 0, 241 | "nodes": [ 242 | { 243 | "asi":"reseller.com", 244 | "sid":"aaaaa", 245 | "rid":"BidRequest4", 246 | "hp":1 247 | } 248 | ] 249 | } 250 | } 251 | } 252 | } 253 | ``` 254 | ## SupplyChain for Non-OpenRTB Requests 255 | As the documentation above provides guidance only for transactions made via OpenRTB protocol, this section describes a standard way to communicate SupplyChain information that via a tag rather than OpenRTB. This situation most commonly occurs when an advertising system provides a tag that can be inserted into an ad server, video player, SSAI vendor, etc. to initiate an ad request to an advertising system. 256 | 257 | **Goals of the serialization:** 258 | * Support all properties of SupplyChain object 259 | * Minimize the need for URL encoding of the serialized data 260 | * Support forward compatibility for future changes to SupplyChain 261 | 262 | **Usage Scenarios:** 263 | This appendix outlines the methodology defining a well-structured string containing SupplyChain data that can be received via industry standard ‘key value pairs’. 264 | 265 | If the receiving advertising system is handling a tag-based request and forming an outbound OpenRTB request to another adverting system then the following procedure is specified. First it should parse the SupplyChain data received as described below, create and fill the SupplyChain object with the data received. Finally the advertising system should append its own information to the array in the object. 266 | 267 | If the receiving advertising system is handling a tag-based request and forming an outbound tag-based request to another advertising system then the following procedure is specified: It should append a node for itself to the pre-existing string, without altering any preceding information in the received string. 268 | 269 | If the receiving advertising system is handling an OpenRTB request and forming an outbound tag-based request to another advertising system then the following procedure is specified: It should parse and serialize the data within the received SupplyChain object and serialize as specified below. It should form a spec compliant string for itself then append it to the prior string. 270 | 271 | **Receiving SupplyChain into an advertising system via tags or URLs** 272 | Advertising systems should support a parameter in their ad tags or VAST URLs to accept a string serialized SupplyChain. It is recommended that this parameter be “schain”. 273 | 274 | For example, an ad server may have a display ad tag format like this: 275 | 276 | ``` 277 | 278 | ``` 279 | 280 | or a VAST URL format like: 281 | 282 | ``` 283 | https://ads.exchange1.com/srv?pid=194&sz=v&plid=2842185&schain=[SUPPLYCHAIN GOES HERE] 284 | ``` 285 | 286 | **Sending SupplyChain to other tags or URLs** 287 | An advertising system may have a need to pass on a SupplyChain object to another ad tag or VAST URL. This may occur regardless of whether the SupplyChain information is received by the advertising system through OpenRTB or via a string serialized SupplyChain as described above. For this purpose, it is recommended that advertising systems support a macro (for example, $SCHAIN) to output a string serialized SupplyChain. The output of this macro must be a string serialized SupplyChain with the advertising system’s node appended. 288 | 289 | ### Serialization of an OpenRTB SupplyChain object into a URL parameter 290 | Suggested URL parameter: schain 291 | 292 | ### Format of serialization 293 | The serialization is composed of two items; the SupplyChainObject properties and the SupplyChainNode array. These two items are separated by a bang (“!”) character. 294 | 295 | ```{SupplyChainObject}!{SupplyChainNode array}``` 296 | 297 | ### SupplyChainObject properties 298 | There are two properties in a SupplyChain object; version and complete. These two values must be included at the beginning of the serialized value and must be separated by a comma (“,”). 299 | 300 | ```ver,complete``` 301 | 302 | ### Array of SupplyChainNode properties 303 | Following the SupplyChainObject properties, every node in the SupplyChain must be included. Properties of a SupplyChainNode object must be separated by a comma (“,”) and if there is more than one node, each must be separated by a bang (“!”) character. 304 | 305 | The order of properties is as follows: 306 | 307 | ```asi,sid,hp,rid,name,domain,ext``` 308 | 309 | The contents of the ext property are exchange specific, no attempt is made in this document to specify the method of serialization of values for this object. 310 | 311 | Optional SupplyChainNode property values can be omitted and trailing separators can be optionally excluded. 312 | 313 | Example: 314 | ```exampleexchange.com,12345,1,,,``` 315 | 316 | or 317 | 318 | ```exampleexchange.com,12345,1``` 319 | 320 | If the values in any of the properties require URL encoding (See RFC 3986 or Wikipedia post) or contain a comma or bang character, they should be URL encoded. The comma that is used to separate properties should not be encoded. 321 | 322 | Example: 323 | ```exampleexchange.com,123%2CB,1,,,``` 324 | 325 | This represents an sid of “123,B” on exampleexchange.com, which handles payments. 326 | 327 | ### Examples 328 | 329 | ### Single Hop - Chain Complete 330 | 331 | **SupplyChain** 332 | ``` 333 | "schain" : { 334 | "ver":"1.0", 335 | "complete":1, 336 | "nodes":[ 337 | { 338 | "asi":"exchange1.com", 339 | "sid":"1234", 340 | "hp":1, 341 | "rid":"bid-request-1", 342 | "name":"publisher", 343 | "domain":"publisher.com" 344 | } 345 | ] 346 | } 347 | ``` 348 | 349 | **Serialized Value** 350 | ``` 351 | 1.0,1!exchange1.com,1234,1,bid-request-1,publisher,publisher.com 352 | ``` 353 | 354 | ### Single Hop - Chain Complete, optional fields missing 355 | 356 | **SupplyChain** 357 | ``` 358 | "schain" : { 359 | "ver":"1.0", 360 | "complete":1, 361 | "nodes" : [ 362 | { 363 | "asi":"exchange1.com", 364 | "sid":"1234", 365 | "hp":1 366 | } 367 | ] 368 | } 369 | ``` 370 | 371 | **Serialized Value** 372 | ```1.0,1!exchange1.com,1234,1,,,``` 373 | 374 | ### Multiple Hops - With all properties supplied 375 | 376 | **SupplyChain** 377 | ``` 378 | "schain" : { 379 | "ver": "1.0", 380 | "complete" : 1, 381 | "nodes" : [ 382 | { 383 | "asi":"exchange1.com", 384 | "sid":"1234", 385 | "hp":1, 386 | "rid":"bid-request-1", 387 | "name":"publisher", 388 | "domain":"publisher.com" 389 | }, 390 | { 391 | "asi":"exchange2.com", 392 | "sid":"abcd", 393 | "hp":1, 394 | "rid":"bid-request-2", 395 | "name":"intermediary", 396 | "domain":"intermediary.com" 397 | } 398 | ] 399 | } 400 | ``` 401 | **Serialized Value** 402 | ```1.0,1!exchange1.com,1234,1,bid-request-1,publisher,publisher.com!exchange2.com,abcd,1,bid-request2,intermediary,intermediary.com``` 403 | 404 | ### Multiple Hops - Chain Complete, optional fields missing 405 | 406 | **SupplyChain** 407 | ``` 408 | "schain" : { 409 | "ver":"1.0", 410 | "complete":1, 411 | "nodes":[ 412 | { 413 | "asi":"exchange1.com", 414 | "sid":"1234", 415 | "hp":1 416 | }, 417 | { 418 | "asi":"exchange2.com", 419 | "sid":"abcd", 420 | "hp":1 421 | } 422 | ] 423 | } 424 | ``` 425 | 426 | **Serialized Value** 427 | ```1.0,1!exchange1.com,1234,1,,,!exchange2.com,abcd,1,,,``` 428 | 429 | ### Multiple Hops Expected - Chain Incomplete 430 | 431 | **SupplyChain** 432 | ``` 433 | "schain" : { 434 | "ver":"1.0", 435 | "complete" :0, 436 | "nodes":[ 437 | { 438 | "asi":"exchange2.com", 439 | "sid":"abcd", 440 | "hp":1 441 | } 442 | ] 443 | } 444 | ``` 445 | 446 | **Serialized Value** 447 | ```1.0,0!exchange2.com,abcd,1,,,``` 448 | 449 | ### Single Hop - Chain Complete, encoded values 450 | 451 | **SupplyChain** 452 | ``` 453 | "schain" : { 454 | "ver":"1.0", 455 | "complete":1, 456 | "nodes":[ 457 | { 458 | "asi":"exchange1.com", 459 | "sid":"1234!abcd", 460 | "hp":1, 461 | "rid":"bid-request-1", 462 | "name":"publisher, Inc.", 463 | "domain":"publisher.com" 464 | } 465 | ] 466 | } 467 | ``` 468 | 469 | **Serialized Value** 470 | ```1.0,1!exchange1.com,1234%21abcd,1,bid-request-1,publisher%2c%20Inc.,publisher.com``` 471 | 472 | --------------------------------------------------------------------------------