request

README

native1/request

OpenRTB Dynamic Native Ads API 1.2 section "4 Native Ad Request Markup Details" types for Go programming language

Documentation

Overview

Package request provides OpenRTB Native 1.2 request types (section "4 Native Ad Request Markup Details")

https://iabtechlab.com/standards/openrtb-native/ https://iabtechlab.com/wp-content/uploads/2016/07/OpenRTB-Native-Ads-Specification-Final-1.2.pdf

Index

• type Asset
• type Data
• type EventTracker
• type Image
• type Request
• type Title
• type Video

Types

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.
	//   Each asset object may contain only one of title, img, data or video.
	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.
	//   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
	// 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:
	//   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.
	//   Each asset object may contain only one of title, img, data or video.
	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 json.RawMessage `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.

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 native1 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 native1 inventory.

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 native1.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"`
}

4.6 Data Object

The Data Object is to be used for all non-core elements of the native1 unit such as Brand Name, Ratings, Review Count, Stars, Download count, descriptions etc. It is also generic for future native1 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 EventTracker

type EventTracker struct {

	// Field:
	//   event
	// Scope:
	//   required
	// Type:
	//   integer
	// Description:
	//   Type of event available for tracking.
	//   See Event Types table.
	Event native1.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 []native1.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 json.RawMessage `json:"ext,omitempty"`
}

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 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 native1.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"`
}

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 Request

type Request struct {

	// Field:
	//   ver
	// Scope:
	//   optional
	// Type:
	//   string
	// Default:
	//   1.2
	// Description:
	//   Version of the Native Markup version in use.
	Ver string `json:"ver,omitempty"`

	// Field:
	//   layout
	// Scope:
	//   recommended in 1.0, deprecated/removed in 1.2
	// Type:
	//   integer
	// Description:
	//   The Layout ID of the native1 ad unit.
	//   See the Table of Layout IDs below.
	Layout native1.Layout `json:"layout,omitempty"`

	// Field:
	//   adunit
	// Scope:
	//   recommended in 1.0, deprecated/removed in 1.2
	// Type:
	//   integer
	// Description:
	//   The Ad unit ID of the native1 ad unit.
	//   See Table of Ad Unit IDs below for a list of supported core ad units.
	AdUnit native1.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 native1.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 native1.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 native1.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:
	//   aurlsupport
	// Scope:
	//   optional
	// Type:
	//   int
	// Default:
	//   0
	// Description:
	//   Whether the supply source / impression supports returning an assetsurl instead of an asset object.
	//   0 or the absence of the field indicates no such support.
	AURLSupport int8 `json:"aurlsupport,omitempty"`

	// Field:
	//   durlsupport
	// Scope:
	//   optional
	// Type:
	//   int
	// Default:
	//   0
	// Description:
	//   Whether the supply source / impression supports returning a dco url instead of an asset object.
	//   0 or the absence of the field indicates no such support.
	//   Beta feature.
	DURLSupport int8 `json:"durlsupport,omitempty"`

	// Field:
	//   eventtrackers
	// Scope:
	//   optional
	// Type:
	//   array of objects
	// Description:
	//   Specifies what type of event tracking is supported - see Event Trackers Request Object
	EventTrackers []EventTracker `json:"eventtrackers,omitempty"`

	// Field:
	//   privacy
	// Scope:
	//   recommended
	// Type:
	//   integer
	// Default:
	//   0
	// Description:
	//   Set to 1 when the native1 ad supports buyer-specific privacy notice.
	//   Set to 0 (or field absent) when the native1 ad doesn’t support custom privacy links or if support is unknown.
	Privacy int8 `json:"privacy,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"`
}

4.1 Native Markup Request Object

The Native Object defines the native1 advertising opportunity available for bid via this bid request. It will be included as a JSON-encoded string in the bid request’s imp.native1 field or as a direct JSON object, depending on the choice of the exchange. While OpenRTB 2.x officially supports only JSON-encoded strings, many exchanges have implemented a formal object. Check with your integration docs.

Note: Prior to VERSION 1.1, the specification could be interpreted as requiring the native1 request to have a root node with a single field “native” that would contain the object above as its value. The Native Markup Request Object specified above is now the root object.

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 json.RawMessage `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 native1 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 []native1.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 json.RawMessage `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.