diff --git a/native/request/ad_unit.go b/native/request/ad_unit.go new file mode 100644 index 0000000..7a90e8e --- /dev/null +++ b/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. +) diff --git a/native/request/asset.go b/native/request/asset.go new file mode 100644 index 0000000..17551e2 --- /dev/null +++ b/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"` +} diff --git a/native/request/context_sub_type.go b/native/request/context_sub_type.go new file mode 100644 index 0000000..60609da --- /dev/null +++ b/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 +) diff --git a/native/request/context_type.go b/native/request/context_type.go new file mode 100644 index 0000000..2956984 --- /dev/null +++ b/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. +) diff --git a/native/request/data.go b/native/request/data.go new file mode 100644 index 0000000..f7ad486 --- /dev/null +++ b/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"` +} diff --git a/native/request/data_asset_type.go b/native/request/data_asset_type.go new file mode 100644 index 0000000..a13eb19 --- /dev/null +++ b/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 +) diff --git a/native/request/image.go b/native/request/image.go new file mode 100644 index 0000000..224e77d --- /dev/null +++ b/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"` +} diff --git a/native/request/image_asset_type.go b/native/request/image_asset_type.go new file mode 100644 index 0000000..d03033b --- /dev/null +++ b/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 +) diff --git a/native/request/placement_type.go b/native/request/placement_type.go new file mode 100644 index 0000000..4157b42 --- /dev/null +++ b/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 +) diff --git a/native/request/request.go b/native/request/request.go new file mode 100644 index 0000000..2e208ed --- /dev/null +++ b/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"` +} diff --git a/native/request/title.go b/native/request/title.go new file mode 100644 index 0000000..a7e49ff --- /dev/null +++ b/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"` +} diff --git a/native/request/video.go b/native/request/video.go new file mode 100644 index 0000000..3414e62 --- /dev/null +++ b/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"` +}