request

package
v9.2.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2017 License: Unlicense Imports: 1 Imported by: 0

README

native/request GoDoc

Go implementation of OpenRTB Dynamic Native Ads API Specification Version 1.1 section 4 Native Ad Request Markup Details types.

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

View Source
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

	// 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

func (m RawJSON) MarshalJSON() ([]byte, error)

MarshalJSON returns m as the JSON encoding of m.

func (*RawJSON) UnmarshalJSON

func (m *RawJSON) UnmarshalJSON(data []byte) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL