Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding option to indicate currency at impression or deal level #113

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

Adding option to indicate currency at impression or deal level #113

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 71 additions & 62 deletions 2.6.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ THE STANDARDS, THE SPECIFICATIONS, THE MEASUREMENT GUIDELINES, AND ANY OTHER MAT

## [7. Implementation Notes](implementation.md#implementationnotes)

- [7.1 - No-Bid Signaling](implementation.md#nobidsignaling)
- [7.1 - No-Bid Signaling](implementation.md#nobidsignaling)

- [7.2 - Impression Expiration](implementation.md#impressionexpiration)

Expand All @@ -219,7 +219,7 @@ THE STANDARDS, THE SPECIFICATIONS, THE MEASUREMENT GUIDELINES, AND ANY OTHER MAT

- [7.11 - Guidance on the Use of Floors](implementation.md#floors)


## [Appendix A. Additional Information](#appendixa)

## [Appendix B. Specification Change Log](#appendixb)
Expand All @@ -240,7 +240,7 @@ Some optional attributes are denoted "recommended." As that term is used herein
<td><strong>Description</strong></td>
</tr>
<tr>
<td rowspan="2">Examples of required attributes.<br> Grouped at the tops of tables for convenience</td>
<td rowspan="2">Examples of required attributes.<br> Grouped at the tops of tables for convenience</td>
<td><code>id</code></td>
<td>string;<br> required</td>
<td>...</td>
Expand All @@ -251,7 +251,7 @@ Some optional attributes are denoted "recommended." As that term is used herein
<td>...</td>
</tr>
<tr>
<td rowspan="2">Examples of recommended attributes.<br> Grouped after required attributes.</td>
<td rowspan="2">Examples of recommended attributes.<br> Grouped after required attributes.</td>
<td><code>site</code></td>
<td>object;<br>recommended</td>
<td>...</td>
Expand Down Expand Up @@ -286,7 +286,7 @@ Some optional attributes are denoted "recommended." As that term is used herein
*Example of how Required, Recommended and Optional attributes are presented.*

**IMPORTANT:** Since **recommended** attributes are not required, they may not be available from all supply sources. It is suggested that all parties to OpenRTB trasnaction develop an integration checklist to identify which attributes the supply side supports in the bid request, and which attributes the demand side requires for ad decisioning.

# 1. Introduction <a name="intro"></a>

## 1.1 - Mission / Overview <a name="mission"></a>
Expand Down Expand Up @@ -384,9 +384,9 @@ The following terms are used throughout this document specifically in the contex
The following figure illustrates the OpenRTB interactions between an exchange and its bidders. Ad requests originate at publisher sites or applications. For each inbound ad request, bid requests are broadcast to bidders, responses are evaluated under prevailing auction rules, and a winner is selected. The winning bidder is notified of the auction win via a win notice. Ad markup can either be included in the bid prospectively or in response to the win notice. A separate billing notice is also available to accommodate varying policies enacted by exchanges which are beyond the scope of the OpenRTB specification (e.g., billing on device delivery, viewability, etc.). The win notice informs the bidder’s pricing algorithms of a success, whereas the billing notice indicates that spend should actually be applied. A loss notification is also available to inform the bidder of the reason their bid did not win.

The URLs for win, billing, and loss notices and the ad markup itself can contain any of several standard macros that enable the exchange to communicate critical data to the bidder (e.g., clearing price).

![](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/864a56706b106eda94c03abefaa01dd43544864c/assets/Figure1%20OpenRTB.png)

*Figure 2: Reference Model - Request Sequence.*

This specification focuses on the real-time interactions of bid request and response and the win, billing, and loss notices. Related specifications include:
Expand Down Expand Up @@ -468,7 +468,7 @@ This means:
For example, if a new field or object is introduced in a future version of OpenRTB 2.6, exchanges should immediately start transmitting it to bidders, if the exchange chooses to implement support for that field. Bidders should start consuming it at their discretion, if it is relevant to them. Neither party needs to explicitly negotiate an "upgrade" to the latest release, but rather should discuss specific fields of interest as they become available.

New minor versions of OpenRTB 2.6 may introduce additional optional ways of handling things. For example, burl field was introduced in OpenRTB 2.5. Use of `burl` (instead of including a pixel in markup in `adm` field) is a breaking change for a specific exchange <> bidder integration, but this is a result of a decision between these parties to switch impression counting methodology and not a result of OpenRTB 2.5 itself. Partners should discuss such situations before making breaking changes to their integrations.

## 2.7 - Privacy <a name="privacy"></a>

Without limiting the scope of the Disclaimer, the OpenRTB specification does include several features to support implementer’s communication of information regarding consumer privacy, including, but not limited to:
Expand Down Expand Up @@ -497,7 +497,7 @@ RTB transactions are initiated when an exchange or other supply source sends a b
## 3.1 - Object Model <a name="objectmodel"></a>

Following is the object model for the bid request. The top-level object (i.e., in JSON the unnamed outer object) is denoted as `BidRequest` in the model. Of its direct subordinates, only `Imp` is technically required since it is fundamental to describing the impression being sold and it requires at least one of `Banner` (which may allow multiple formats), `Video`, `Audio`, and `Native` to define the type of impression (i.e., whichever one or more the publisher is willing to accept; although a bid will be for exactly one of those specified). An impression can optionally be subject to a private marketplace.

![](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/a29f4b1060c04813270dbf13607bba0403409068/assets/ORTB%20ERD.png)

*Figure 3: Bid Request object model.*
Expand Down Expand Up @@ -1034,14 +1034,19 @@ The presence of `Banner` (Section 3.2.6), `Video` (Section 3.2.7), and/or `Nativ
<td>Details about ad slots being refreshed automatically. (Section 3.2.33)</td>
</td>
</tr>
<tr>
<td><code>cur</code></td>
<td>string; default "USD"</td>
<td>Deal currency using ISO-4217 alpha codes.</td>
</tr>
<tr>
<td><code>ext</code></td>
<td>object</td>
<td>Placeholder for exchange-specific extensions to OpenRTB.</td>
</td>
</td>
</tr>

</table>


Expand Down Expand Up @@ -1114,9 +1119,9 @@ The presence of a `Banner` as a subordinate of the `Imp` object indicates that t
<td>integer array</td>
<td>Blocked banner ad types.<br>
Values:<br>
1 = XHTML Text Ad,<br>
2 = XHTML Banner Ad,<br>
3 = JavaScript Ad,<br>
1 = XHTML Text Ad,<br>
2 = XHTML Banner Ad,<br>
3 = JavaScript Ad,<br>
4 = iframe.<br></td>
</tr>
<tr>
Expand Down Expand Up @@ -1672,24 +1677,29 @@ This object constitutes a specific deal that was struck between a buyer and a se
</tr>
<tr>
<td><code>wadomain</code></td>
<td>string array</td>
<td>string array</td>
<td>Array of advertiser domains (e.g., advertiser.com) allowed to bid on this deal. Omission implies no advertiser restrictions.</td>
</tr>
<tr>
<td><code>guar</code></td>
<td>integer, default 0</td>
<td>integer, default 0</td>
<td>Indicates that the deal is of type `guaranteed` and the bidder must bid on the deal, where 0 = not a guaranteed deal, 1 = guaranteed deal.</td>
</tr>
<tr>
<td><code>mincpmpersec</code></td>
<td>float</td>
<td>float</td>
<td>Minimum CPM per second. This is a price floor for video or audio impression opportunities, relative to the duration of bids an advertiser may submit.</td>
</tr>
<tr>
<td><code>durfloors</code></td>
<td>object array</td>
<td>object array</td>
<td>Container for floor price by duration information, to be used if a given deal is eligible for video or audio demand. An array of DurFloors objects (see Section 3.2.35).</td>
</tr>
<tr>
<td><code>cur</code></td>
<td>string; default "USD"</td>
<td>Deal currency using ISO-4217 alpha codes.</td>
</tr>
<tr>
<td><code>ext</code></td>
<td>object</td>
Expand Down Expand Up @@ -2149,7 +2159,7 @@ This object defines the producer of the content in which the ad will be shown. T
</tr>
<td><code>cat</code></td>
<td>string array</td>
<td>Array of IAB Tech Lab content categories that describe the content producer.
<td>Array of IAB Tech Lab content categories that describe the content producer.
The taxonomy to be used is defined by the cattax field. If no cattax field is supplied Content Category Taxonomy 1.0 is assumed.</td>
</tr>
<tr>
Expand Down Expand Up @@ -2450,7 +2460,7 @@ This object contains information known or derived about the human user of the de
<td><code>id</code></td>
<td>string</td>
<td>Exchange-specific ID for the user.

<br>Unless prior arrangements have been made between the buyer and the seller directly, the value in this field is expected to be derived from an ID sync. (see <a href="https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/develop/2.6.md#appendix-c-cookie-based-id-syncing-">Appendix: Cookie Based ID Syncing)</a></br>
</td>
</tr>
Expand Down Expand Up @@ -2890,7 +2900,7 @@ Structured user agent information, which can be used when a client supports [Use
</tr>
</table>

* or an equivalent JavaScript accessor from [NavigatorUAData interface](https://wicg.github.io/ua-client-hints/#navigatoruadata). This header or accessor are only available for browsers that support [User-Agent Client Hints](https://wicg.github.io/ua-client-hints/).
* or an equivalent JavaScript accessor from [NavigatorUAData interface](https://wicg.github.io/ua-client-hints/#navigatoruadata). This header or accessor are only available for browsers that support [User-Agent Client Hints](https://wicg.github.io/ua-client-hints/).

### 3.2.30 - Object: BrandVersion <a name="objectbrandversion"></a>

Expand Down Expand Up @@ -3005,7 +3015,7 @@ This object should be included if the ad supported content is a Digital Out-Of-H

### 3.2.34 - Object: RefSettings <a name="objectrefsettings"></a>

Information on how often and what triggers an ad slot being refreshed.
Information on how often and what triggers an ad slot being refreshed.

<table>
<tr>
Expand Down Expand Up @@ -3074,7 +3084,7 @@ RTB responses contain bids that reference specific impressions within a bid requ

## 4.1 - Object Model <a name="4.2objectmodel"></a>

Following is the object model for the bid response. The top-level object (i.e., in JSON the unnamed outer object) is denoted as `BidResponse` in the model. A bid response may contain bids from multiple “seats” (i.e., the buying entity upstream from the actual bidder). In fact, a response may contain multiple bids from the same seat; typically but not necessarily from different campaigns. This can improve the seat’s chances of winning since most exchanges enforce various block lists on behalf of their publishers.
Following is the object model for the bid response. The top-level object (i.e., in JSON the unnamed outer object) is denoted as `BidResponse` in the model. A bid response may contain bids from multiple “seats” (i.e., the buying entity upstream from the actual bidder). In fact, a response may contain multiple bids from the same seat; typically but not necessarily from different campaigns. This can improve the seat’s chances of winning since most exchanges enforce various block lists on behalf of their publishers.

![](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/864a56706b106eda94c03abefaa01dd43544864c/assets/Figure3.png)

Expand Down Expand Up @@ -3378,7 +3388,7 @@ A `SeatBid` object contains one or more `Bid` objects, each of which relates to
<td><code>mtype</code></td>
<td>integer</td>
<td>Type of the creative markup so that it can properly be associated with the right sub-object of the <code>BidRequest.Imp.</code><br>
Values:<br>
Values:<br>
1 = Banner<br>
2 = Video,<br>
3 = Audio<br>
Expand Down Expand Up @@ -3487,7 +3497,7 @@ These same substitution macros can also be placed in the ad markup. The exchange
<td>Market Bid Ratio defined as: clearance price / bid price.</td>
</tr>
<tr>
<td><code>${AUCTION_LOSS}</code></td>
<td><code>${AUCTION_LOSS}</code></td>
<td>Loss reason codes. Refer to <a href="https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/OpenRTB%20v3.0%20FINAL.md#list--loss-reason-codes-">List: Loss Reason Codes</a> in OpenRTB 3.0.</td>
</tr>
<tr>
Expand Down Expand Up @@ -3531,7 +3541,7 @@ Except where the value "AUDIT" applies, as above, the macro is replaced by:
- The bid was not allowed into the auction, e.g., because of blocks on the seat, advertiser, etc.
- Per the loss code, price was not the deciding factor in the loss.
- As dictated by exchange privacy controls, e.g., if price data is not shared to bidders that did not meet the desired floor, or if the exchange supports a publisher or winning bidder election not to share price data with the other bidders.

- The minimum price required to tie with the winning bid, when your bid lost to another in the auction.
- The minimum price required to tie with the next-closest bid, or the floor if there was only one bid, when your bid won the auction.

Expand Down Expand Up @@ -4149,7 +4159,7 @@ Following is an example of a bid response with the ad served on win notice. The


### 6.3.4 - Example 4 – Native Markup Returned Inline <a name="nativemarkupreturnedinline"></a>

Following is an example of a bid response that returns a native ad inline to be served. The `adm` attribute contains an encoded string of a native ad request that conforms to the Dynamic Native Ads API and specifically the same version as that used for the request string. Alternatively, the `adm` attribute could have been omitted in favor of returning the native ad markup in the response to the win notice `nurl`.

```javascript
Expand All @@ -4174,7 +4184,7 @@ Following is an example of a bid response that returns a native ad inline to be

## [7. Implementation Notes](implementation.md#implementationnotes)

- [7.1 - No-Bid Signaling](implementation.md#nobidsignaling)
- [7.1 - No-Bid Signaling](implementation.md#nobidsignaling)

- [7.2 - Impression Expiration](implementation.md#impressionexpiration)

Expand All @@ -4196,57 +4206,57 @@ Following is an example of a bid response that returns a native ad inline to be

- [7.11 - Guidance on the Use of Floors](implementation.md#floors)


# Appendix A. Additional Information <a name="appendixa"></a>

- Creative Commons / Attribution License

creativecommons.org/licenses/by/3.0

- IAB (Interactive Advertising Bureau)

www.iab.com

- IAB Quality Assurance Guidelines (QAG):

www.iab.com/guidelines/iab-quality-assurance-guidelines-qag-taxonomy/

- JavaScript Object Notation (JSON)

www.json.org

- MMA (Mobile Marketing Association)

mmaglobal.com

- OpenRTB Project on Github

github.com/openrtb/OpenRTB/

- Apache Avro

avro.apache.org

Protocol Buffers (Protobuf)

code.google.com/p/protobuf

- Google Metro Codes

code.google.com/apis/adwords/docs/appendix/metrocodes.html

- U.N. Code for Trade and Transport Locations:

www.unece.org/cefact/locode/service/location.htm


# Appendix B. Specification Change Log <a name="appendixb"></a>

This appendix serves as an index of specification changes across 2.x versions. These changes pertain only to the substance of the specification and not routine document formatting, organization, or content without technical impact.

**<strong>Please refer to GitHub [Releases](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/releases) page for release notes for ORTB2.6-202303 onward</strong>**


**Version 2.6-202210 (Base 2.6 version) to 2.6-202211:**
<table>
<tr>
Expand Down Expand Up @@ -4280,8 +4290,8 @@ This appendix serves as an index of specification changes across 2.x versions. T
</table>

**Version 2.5 to 2.6:**


<table>
<tr>
<td><strong>Section&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</strong></td>
Expand Down Expand Up @@ -4372,19 +4382,19 @@ This appendix serves as an index of specification changes across 2.x versions. T
</td>
</tr>
</table>





**Version 2.4 to 2.5:**


<table>
<tr>
<td><strong>Section&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</strong></td>
<td><strong>Description&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</strong></td>
</tr>
<tr>
<td><code><b>2.4</b></code></td>
<td><code><b>2.4</b></code></td>
<td><b>Section: Data Encoding</b> New section added.</td>
</tr>
<tr>
Expand Down Expand Up @@ -4464,12 +4474,12 @@ This appendix serves as an index of specification changes across 2.x versions. T
</table>

# Appendix C. Cookie Based ID Syncing <a name="appendixc"></a>
Cookie syncing (also known as user syncing, user matching, cookie matching) is the process by which one party learns another party’s user IDs, and thus is foundational to availability of IDs in the cookie-based web environment. Since cookies are domain-specific, the sync process is necessary for one party to know the other’s IDs.
Cookie syncing (also known as user syncing, user matching, cookie matching) is the process by which one party learns another party’s user IDs, and thus is foundational to availability of IDs in the cookie-based web environment. Since cookies are domain-specific, the sync process is necessary for one party to know the other’s IDs.


Cookie syncs are established between any two parties in the ecosystem that need to send user IDs to each other. Classically, however, cookie syncs are established between DSPs and exchanges/SSPs, and between DSPs and DMPs.

In the cookie sync process, one party stores the relationship between their user IDs and the other party’s user IDs in a match table that knows that cookieID123 from party A is the same user as cookieID789 from party B.
In the cookie sync process, one party stores the relationship between their user IDs and the other party’s user IDs in a match table that knows that cookieID123 from party A is the same user as cookieID789 from party B.

When the sync pixel loads, the party reads their cookie (or sets a new one) to learn their user ID, and then issues a 302 redirect to a URL provided by the other party, to pass them that user ID. When the other party’s URL loads in the browser, they will be able to read their cookie (or set a new one), thus establishing the relationship between the two user IDs, which can then be stored (in a server-side data store of some sort, or simply by using a cookie to store it client-side if feasible).

Expand Down Expand Up @@ -4529,4 +4539,3 @@ There are frequently a long list of parties necessary to sync. For example, an e
It's also helpful if both parties deploy sync pixels when possible, as this increases the number of opportunities to perform sync for a given user.
Sync pixels fire in the user’s browser, and thus sync activity creates overhead when web pages load. To avoid blocking page loads, parties are advised to load sync pixels in a non-blocking manner, such as in a hidden IFRAME. Additionally, parties might wish to limit the number of sync partners deployed in a given instance to a modest number.
For example, a reasonable strategy would be to sync up to 5 partners on each occasion, and record that this has occurred and when. Then, on the next occasion, the next 5 partners can be synced, and so on. Once all partners have been rotated through and syncs established for a given user, it’s not necessary to fire any more sync pixels for a while. Keeping track of the timestamp of performing each sync enables the party to trigger another one shortly before they expect that the ID will expire out of the match table.