From 047080cb3911c4adabfc1f2e009d0fd2e534d94d Mon Sep 17 00:00:00 2001 From: Scott Kay Date: Tue, 6 Dec 2022 01:02:35 -0500 Subject: [PATCH] OpenRTB 2.6-202211 (#1) * InventoryPartnerDomain, ETime, + GPP * DOOH * Fix Type Name Change * Final Release Update * Revert Comment To Match Final Spec * Remove inventorypartnerdomain from adcom app object and fix typos Co-authored-by: bsardo <1168933+bsardo@users.noreply.github.com> --- ...dooh_multiplier_measurement_source_type.go | 13 +++ adcom1/dooh_venue_taxonomies.go | 29 ++++++ adcom1/dooh_venue_type.go | 1 + openrtb2/app.go | 19 +++- openrtb2/bid_request.go | 10 +++ openrtb2/dooh.go | 89 +++++++++++++++++++ openrtb2/imp.go | 19 ++++ openrtb2/qty.go | 39 ++++++++ openrtb2/regs.go | 25 +++++- openrtb2/site.go | 22 ++++- 10 files changed, 259 insertions(+), 7 deletions(-) create mode 100644 adcom1/dooh_multiplier_measurement_source_type.go create mode 100644 adcom1/dooh_venue_taxonomies.go create mode 100644 openrtb2/dooh.go create mode 100644 openrtb2/qty.go diff --git a/adcom1/dooh_multiplier_measurement_source_type.go b/adcom1/dooh_multiplier_measurement_source_type.go new file mode 100644 index 0000000..c8fad87 --- /dev/null +++ b/adcom1/dooh_multiplier_measurement_source_type.go @@ -0,0 +1,13 @@ +package adcom1 + +// DOOHMultiplierMeasurementSourceType identifies the types of entities that provide quantity measurement for +// impression multipliers, which are common in DOOH (Digital Out of Home) advertising. +type DOOHMultiplierMeasurementSourceType int8 + +// MultiplierMeasurementSourceType options. +const ( + MultiplierUnknown DOOHMultiplierMeasurementSourceType = 0 + MultiplierMeasurementVendorProvided DOOHMultiplierMeasurementSourceType = 1 + MultiplierPublisherProvided DOOHMultiplierMeasurementSourceType = 2 + MultiplierExchangeProvided DOOHMultiplierMeasurementSourceType = 3 +) diff --git a/adcom1/dooh_venue_taxonomies.go b/adcom1/dooh_venue_taxonomies.go new file mode 100644 index 0000000..64ce835 --- /dev/null +++ b/adcom1/dooh_venue_taxonomies.go @@ -0,0 +1,29 @@ +package adcom1 + +// DOOHVenueTaxonomy describes the locations and contexts in which Out-Of-Home media may be experienced. Taxonomies entries +// are expected to refer to a specific version, unless a given taxonomy has explicit semantics for forward compatibility and +// handling updates. +type DOOHVenueTaxonomy int + +// Digital out-of-home venue taxonomies. +const ( + VenueTaxonomyAdCom DOOHVenueTaxonomy = 0 // AdCom DOOH Venue Types (deprecated) + VenueTaxonomyOpenOOH10 DOOHVenueTaxonomy = 1 // OpenOOH Venue Taxonomy 1.0 https://github.com/openooh/venue-taxonomy/blob/main/specification-1.0.md + VenueTaxonomyDPAA DOOHVenueTaxonomy = 2 // DPAA Device Venue Types https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list--dooh-venue-types- + VenueTaxonomyDMI11 DOOHVenueTaxonomy = 3 // DMI Categorization of Venues 1.1 https://www.dmi-org.com/download/DMI_Standards_for_DOOH_Venues.pdf + VenueTaxonomyOMAJan2022 DOOHVenueTaxonomy = 4 // OMA taxonomy Jan 2022 https://www.oma.org.au/industry-standards + VenueTaxonomyOpenOOH11 DOOHVenueTaxonomy = 5 // OpenOOH Venue Taxonomy 1.1 https://github.com/openooh/venue-taxonomy/blob/main/specification-1.1.md +) + +// Ptr returns pointer to own value. +func (t DOOHVenueTaxonomy) Ptr() *DOOHVenueTaxonomy { + return &t +} + +// Val safely dereferences pointer, returning default value (ConnectionUnknown) for nil. +func (t *DOOHVenueTaxonomy) Val() DOOHVenueTaxonomy { + if t == nil { + return VenueTaxonomyOpenOOH10 + } + return *t +} diff --git a/adcom1/dooh_venue_type.go b/adcom1/dooh_venue_type.go index 583f502..5da1698 100644 --- a/adcom1/dooh_venue_type.go +++ b/adcom1/dooh_venue_type.go @@ -1,6 +1,7 @@ package adcom1 // DOOHVenueType represents the digital out-of-home venue types and is derived from DPAA Programmatic Standards. +// This enumeration is deprecated. type DOOHVenueType int // Digital out-of-home venue types. diff --git a/openrtb2/app.go b/openrtb2/app.go index c0a5135..52ac8a7 100644 --- a/openrtb2/app.go +++ b/openrtb2/app.go @@ -6,10 +6,10 @@ import ( "github.com/prebid/openrtb/v17/adcom1" ) -// 3.2.14 Object: App +// Object: App // // This object should be included if the ad supported content is a non-browser application (typically in mobile) as opposed to a website. -// A bid request must not contain both an App and a Site object. +// A bid request with an app object must not contain a site or DOOH object. // At a minimum, it is useful to provide an App ID or bundle, but this is not strictly required. type App struct { @@ -155,6 +155,21 @@ type App struct { // ‘kwarray’ may be present. KwArray []string `json:"kwarray,omitempty"` + // Attribute: + // inventorypartnerdomain + // Type: + // string + // Description: + // A domain to be used for inventory authorization in the case of inventory + // sharing arrangements between an app owner and content owner. This field + // is typically used by authorization crawlers to establish the domain of the + // content owner, who has the right to monetize some portion of ad inventory + // within the app. The content owner's domain should be listed in the app + // owner's app-ads.txt file as an inventorypartnerdomain. Authorization for + // supply from the inventorypartnerdomain will be published in the ads.txt + // file on the root of that domain. Refer to the ads.txt 1.1 spec for more details. + InventoryPartnerDomain string `json:"inventorypartnerdomain,omitempty"` + // Attribute: // ext // Type: diff --git a/openrtb2/bid_request.go b/openrtb2/bid_request.go index 0b88637..f59f036 100644 --- a/openrtb2/bid_request.go +++ b/openrtb2/bid_request.go @@ -53,6 +53,16 @@ type BidRequest struct { // recommended for apps. App *App `json:"app,omitempty"` + // Attribute: + // dooh + // Type: + // object + // Description: + // This object should be included if the ad supported content is a + // Digital Out-Of-Home screen. A bid request with a DOOH object must + // not contain a site or app object. + DOOH *DOOH `json:"dooh,omitempty"` + // Attribute: // device // Type: diff --git a/openrtb2/dooh.go b/openrtb2/dooh.go new file mode 100644 index 0000000..522e4d0 --- /dev/null +++ b/openrtb2/dooh.go @@ -0,0 +1,89 @@ +package openrtb2 + +import ( + "encoding/json" + + "github.com/prebid/openrtb/v17/adcom1" +) + +// Object: DOOH +// +// This object should be included if the ad supported content is a Digital Out-Of-Home screen. +// A bid request with a DOOH object must not contain a site or app object. +// At a minimum, it is useful to provide id and/or venuetype, but this is not strictly required. +type DOOH struct { + + // Attribute: + // id + // Type: + // string; recommended + // Description: + // Exchange provided id for a placement or logical grouping of placements. + ID string `json:"id,omitempty"` + + // Attribute: + // name + // Type: + // string + // Description: + // Name of the DOOH placement. + Name string `json:"name,omitempty"` + + // Attribute: + // venuetype + // Type: + // string, array + // Description: + // The type of out-of-home venue. The taxonomy to be used is defined by + // the venuetax field. If no venuetax field is supplied, The OpenOOH + // Venue Taxonomy is assumed. + VenueType []string `json:"venuetype,omitempty"` + + // Attribute: + // venuetypetax + // Type: + // integer; default 1 + // Description: + // The venue taxonomy in use. Refer to List: DOOH Venue Taxonomies + VenueTypeTax *adcom1.DOOHVenueTaxonomy `json:"venuetypetax,omitempty"` + + // Attribute: + // publisher + // Type: + // object + // Description: + // Details about the publisher of the placement. + Publisher *Publisher `json:"publisher,omitempty"` + + // Attribute: + // domain + // Type: + // string + // Description: + // Domain of the inventory owner (e.g., “mysite.foo.com”) + Domain string `json:"domain,omitempty"` + + // Attribute: + // keywords + // Type: + // string + // Description: + // Comma separated list of keywords about the DOOH placement. + Keywords string `json:"keywords,omitempty"` + + // Attribute: + // content + // Type: + // object + // Description: + // Details about the Content within the DOOH placement. + Content *Content `json:"content,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Description: + // Placeholder for exchange-specific extensions to OpenRTB. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/openrtb2/imp.go b/openrtb2/imp.go index 9e0f3d0..2109c9e 100644 --- a/openrtb2/imp.go +++ b/openrtb2/imp.go @@ -199,6 +199,25 @@ type Imp struct { // between the auction and the actual impression. Exp int64 `json:"exp,omitempty"` + // Attribute: + // qty + // Type: + // object + // Description: + // A means of passing a multiplier in the bid request, representing the total + // quantity of impressions for adverts that display to more than one person. + Qty *Qty `json:"qty,omitempty"` + + // Attribute: + // dt + // Type: + // float + // Description: + // Timestamp when the item is estimated to be fulfilled (e.g. when a DOOH + // impression will be displayed) in Unix format (i.e., milliseconds since + // the epoch). + DT float64 `json:"dt,omitempty"` + // Attribute: // ext // Type: diff --git a/openrtb2/qty.go b/openrtb2/qty.go new file mode 100644 index 0000000..7fb962f --- /dev/null +++ b/openrtb2/qty.go @@ -0,0 +1,39 @@ +package openrtb2 + +import "github.com/prebid/openrtb/v17/adcom1" + +// Object: Qty +// +// A programmatic impression is often referred to as a ‘spot’ in digital out-of-home and CTV, with an impression being a unique member of the audience viewing it. +// Therefore, a standard means of passing a multiplier in the bid request, representing the total quantity of impressions, is required. +// This object includes the impression multiplier, and describes the source of the multiplier value. +type Qty struct { + + // Attribute: + // multiplier + // Type: + // float; required + // Description: + // The quantity of billable events which will be deemed to have occurred + // if this item is purchased. For example, a DOOH opportunity may be + // considered to be 14.2 impressions. Equivalent to qtyflt in OpenRTB 3.0. + Multiplier float64 `json:"multiplier,omitempty"` + + // Attribute:x + // sourcetype + // Type: + // integer; recommended + // Description: + // The source type of the quantity measurement, ie. publisher. Refer to + // List: DOOH Multiplier Measurement Source Types. + SourceType adcom1.DOOHMultiplierMeasurementSourceType `json:"sourcetype,omitempty"` + + // Attribute: + // vendor + // Type: + // string; required if sourcetype is present and type = 1 + // Description: + // The top level business domain name of the measurement vendor providing + // the quantity measurement. + Vendor string `json:"vendor,omitempty"` +} diff --git a/openrtb2/regs.go b/openrtb2/regs.go index 54c05d5..a19c6d7 100644 --- a/openrtb2/regs.go +++ b/openrtb2/regs.go @@ -2,10 +2,10 @@ package openrtb2 import "encoding/json" -// 3.2.3 Object: Regs +// Object: Regs // // This object contains any legal, governmental, or industry regulations that the sender deems applicable to the request. -// See Section 7.5 for more details on the flags supporting Coppa, GDPR and CCPA. +// See Section 7.5 for more details on the flags supporting Coppa, GDPR and others. type Regs struct { // Attribute: @@ -38,6 +38,27 @@ type Regs struct { // to Section 7.5 for more information. USPrivacy string `json:"us_privacy,omitempty"` + // Attribute: + // gpp + // Type: + // string + // Description: + // Contains the Global Privacy Platform’s consent string. See the + // Global Privacy Platform specification for more details. + GPP string `json:"gpp,omitempty"` + + // Attribute: + // gpp_sid + // Type: + // integer array + // Description: + // Array of the section(s) of the string which should be applied for this + // transaction. Generally will contain one and only one value, but there + // are edge cases where more than one may apply. GPP Section 3 (Header) + // and 4 (Signal Integrity) do not need to be included. See the + // GPP Section Information for more details. + GPPSID []int8 `json:"gpp_sid,omitempty"` + // Attribute: // ext // Type: diff --git a/openrtb2/site.go b/openrtb2/site.go index a491660..8d7e7c6 100644 --- a/openrtb2/site.go +++ b/openrtb2/site.go @@ -6,10 +6,10 @@ import ( "github.com/prebid/openrtb/v17/adcom1" ) -// 3.2.13 Object: Site +// Object: Site // -// This object should be included if the ad supported content is a website as opposed to a non-browser application. -// A bid request must not contain both a Site and an App object. +// This object should be included if the ad supported content is a website as opposed to a non-browser application or Digital Out of Home (DOOH) inventory. . +// A bid request must not contain more than one of a `Site`, `App` or `DOOH` object. // At a minimum, it is useful to provide a site ID or page URL, but this is not strictly required. type Site struct { @@ -151,6 +151,22 @@ type Site struct { // ‘kwarray’ may be present. KwArray []string `json:"kwarray,omitempty"` + // Attribute: + // inventorypartnerdomain + // Type: + // string + // Description: + // A domain to be used for inventory authorization in the case of inventory + // sharing arrangements between a site owner and content owner. This field + // is typically used by authorization crawlers to establish the domain of + // the content owner, who has the right to monetize some portion of ad + // inventory within the site. The content owner's domain should be listed + // in the site owner's ads.txt file as an inventorypartnerdomain. Authorization + // for supply from the inventorypartnerdomain will be published in the ads.txt + // file on the root of that domain. Refer to the ads.txt 1.1 spec for more + // details. + InventoryPartnerDomain string `json:"inventorypartnerdomain,omitempty"` + // Attribute: // ext // Type: