Documentation
¶
Overview ¶
Package request provides OpenRTB Dynamic Native Ads API Specification Version 1.1 section 4 Native Ad Request Markup Details types: https://www.iab.com/guidelines/real-time-bidding-rtb-project/ https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf
Index ¶
Constants ¶
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. )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AdUnit ¶
type AdUnit int64
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.
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” )
type Asset ¶
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 *Title `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 *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.
// 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 *Video `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 *Data `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 RawJSON `json:"ext,omitempty"`
}
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 ContextSubType ¶
type ContextSubType int64
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).
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 ContextSubTypeAppStore ContextSubType = 31 // Application store/marketplace ContextSubTypeProductReview ContextSubType = 32 // Product reviews site primarily (which may sell product secondarily) )
type ContextType ¶
type ContextType int64
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.
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. )
type Data ¶
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 RawJSON `json:"ext,omitempty"`
}
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 DataAssetType ¶
type DataAssetType int64
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.
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 Image ¶
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 uint64 `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 uint64 `json:"wmin,omitempty"`
// Field:
// h
// Scope:
// optional
// Type:
// integer
// Description:
// Height of the image in pixels.
H uint64 `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 uint64 `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 RawJSON `json:"ext,omitempty"`
}
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 ImageAssetType ¶
type ImageAssetType int64
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.
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 )
type Layout ¶
type Layout int64
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.
Below is a list of the core layouts described in the introduction above.
An implementing exchange may not support all asset variants or introduce new ones unique to that system.
const ( LayoutContentWall Layout = 1 // Content Wall LayoutAppWall Layout = 2 // App Wall LayoutNewsFeed Layout = 3 // News Feed LayoutChatList Layout = 4 // Chat List LayoutCarousel Layout = 5 // Carousel LayoutContentStream Layout = 6 // Content Stream LayoutGrid Layout = 7 // Grid adjoining the content )
type PlacementType ¶
type PlacementType int64
7.5 Placement Type IDs
The FORMAT of the ad you are purchasing, separate from the surrounding context
type Protocol ¶
type Protocol int8
5.8 Protocols (from OpenRTB spec 2.5)
Options for the various bid response protocols that could be supported by an exchange.
const ( ProtocolVAST10 Protocol = 1 // VAST 1.0 ProtocolVAST20 Protocol = 2 // VAST 2.0 ProtocolVAST30 Protocol = 3 // VAST 3.0 ProtocolVAST10Wrapper Protocol = 4 // VAST 1.0 Wrapper ProtocolVAST20Wrapper Protocol = 5 // VAST 2.0 Wrapper ProtocolVAST30Wrapper Protocol = 6 // VAST 3.0 Wrapper ProtocolVAST40 Protocol = 7 // VAST 4.0 ProtocolVAST40Wrapper Protocol = 8 // VAST 4.0 Wrapper ProtocolDAAST10 Protocol = 9 // DAAST 1.0 ProtocolDAAST10Wrapper Protocol = 10 // DAAST 1.0 Wrapper )
type RawJSON ¶
type RawJSON []byte
RawJSON is a raw encoded JSON value. It implements encoding/json.Marshaler and encoding/json.Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding.
Basically, it's just a copy of encoding/json.RawMessage type, but with more convenient non-pointer encoding.
HEADS UP: this will be replaced with json.RawMessage when Go 1.10 is out.
func (RawJSON) MarshalJSON ¶
MarshalJSON returns m as the JSON encoding of m.
func (*RawJSON) UnmarshalJSON ¶
UnmarshalJSON sets *m to a copy of data.
type Request ¶
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 Layout `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 RawJSON `json:"ext,omitempty"`
}
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 Title ¶
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 RawJSON `json:"ext,omitempty"`
}
4.3 Title Object
The Title object is to be used for title element of the Native ad.
type Video ¶
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 []Protocol `json:"protocols"`
// 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"`
}
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.