wip - native

native/request/ad_unit.go

@@ -0,0 +1,22 @@
+package request
+
+// 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.
+//
+// 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.
+//
+// An implementing exchange may not support all asset variants or introduce new ones unique to that system.
+type AdUnit int64
+
+const (
+	AdUnitPaidSearch           AdUnit = 1 // Paid Search Units
+	AdUnitRecommendationWidget AdUnit = 2 // Recommendation Widgets
+	AdUnitPromotedListing      AdUnit = 3 // Promoted Listings
+	AdUnitInAd                 AdUnit = 4 // In-Ad (IAB Standard) with Native Element Units
+	AdUnitCustom               AdUnit = 5 // Custom /”Can’t Be Contained”
+
+	// 500+ Reserved for Exchange specific formats.
+)

native/request/asset.go

@@ -0,0 +1,99 @@
+package request
+
+import "encoding/json"
+
+// 4.2 Asset Object
+//
+// The main container object for each asset requested or supported by Exchange on behalf of the rendering client.
+// Any object that is required is to be flagged as such.
+// Only one of the {title,img,video,data} objects should be present in each object.
+// All others should be null/absent.
+// The id is to be unique within the AssetObject array so that the response can be aligned.
+//
+// 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.
+// 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.
+// SSPs can deviate from these standards, but should understand they may limit applicable DSP demand by doing so.
+// DSPs should feel confident that if they support these standards they'll be able to access most native inventory.
+type Asset struct {
+	// Field:
+	//   id
+	// Scope:
+	//   required
+	// Type:
+	//   int
+	// Description:
+	//   Unique asset ID, assigned by exchange.
+	//   Typically a counter for the array.
+	ID int64 `json:"id"`
+
+	// Field:
+	//   required
+	// Scope:
+	//   optional
+	// Type:
+	//   int
+	// Default:
+	//   0
+	// Description:
+	//   Set to 1 if asset is required (exchange will not accept a bid without it)
+	Required int8 `json:"required,omitempty"`
+
+	// Field:
+	//   title
+	// Scope:
+	//   recommended (each asset object may contain only one of title, img, data or video)
+	// Type:
+	//   object
+	// Description:
+	//   Title object for title assets.
+	//   See TitleObject definition.
+	Title interface{} `json:"title,omitempty"`
+
+	// Field:
+	//   img
+	// Scope:
+	//   recommended (each asset object may contain only one of title, img, data or video)
+	// Type:
+	//   object
+	// Description:
+	//   Image object for image assets.
+	//   See ImageObject definition.
+	Img interface{} `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.
+	//   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.
+	Video interface{} `json:"video,omitempty"`
+
+	// Field:
+	//   data
+	// Scope:
+	//   recommended (each asset object may contain only one of title, img, data or video)
+	// Type:
+	//   object
+	// Description:
+	//   Data object for brand name, description, ratings, prices etc.
+	//   See DataObject definition.
+	Data interface{} `json:"data,omitempty"`
+
+	// 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 json.RawMessage `json:"ext,omitempty"`
+}

native/request/context_sub_type.go

@@ -0,0 +1,26 @@
+package request
+
+// 7.4 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.
+// For example, an article is likely to contain images but is still first and foremost an article.
+// SubType should only be combined with the primary context type as indicated (ie for a context type of 1, only context subtypes that start with 1 are valid).
+type ContextSubType int64
+
+const (
+	ContextSubTypeGeneral       ContextSubType = 10 // General or mixed content.
+	ContextSubTypeArticle       ContextSubType = 11 // Primarily article content (which of course could include images, etc as part of the article)
+	ContextSubTypeVideo         ContextSubType = 12 // Primarily video content
+	ContextSubTypeAudio         ContextSubType = 13 //  Primarily audio content
+	ContextSubTypeImage         ContextSubType = 14 // Primarily image content
+	ContextSubTypeUserGenerated ContextSubType = 15 // User-generated content - forums, comments, etc
+	ContextSubTypeSocial        ContextSubType = 20 // General social content such as a general social network
+	ContextSubTypeEmail         ContextSubType = 21 // Primarily email content
+	ContextSubTypeChat          ContextSubType = 22 // Primarily chat/IM content
+	ContextSubTypeSelling       ContextSubType = 30 // Content focused on selling products, whether digital or physical
+	ContextSubTypeMarketplace   ContextSubType = 31 // Application store/marketplace
+	ContextSubTypeProductReview ContextSubType = 32 // Product reviews site primarily (which may sell product secondarily)
+
+	// 500+ To be defined by the exchange
+)

native/request/context_type.go

@@ -0,0 +1,16 @@
+package request
+
+// 7.3 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.
+type ContextType int64
+
+const (
+	ContextTypeContent ContextType = 1 // Content-centric context such as newsfeed, article, image gallery, video gallery, or similar.
+	ContextTypeSocial  ContextType = 2 // Social-centric context such as social network feed, email, chat, or similar.
+	ContextTypeProduct ContextType = 3 // Product context such as product listings, details, recommendations, reviews, or similar.
+
+	// 500+ To be defined by the exchange.
+)

native/request/data.go

@@ -0,0 +1,43 @@
+package request
+
+import "encoding/json"
+
+// 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.
+// It is also generic for future native elements not contemplated at the time of the writing of this document.
+// In some cases, additional recommendations are also included in the Data Asset Types table.
+type Data struct {
+
+	// Field:
+	//   type
+	// Scope:
+	//   required
+	// Type:
+	//   integer
+	// Description:
+	//   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"`
+
+	// Field:
+	//   len
+	// Scope:
+	//   optional
+	// Type:
+	//   integer
+	// Description:
+	//   Maximum length of the text in the element’s response.
+	Len int64 `json:"len,omitempty"`
+
+	// 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 json.RawMessage `json:"ext,omitempty"`
+}

native/request/data_asset_type.go

@@ -0,0 +1,154 @@
+package request
+
+// 7.6 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.
+//
+// An implementing exchange may not support all asset variants or introduce new ones unique to that system.
+type DataAssetType int64
+
+const (
+	// Type ID:
+	//   1
+	// Name:
+	//   sponsored
+	// Description:
+	//   Sponsored By message where response should contain the brand name of the sponsor.
+	// Format:
+	//   text
+	// Recommendations:
+	//   Required. Max 25 or longer
+	DataAssetTypeSponsored DataAssetType = 1
+
+	// Type ID:
+	//   2
+	// Name:
+	//   desc
+	// Description:
+	//   Descriptive text associated with the product or service being advertised.
+	//   Longer length of text in response may be truncated or ellipsed by th exchange.
+	// Format:
+	//   text
+	// Recommendations:
+	//   Recommended. Max 140 or longer.
+	DataAssetTypeDesc DataAssetType = 2
+
+	// Type ID:
+	//   3
+	// Name:
+	//   rating
+	// Description:
+	//   Rating of the product being offered to the user.
+	//   For example an app’s rating in an app store from 0-5.
+	// Format:
+	//   number formatted as string
+	// Recommendations:
+	//   Optional. 0-5 integer formatted as string.
+	DataAssetTypeRating DataAssetType = 3
+
+	// Type ID:
+	//   4
+	// Name:
+	//   likes
+	// Description:
+	//   Number of social ratings or “likes” of the product being offered to the user.
+	// Format:
+	//   number formatted as string
+	DataAssetTypeLikes DataAssetType = 4
+
+	// Type ID:
+	//   5
+	// Name:
+	//   downloads
+	// Description:
+	//   Number downloads/installs of this product
+	// Format:
+	//   number formatted as string
+	DataAssetTypeDownloads DataAssetType = 5
+
+	// Type ID:
+	//   6
+	// Name:
+	//   price
+	// Description:
+	//   Price for product / app / in-app purchase.
+	//   Value should include currency symbol in localised format.
+	// Format:
+	//   number formatted as string
+	DataAssetTypePrice DataAssetType = 6
+
+	// Type ID:
+	//   7
+	// Name:
+	//   saleprice
+	// Description:
+	//   Sale price that can be used together with price to indicate a discounted price compared to a regular price.
+	//   Value should include currency symbol in localised format.
+	// Format:
+	//   number formatted as string
+	DataAssetTypeSalePrice DataAssetType = 7
+
+	// Type ID:
+	//   8
+	// Name:
+	//   phone
+	// Description:
+	//   Phone number formatted
+	// Format:
+	//   string
+	DataAssetTypePhone DataAssetType = 8
+
+	// Type ID:
+	//   9
+	// Name:
+	//   address
+	// Description:
+	//   Address
+	// Format:
+	//   text
+	DataAssetTypeAddress DataAssetType = 9
+
+	// Type ID:
+	//   10
+	// Name:
+	//   desc2
+	// Description:
+	//   Additional descriptive text associated with the product or service being advertised
+	// Format:
+	//   text
+	DataAssetTypeDesc2 DataAssetType = 10
+
+	// Type ID:
+	//   11
+	// Name:
+	//   displayurl
+	// Description:
+	//   Display URL for the text ad.
+	//   To be used when sponsoring entity doesn’t own the content.
+	//   IE sponsored by BRAND on SITE (where SITE is transmitted in this field).
+	// Format:
+	//   text
+	DataAssetTypeDispayURL DataAssetType = 11
+
+	// Type ID:
+	//   12
+	// Name:
+	//   ctatext
+	// Dewscription:
+	//   CTA description - descriptive text describing a ‘call to action’ button for the destination URL.
+	// Format:
+	//   text
+	// Recommendations:
+	//   Optional. Max 15 or longer.
+	DataAssetTypeCTAText DataAssetType = 12
+
+	// Type ID:
+	//   500+
+	// Name:
+	//   XXX
+	// Description:
+	//   Reserved for Exchange specific usage numbered above 500
+	// Format:
+	//   Unknown
+)

native/request/image.go

@@ -0,0 +1,94 @@
+package request
+
+import "encoding/json"
+
+// 4.4 Image Object
+//
+// The Image object to be used for all image elements of the Native ad such as Icons, Main Image, etc.
+// Recommended sizes and aspect ratios are included in the Image Asset Types section.
+type Image struct {
+
+	// Field:
+	//   type
+	// Scope:
+	//   optional
+	// Type:
+	//   integer
+	// Description:
+	//   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"`
+
+	// Field:
+	//   w
+	// Scope:
+	//   optional
+	// Type:
+	//   integer
+	// Description:
+	//   Width of the image in pixels.
+	W int64 `json:"w,omitempty"`
+
+	// Field:
+	//   wmin
+	// Scope:
+	//   recommended
+	// Type:
+	//   integer
+	// Description:
+	//   The minimum requested width of the image in pixels.
+	//   This option should be used for any rescaling of images by the client.
+	//   Either w or wmin should be transmitted.
+	//   If only w is included, it should be considered an exact requirement.
+	WMin int64 `json:"wmin,omitempty"`
+
+	// Field:
+	//   h
+	// Scope:
+	//   optional
+	// Type:
+	//   integer
+	// Description:
+	//   Height of the image in pixels.
+	H int64 `json:"h,omitempty"`
+
+	// Field:
+	//   hmin
+	// Scope:
+	//   recommended
+	// Type:
+	//   integer
+	// Description:
+	// The minimum requested height of the image in pixels.
+	// This option should be used for any rescaling of images by the client.
+	// Either h or hmin should be transmitted.
+	// If only h is included, it should be considered an exact requirement.
+	HMin int64 `json:"hmin,omitempty"`
+
+	// Field:
+	//   mimes
+	// Scope:
+	//   optional
+	// Type:
+	//   array of strings
+	// Default:
+	//   All types allowed
+	// Description:
+	//   Whitelist of content MIME types supported.
+	//   Popular MIME types include, but are not limited to “image/jpg” “image/gif”.
+	//   Each implementing Exchange should have their own list of supported types in the integration docs.
+	//   See Wikipedia's MIME page for more information and links to all IETF RFCs.
+	//   If blank, assume all types are allowed.
+	MIMEs []string `json:"mimes,omitempty"`
+
+	// 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 json.RawMessage `json:"ext,omitempty"`
+}

native/request/image_asset_type.go

@@ -0,0 +1,34 @@
+package request
+
+// 7.7 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.
+//
+// An implementing exchange may not support all asset variants or may introduce new ones unique to that system.
+//
+// In order to facilitate adoption, recommendations are made for both minimum sizes and aspect ratios.
+// We speak here of 'minimum maximum height' or ‘max height of at least’, which means the SSP should support a max height of at least this value.
+// 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.
+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.
+
+	// Main; Large image preview for the ad. At least one of 2 size variants required:
+	//   Small Variant:
+	//     max height: at least 200
+	//     max width: at least 200, 267, or 382
+	//     aspect ratio: 1:1, 4:3, or 1.91:1
+	//   Large Variant:
+	//     max height: at least 627
+	//     max width: at least 627, 836, or 1198
+	//     aspect ratio: 1:1, 4:3, or 1.91:1
+	ImageAssetTypeMain ImageAssetType = 3
+
+	// 500+ XXX; Reserved for Exchange specific usage numbered above 500. No recommendations
+)

native/request/placement_type.go

@@ -0,0 +1,15 @@
+package request
+
+// 7.5 Placement Type IDs
+//
+// The FORMAT of the ad you are purchasing, separate from the surrounding context
+type PlacementType int8
+
+const (
+	PlacementTypeFeed                 = 1 // In the feed of content - for example as an item inside the organic feed/grid/listing/carousel.
+	PlacementTypeAtomicContentUnit    = 2 // In the atomic unit of the content - IE in the article page or single image page
+	PlacementTypeOutsideCoreContent   = 3 // Outside the core content - for example in the ads section on the right rail, as a banner-style placement near the content, etc.
+	PlacementTypeRecommendationWidget = 4 // Recommendation widget, most commonly presented below the article content.
+
+	// 500+ To be defined by the exchange
+)

native/request/request.go

@@ -0,0 +1,128 @@
+package request
+
+import "encoding/json"
+
+// 4.1 Native Markup Request Object
+//
+// The Native Object defines the native advertising opportunity available for bid via this bid request.
+// It will be included as a JSON-encoded string in the bid request’s imp.native field or as a direct JSON object, depending on the choice of the exchange.
+// While OpenRTB 2.3/2.4 supports only JSON-encoded strings, many exchanges have implemented a formal object.
+// Check with your integration docs.
+//
+// The Default column dictates how optional parameters should be interpreted if explicit values are not provided.
+type Request struct {
+
+	// Field:
+	//   ver
+	// Scope:
+	//   optional
+	// Type:
+	//   string
+	// Default:
+	//   1.1
+	// Description:
+	//   Version of the Native Markup version in use.
+	Ver string `json:"ver,omitempty"`
+
+	// Field:
+	//   layout
+	// Scope:
+	//   recommended in 1.0, to be deprecated
+	// Type:
+	//   integer
+	// Description:
+	//   The Layout ID of the native ad unit.
+	//   See the Table of Layout IDs below.
+	Layout int8 `json:"layout,omitempty"`
+
+	// Field:
+	//   adunit
+	// Scope:
+	//   recommended in 1.0, to be deprecated
+	// Type:
+	//   integer
+	// Description:
+	//   The Ad unit ID of the native ad unit.
+	//   See Table of Ad Unit IDs below for a list of supported core ad units.
+	AdUnit AdUnit `json:"adunit,omitempty"`
+
+	// Field:
+	//   context
+	// Scope:
+	//   recommended
+	// Type:
+	//   integer
+	// Description:
+	//   The context in which the ad appears.
+	//   See Table of Context IDs below for a list of supported context types.
+	Context ContextType `json:"context,omitempty"`
+
+	// Field:
+	//   contextsubtype
+	// Scope:
+	//   optional
+	// Type:
+	//   integer
+	// Description:
+	//   A more detailed context in which the ad appears.
+	//   See Table of Context SubType IDs below for a list of supported context subtypes.
+	ContextSubType ContextSubType `json:"contextsubtype,omitempty"`
+
+	// Field:
+	//   plcmttype
+	// Scope:
+	//   recommended
+	// Type:
+	//   integer
+	// Description:
+	//   The design/format/layout of the ad unit being offered.
+	//   See Table of Placement Type IDs below for a list of supported placement types.
+	PlcmtType PlacementType `json:"plcmttype,omitempty"`
+
+	// Field:
+	//   plcmtcnt
+	// Scope:
+	//   optional
+	// Type:
+	//   integer
+	// Default:
+	//   1
+	// Description:
+	//   The number of identical placements in this Layout.
+	//   Refer Section 8.1 Multiplacement Bid Requests for further detail.
+	PlcmtCnt int64 `json:"plcmtcnt,omitempty"`
+
+	// Field:
+	//   seq
+	// Scope:
+	//   optional
+	// Type:
+	//   integer
+	// Default:
+	//   0
+	// Description:
+	//   0 for the first ad, 1 for the second ad, and so on.
+	//   Note this would generally NOT be used in combination with plcmtcnt - either you are auctioning multiple identical placements (in which case plcmtcnt>1, seq=0) or you are holding separate auctions for distinct items in the feed (in which case plcmtcnt=1, seq=>=1)
+	Seq int64 `json:"seq,omitempty"`
+
+	// Field:
+	//   assets
+	// Scope:
+	//   required
+	// Type:
+	//   array of objects
+	// Description:
+	//   An array of Asset Objects.
+	//   Any bid response must comply with the array of elements expressed in the bid request.
+	Assets []Asset `json:"assets"`
+
+	// 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 json.RawMessage `json:"ext,omitempty"`
+}

native/request/title.go

@@ -0,0 +1,29 @@
+package request
+
+import "encoding/json"
+
+// 4.3 Title Object
+//
+// The Title object is to be used for title element of the Native ad.
+type Title struct {
+	// Field:
+	//   len
+	// Scope:
+	//   required
+	// Type:
+	//   integer
+	// Description:
+	//   Maximum length of the text in the title element.
+	//   Recommended to be 25, 90, or 140.
+	Len int64 `json:"len"`
+
+	// 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 json.RawMessage `json:"ext,omitempty"`
+}

native/request/video.go

@@ -0,0 +1,65 @@
+package request
+
+import "encoding/json"
+
+// 4.5 Video Object
+//
+// The video object to be used for all video elements supported in the Native Ad.
+// This corresponds to the Video object of OpenRTB.
+// Exchange implementers can impose their own specific restrictions.
+// Here are the required attributes of the Video Object.
+// For optional attributes please refer to OpenRTB.
+type Video struct {
+	// Field:
+	//   mimes
+	// Scope:
+	//   required
+	// Type:
+	//   array of string
+	// Description:
+	//   Content MIME types supported.
+	//   Popular MIME types include,but are not limited to “video/x-mswmv” for Windows Media, and “video/x-flv” for Flash Video, or “video/mp4”.
+	//   Note that native frequently does not support flash.
+	MIMEs []string `json:"mimes"`
+
+	// Field:
+	//   minduration
+	// Scope:
+	//   required
+	// Type:
+	//   integer
+	// Description:
+	//   Minimum video ad duration in seconds.
+	MinDuration int64 `json:"minduration"`
+
+	// Field:
+	//   maxduration
+	// Scope:
+	//   required
+	// Type:
+	//   integer
+	// Description:
+	//   Maximum video ad duration in seconds.
+	MaxDuration int64 `json:"maxduration"`
+
+	// Field:
+	//   protocols
+	// Scope:
+	//   required
+	// Type:
+	//   array of integers
+	// Description:
+	//   An array of video protocols the publisher can accept in the bid response.
+	// See OpenRTB Table ‘Video Bid Response Protocols’ for a list of possible values.
+	Protocols []int8 `json:"protocols"` // TODO!!!
+
+	// 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 json.RawMessage `json:"ext,omitempty"`
+}