Native 1.2

README.md

@@ -2,10 +2,10 @@
 
 [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [v2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) types for Go programming language (Golang)
 
-Also includes [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API
-Specification Version 1.1](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf) types:
+Also includes [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API Specification Version 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) types:
 - [4 Native Ad Request Markup Details](native/request/)
 - [5 Native Ad Response Markup Details](native/response/)
+- [7 Reference Lists/Enumerations](native/)
 
 # Using
 
@@ -53,5 +53,4 @@ Master always contains latest code, so better use some package manager to vendor
 # TODO
 - [ ] Review all integral types, probably, switch everything to signed ones or just to `int`?
 - [ ] Consider switching back to `encoding/json.RawMessage`, as Go 1.8 fixed serialisation for non-ptr (probably, when Go 1.9 or even 1.10 is out)
-- [x] Review enum types (typed enum attributes + constants)
 - [ ] Review types, that are enums (or "open enums" like `BidRequest.at`) themselves, but not described in section 5 - make them typed

native/README.md

@@ -1,4 +1,4 @@
 # native
 
 [Go](https://golang.org/) implementation of [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API
-Specification Version 1.1](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf) types.
+Specification Version 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) types/enums.

native/request/ad_unit.go → native/ad_unit.go

@@ -1,12 +1,12 @@
-package request
+package native
 
-// 7.2 Native Ad Unit IDs - To Be Deprecated
-//
-// Ad Unit ID is to be deprecated in a future version and is not suggested for new implementations.
+// 7.2 Native Ad Unit IDs in version 1.1.
+// Deprecated/removed in version 1.2.
 //
 // Below is a list of the core ad unit ids described by IAB here http://www.iab.net/media/file/IABNativeAdvertisingPlaybook120413.pdf
 //
-// In feed unit is essentially a layout, it has been removed from the list. The in feed units can be identified via the layout parameter on the request.
+// In feed unit is essentially a layout, it has been removed from the list.
+// The in feed units can be identified via the layout parameter on the request.
 //
 // An implementing exchange may not support all asset variants or introduce new ones unique to that system.
 type AdUnit int64

native/request/context_sub_type.go → native/context_sub_type.go

@@ -1,6 +1,6 @@
-package request
+package native
 
-// 7.4 Context Sub Type IDs
+// 7.2 Context Sub Type IDs
 //
 // Next-level context in which the ad appears.
 // Again this reflects the primary context, and does not imply no presence of other elements.

native/request/context_type.go → native/context_type.go

@@ -1,10 +1,13 @@
-package request
+package native
 
-// 7.3 Context Type IDs
+// 7.1 Context Type IDs
 //
-// The context in which the ad appears - what type of content is surrounding the ad on the page at a high level.
-// This maps directly to the new Deep Dive on In-Feed Ad Units.
-// This denotes the primary context, but does not imply other content may not exist on the page - for example it's expected that most content platforms have some social components, etc.
+// The context in which the ad appears - what type of content is surrounding the ad on the
+// page at a high level.
+// This maps directly to the new Deep Dive on In-Feed Ad Units. This
+// denotes the primary context, but does not imply other content may not exist on the
+// page - for example it's expected that most content platforms have some social
+// components, etc.
 type ContextType int64
 
 const (

native/request/data_asset_type.go → native/data_asset_type.go

@@ -1,6 +1,6 @@
-package request
+package native
 
-// 7.6 Data Asset Types
+// 7.4  Data Asset Types
 //
 // Below is a list of common asset element types of native advertising at the time of writing this spec.
 // This list is non-exhaustive and intended to be extended by the buyers and sellers as the format evolves.

native/event_tracking_method.go

@@ -0,0 +1,12 @@
+package native
+
+// 7.7 Event Tracking Methods Table
+type EventTrackingMethod int8
+
+const (
+	EventTrackingMethodImage EventTrackingMethod = 1 // Image-pixel tracking - URL provided will be inserted as a 1x1 pixel at the time of the event.
+	EventTrackingMethodJS    EventTrackingMethod = 2 // Javascript-based tracking - URL provided will be inserted as a js tag at the time of the event.
+
+	// 500+ exchangespecific
+	// Could include custom measurement companies such as moat, doubleverify, IAS, etc - in this case additional elements will often be passed
+)

native/event_type.go

@@ -0,0 +1,13 @@
+package native
+
+// 7.6 Event Types Table
+type EventType int8
+
+const (
+	EventTypeImpression      EventType = 1 // Impression
+	EventTypeViewableMRC50   EventType = 2 // Visible impression using MRC definition at 50% in view for 1 second
+	EventTypeViewableMRC100  EventType = 3 // 100% in view for 1 second (ie GroupM standard)
+	EventTypeViewableVideo50 EventType = 4 // Visible impression for video using MRC definition at 50% in view for 2 seconds
+
+	// 500+ exchange-specific
+)

native/request/image_asset_type.go → native/image_asset_type.go

@@ -1,6 +1,6 @@
-package request
+package native
 
-// 7.7 Image Asset Types
+// 7.5 Image Asset Types
 //
 // Below is a list of common image asset element types of native advertising at the time of writing this spec.
 // This list is non-exhaustive and intended to be extended by the buyers and sellers as the format evolves.
@@ -12,12 +12,12 @@ package request
 // They are free to support larger, but the DSP knows that if they have an image of this size it will be accepted.
 // Note that SSPs will be responsible for sizing image to exact size if min-maxheight framework is used; exact size may not be available at bid request time.
 // Width is calculated from the 3 supported aspect ratios.
-// Note we are merging the prior overlapping type 1 and type 2 as just type 1 - to be used for app icon, brand logo, or similar.
+// Note we merged the prior overlapping type 1 and type 2 as just type 1 - to be used for app icon, brand logo, or similar.
 type ImageAssetType int64
 
 const (
 	ImageAssetTypeIcon ImageAssetType = 1 // Icon; Icon image; Optional. Max height: at least 50; aspect ratio: 1:1
-	ImageAssetTypeLogo ImageAssetType = 2 // Logo; Logo image for the brand/app. To be deprecated in future version - use type 1 Icon.
+	ImageAssetTypeLogo ImageAssetType = 2 // Logo; Logo image for the brand/app. Deprecated in version 1.2 - use type 1 Icon.
 
 	// Main; Large image preview for the ad. At least one of 2 size variants required:
 	//   Small Variant:

native/request/layout.go → native/layout.go

@@ -1,8 +1,7 @@
-package request
+package native
 
-// 7.1 Native Layout IDs - To Be Deprecated
-//
-// Layout ID is to be deprecated in a future version and is not suggested for new implementations.
+// 7.1 Native Layout IDs in version 1.1.
+// Deprecated/removed in version 1.2.
 //
 // Below is a list of the core layouts described in the introduction above.
 //

native/native.go

@@ -0,0 +1,5 @@
+// Package native provides OpenRTB Dynamic Native Ads API Specification Version 1.2
+// section 7 Reference Lists/Enumerations types/constants:
+// https://www.iab.com/guidelines/real-time-bidding-rtb-project/
+// https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf
+package native

native/request/placement_type.go → native/placement_type.go

@@ -1,6 +1,6 @@
-package request
+package native
 
-// 7.5 Placement Type IDs
+// 7.3 Placement Type IDs
 //
 // The FORMAT of the ad you are purchasing, separate from the surrounding context
 type PlacementType int64

native/request/README.md

@@ -1,4 +1,4 @@
 # native/request [![GoDoc](https://godoc.org/github.com/mxmCherry/openrtb/native/request?status.svg)](https://godoc.org/github.com/mxmCherry/openrtb/native/request)
 
 [Go](https://golang.org/) implementation of [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API
-Specification Version 1.1](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf) section 4 Native Ad Request Markup Details types.
+Specification Version 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) section 4 Native Ad Request Markup Details types.

native/request/asset.go

@@ -11,7 +11,7 @@ package request
 // To be more explicit, it is the ID of each asset object that maps the response to the request.
 // So if a request for a title object is sent with id 1, then the response containing the title should have an id of 1.
 //
-// New in version 1.1 of the spec, there are recommended sizes/lengths/etc with some of the asset types.
+// Since version 1.1 of the spec, there are recommended sizes/lengths/etc with some of the asset types.
 // The goal for asset requirements standardization is to facilitate adoption of native by DSPs by limiting the diverse types/sizes/requirements of assets they must have available to purchase a native ad impression.
 // While great diversity may exist in publishers, advertisers/DSPs can not be expected to provide infinite headline lengths, thumbnail aspect ratios, etc.
 // While we have not gone as far as creating a single standard, we've honed in on a few options that cover the most common cases.
@@ -50,6 +50,7 @@ type Asset struct {
 	// Description:
 	//   Title object for title assets.
 	//   See TitleObject definition.
+	//   Each asset object may contain only one of title, img, data or video.
 	Title *Title `json:"title,omitempty"`
 
 	// Field:
@@ -61,17 +62,21 @@ type Asset struct {
 	// Description:
 	//   Image object for image assets.
 	//   See ImageObject definition.
+	//   Each asset object may contain only one of title, img, data or video.
 	Img *Image `json:"img,omitempty"`
 
 	// Field:
 	//   video
 	// Scope:
 	//   optional (each asset object may contain only one of title, img, data or video)
 	// Type:
-	//   object - Video object for video assets.
+	//   object
+	// Description:
+	//   Video object for video assets.
 	//   See the Video request object definition.
 	//   Note that in-stream (ie preroll, etc) video ads are not part of Native.
 	//   Native ads may contain a video as the ad creative itself.
+	//   Each asset object may contain only one of title, img, data or video.
 	Video *Video `json:"video,omitempty"`
 
 	// Field:
@@ -83,6 +88,7 @@ type Asset struct {
 	// Description:
 	//   Data object for brand name, description, ratings, prices etc.
 	//   See DataObject definition.
+	//   Each asset object may contain only one of title, img, data or video.
 	Data *Data `json:"data,omitempty"`
 
 	// Field:

native/request/data.go

@@ -1,5 +1,7 @@
 package request
 
+import "github.com/mxmCherry/openrtb/native"
+
 // 4.6 Data Object
 //
 // The Data Object is to be used for all non-core elements of the native unit such as Brand Name, Ratings, Review Count, Stars, Download count, descriptions etc.
@@ -17,7 +19,7 @@ type Data struct {
 	//   Type ID of the element supported by the publisher.
 	//   The publisher can display this information in an appropriate format.
 	//   See Data Asset Types table for commonly used examples.
-	Type DataAssetType `json:"type"`
+	Type native.DataAssetType `json:"type"`
 
 	// Field:
 	//   len

native/request/event_tracker.go

@@ -0,0 +1,41 @@
+package request
+
+import "github.com/mxmCherry/openrtb/native"
+
+// 4.7 Event Trackers Request Object
+//
+// The event trackers object specifies the types of events the bidder can request to be tracked in the bid response, and which types of tracking are available for each event type, and is included as an array in the request.
+type EventTracker struct {
+
+	// Field:
+	//   event
+	// Scope:
+	//   required
+	// Type:
+	//   integer
+	// Description:
+	//   Type of event available for tracking.
+	//   See Event Types table.
+	Event native.EventType `json:"event"`
+
+	// Field:
+	//   methods
+	// Scope:
+	//   required
+	// Type:
+	//   array of integers
+	// Description:
+	//   Array of the types of tracking available for the given event.
+	//   See Event Tracking Methods table
+	Methods []native.EventTrackingMethod `json:"methods"`
+
+	// Field:
+	//   ext
+	// Scope:
+	//   optional
+	// Type:
+	//   object
+	// Description:
+	//   This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification
+	Ext RawJSON `json:"ext,omitempty"`
+}

native/request/image.go

@@ -1,5 +1,7 @@
 package request
 
+import "github.com/mxmCherry/openrtb/native"
+
 // 4.4 Image Object
 //
 // The Image object to be used for all image elements of the Native ad such as Icons, Main Image, etc.
@@ -16,7 +18,7 @@ type Image struct {
 	//   Type ID of the image element supported by the publisher.
 	//   The publisher can display this information in an appropriate format.
 	//   See Table Image Asset Types.
-	Type ImageAssetType `json:"type,omitempty"`
+	Type native.ImageAssetType `json:"type,omitempty"`
 
 	// Field:
 	//   w
@@ -87,6 +89,6 @@ type Image struct {
 	// Type:
 	//   object
 	// Description:
-	// This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification
+	//   This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification
 	Ext RawJSON `json:"ext,omitempty"`
 }