From 87539cb4dd754ea6ad61a2f71d8cccbd0099b2a3 Mon Sep 17 00:00:00 2001 From: warmans Date: Sat, 9 May 2015 16:06:26 +0100 Subject: [PATCH] Added BidRequest, Banner, Video, Native --- 2.3/rtb/rtb.go | 703 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 702 insertions(+), 1 deletion(-) diff --git a/2.3/rtb/rtb.go b/2.3/rtb/rtb.go index cb1ec82..13dcc37 100644 --- a/2.3/rtb/rtb.go +++ b/2.3/rtb/rtb.go @@ -92,7 +92,6 @@ const ( PMPPrivateAuctionRestricted uint8 = 1 // 1 = bids are restricted to the deals specified and the terms thereof ) - // Optional override of the overall auction type of the bid request, where 1 = First Price, // 2 = Second Price Plus, 3 = the value passed in bidfloor is the agreed upon deal price. Additional // auction types can be defined by the exchange. @@ -105,6 +104,708 @@ const ( // Placeholder for exchange-specific extensions to OpenRTB. type Ext interface{} +// 3.2.1 Object: BidRequest +// The top-level bid request object contains a globally unique bid request or auction ID. This id attribute is +// required as is at least one impression object (Section 3.2.2). Other attributes in this top-level object +// establish rules and restrictions that apply to all impressions being offered. +// +// There are also several subordinate objects that provide detailed data to potential buyers. Among these +// are the Site and App objects, which describe the type of published media in which the impression(s) +// appear. These objects are highly recommended, but only one applies to a given bid request depending +// on whether the media is browser-based web content or a non-browser application, respectively. +type BidRequest struct { + + // Attribute: + // id + // Type: + // string; required + // Description: + // Unique ID of the bid request, provided by the exchange. + ID string `json:"id"` + + // Attribute: + // imp + // Type: + // object array; required + // Description: + // Array of Imp objects (Section 3.2.2) representing the + // impressions offered. At least 1 Imp object is required. + Imp []Imp `json:"imp"` + + // Attribute: + // site + // Type: + // object; recommended + // Description: + // Details via a Site object (Section 3.2.6) about the publisher's + // website. Only applicable and recommended for websites. + Site Site `json:"site"` + + // Attribute: + // app + // Type: + // object; recommended + // Description: + // Details via an App object (Section 3.2.7) about the publisher's + // app (i.e. non-browser applications). Only applicable and recommended for apps. + App App `json:"app"` + + // Attribute: + // device + // Type: + // object; recommended + // Description: + // Details via a Device object (Section 3.2.11) about the user’s device to which the impression will be delivered. + Device Device `json:"device"` + + // Attribute: + // user + // Type: + // object; recommended + // Description: + // Details via a User object (Section 3.2.13) about the human user of the device; the advertising audience. + User User `json:"user"` + + // Attribute: + // test + // Type: + // integer; default 0 + // Description: + // Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode. + Test int8 `json:"test"` + + // Attribute: + // at + // Type: + // integer; default 2 + // Description: + // Auction type, where 1 = First Price, 2 = Second Price Plus. + // Exchange-specific auction types can be defined using values + // greater than 500. + AT int8 `json:"at"` + + // Attribute: + // tmax + // Type: + // integer + // Description: + // Maximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline. + TMax int64 `json:"tmax"` + + // Attribute: + // wseat + // Type: + // string array + // Description: + // Whitelist of buyer seats allowed to bid on this deal. Seat IDs must be + // communicated between bidders and the exchange a priori. Omission implies no seat restrictions. + WSeat []string `json:"wseat"` + + // Attribute: + // allimps + // Type: + // integer; default 0 + // Description: + // Flag to indicate if Exchange can verify that the impressions + // offered represent all of the impressions available in context + // (e.g., all on the web page, all video spots such as pre/mid/post + // roll) to support road-blocking. 0 = no or unknown, 1 = yes, the + // impressions offered represent all that are available. + AllImps int8 `json:"allimps"` + + // Attribute: + // cur + // Type: + // string array + // Description: + // Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if + // the exchange accepts multiple currencies. + Cur []string `json:"cur"` + + // Attribute: + // bcat + // Type: + // string array + // Description: + // Blocked advertiser categories using the IAB content categories. Refer to List 5.1. + BCat []string `json:"bcat"` + + // Attribute: + // badv + // Type: + // string array + // Description: + // Blocked advertiser categories using the IAB content categories. Refer to List 5.1. + BAdv []string `json:"badv"` + + // Attribute: + // regs + // Type: + // object + // Description: + // Blocked advertiser categories using the IAB content categories. Refer to List 5.1. or governmental + // regulations in force for this request. + Regs Regs `json:"regs"` + + // Attribute: + // ext + // Type: + // object + // Description: + // Placeholder for exchange-specific extensions to OpenRTB. + Ext Ext `json:"ext"` +} + +// 3.2.2 Object: Imp +// This object describes an ad placement or impression being auctioned. A single bid request can include +// multiple Imp objects, a use case for which might be an exchange that supports selling all ad positions on +// a given page. Each Imp object has a required ID so that bids can reference them individually. +// +// The presence of Banner (Section 3.2.3), Video (Section 3.2.4), and/or Native (Section 3.2.5) objects +// subordinate to the Imp object indicates the type of impression being offered. The publisher can choose +// one such type which is the typical case or mix them at their discretion. However, any given bid for the +// impression must conform to one of the offered types. +type Imp struct { + + // Attribute: + // id + // Type: + // string; required + // Description: + // A unique identifier for this impression within the context of the bid request (typically, starts + // with 1 and increments. + ID string `json:"id"` + + // Attribute: + // banner + // Type: + // object + // Description: + // A Banner object (Section 3.2.3); required if this impression is + // offered as a banner ad opportunity. + Banner Banner `json:"banner"` + + // Attribute: + // video + // Type: + // object + // Description: + // A Video object (Section 3.2.4); required if this impression is + // offered as a video ad opportunity. + Video Video `json:"video"` + + // Attribute: + // native + // Type: + // object + // Description: + // A Native object (Section 3.2.5); required if this impression is + // offered as a native ad opportunity + Native Native `json:"native"` + + // Attribute: + // displaymanager + // Type: + // string + // Description: + // Name of ad mediation partner, SDK technology, or player + // responsible for rendering ad (typically video or mobile). Used + // by some ad servers to customize ad code by partner. + // Recommended for video and/or apps. + DisplayManager string `json:"displaymanager"` + + // Attribute: + // instl + // Type: + // int; default 0 + // Description: + // 1 = the ad is interstitial or full screen, 0 = not interstitial. + Instl int8 `json:"instl"` + + // Attribute: + // tagid + // Type: + // string + // Description: + // Identifier for specific ad placement or ad tag that was used to + // initiate the auction. This can be useful for debugging of any + // issues, or for optimization by the buyer. + TagID string `json:"tagid"` + + // Attribute: + // bidfloor + // Type: + // float; default 0 + // Description: + // Minimum bid for this impression expressed in CPM. + BidFloor float64 `json:"bidfloor"` + + // Attribute: + // bidfloorcur + // Type: + // string; default “USD” + // Description: + // Currency specified using ISO-4217 alpha codes. This may be + // different from bid currency returned by bidder if this is + // allowed by the exchange. + BidFloorCur float64 `json:"bidfloorcur"` + + // Attribute: + // secure + // Type: + // integer + // Description: + // Flag to indicate if the impression requires secure HTTPS URL + // creative assets and markup, where 0 = non-secure, 1 = secure. + // If omitted, the secure state is unknown, but non-secure HTTP + // support can be assumed. + Secure int8 `json:"secure"` + + // Attribute: + // iframebuster + // Type: + // string array + // Description: + // Array of exchange-specific names of supported iframe busters. + IframeBuster []string `json:"iframebuster"` + + // Attribute: + // pmp + // Type: + // object + // Description: + // A Pmp object (Section 3.2.17) containing any private marketplace deals in effect for this impression. + PMP PMP `json:"pmp"` + + // Attribute: + // ext + // Type: + // object + // Description: + // Placeholder for exchange-specific extensions to OpenRTB. + Ext Ext `json:"ext"` +} + +// 3.2.3 Object: Banner +// This object represents the most general type of impression. Although the term “banner” may have very +// specific meaning in other contexts, here it can be many things including a simple static image, an +// expandable ad unit, or even in-banner video (refer to the Video object in Section 3.2.4 for the more +// generalized and full featured video ad units). An array of Banner objects can also appear within the +// Video to describe optional companion ads defined in the VAST specification. +// +// The presence of a Banner as a subordinate of the Imp object indicates that this impression is offered as +// a banner type impression. At the publisher’s discretion, that same impression may also be offered as +// video and/or native by also including as Imp subordinates the Video and/or Native objects, +// respectively. However, any given bid for the impression must conform to one of the offered types. +type Banner struct { + + // Attribute: + // w + // Type: + // integer; recommended + // Description: + // Width of the impression in pixels. + // If neither wmin nor wmax are specified, this value is an exact + // width requirement. Otherwise it is a preferred width. + W int64 `json:"w"` + + // Attribute: + // h + // Type: + // integer; recommended + // Description: + // Height of the impression in pixels. + // If neither hmin nor hmax are specified, this value is an exact + // height requirement. Otherwise it is a preferred height. + H int64 `json:"h"` + + // Attribute: + // wmax + // Type: + // integer + // Description: + // Maximum width of the impression in pixels. + // If included along with a w value then w should be interpreted + // as a recommended or preferred width. + WMax int64 `json:"wmax"` + + // Attribute: + // hmax + // Type: + // integer + // Description: + // Maximum height of the impression in pixels. + // If included along with an h value then h should be interpreted + // as a recommended or preferred height. + HMax int64 `json:"hmax"` + + // Attribute: + // wmin + // Type: + // integer + // Description: + // Minimum width of the impression in pixels. + // If included along with a w value then w should be interpreted + // as a recommended or preferred width. + WMin int64 `json:"wmin"` + + // Attribute: + // hmin + // Type: + // integer + // Description: + // Minimum height of the impression in pixels. + // If included along with an h value then h should be interpreted + // as a recommended or preferred height. + HMin int64 `json:"hmin"` + + // Attribute: + // id + // Type: + // string + // Description: + // Unique identifier for this banner object. Recommended when + // Banner objects are used with a Video object (Section 3.2.4) to + // represent an array of companion ads. Values usually start at 1 + // and increase with each object; should be unique within an + // impression. + ID string `json:"id"` + + // Attribute: + // btype + // Type: + // integer array + // Description: + // Blocked banner ad types. Refer to List 5.2. + BType []int64 `json:"btype"` + + // Attribute: + // battr + // Type: + // integer array + // Description: + // Blocked creative attributes. Refer to List 5.3. + BAttr []int64 `json:"battr"` + + // Attribute: + // pos + // Type: + // integer + // Description: + // Ad position on screen. Refer to List 5.4 + Pos int64 `json:"pos"` + + // Attribute: + // mimes + // Type: + // string array + // Description: + // Content MIME types supported. Popular MIME types may + // include “application/x-shockwave-flash”, “image/jpg”, and “image/gif”. + MIMEs []string `json:"mimes"` + + // Attribute: + // topframe + // Type: + // integer + // Description: + // Indicates if the banner is in the top frame as opposed to an + // iframe, where 0 = no, 1 = yes. + TopFrame int8 `json:"topframe"` + + // Attribute: + // expdir + // Type: + // integer array + // Description: + // Directions in which the banner may expand. Refer to List 5.5. + ExpDir []int64 `json:"expdir"` + + // Attribute: + // api + // Type: + // integer array + // Description: + // List of supported API frameworks for this impression. Refer to + // List 5.6. If an API is not explicitly listed, it is assumed not to be supported. + API []int64 `json:"api"` + + // Attribute: + // ext + // Type: + // object + // Description: + // Placeholder for exchange-specific extensions to OpenRTB. + Ext Ext `json:"ext"` +} + +// 3.2.4 Object: Video +// This object represents an in-stream video impression. Many of the fields are non-essential for minimally +// viable transactions, but are included to offer fine control when needed. Video in OpenRTB generally +// assumes compliance with the VAST standard. As such, the notion of companion ads is supported by +// optionally including an array of Banner objects (refer to the Banner object in Section 3.2.3) that define +// these companion ads. +// +// The presence of a Video as a subordinate of the Imp object indicates that this impression is offered as a +// video type impression. At the publisher’s discretion, that same impression may also be offered as +// banner and/or native by also including as Imp subordinates the Banner and/or Native objects, +// respectively. However, any given bid for the impression must conform to one of the offered types. +type Video struct { + + // Attribute: + // mimes + // Type: + // string array + // Description: + // Content MIME types supported. Popular MIME types may include “video/x-ms-wmv” for Windows Media and + // “video/x-flv” for Flash Video. + MIMEs []string `json:"mimes"` + + // Attribute: + // minduration + // Type: + // integer; recommended + // Description: + // Minimum video ad duration in seconds. + MinDuration int64 `json:"minduration"` + + // Attribute: + // maxduration + // Type: + // integer; recommended + // Description: + // Maximum video ad duration in seconds. + MaxDuration int64 `json:"maxduration"` + + // Attribute: + // protocol + // Type: + // integer array; DEPRECATED + // Description: + // NOTE: Use of protocols instead is highly recommended. + // Supported video bid response protocol. Refer to List 5.8. At + // least one supported protocol must be specified in either the + // protocol or protocols attribute. + Protocol []int64 `json:"protocol"` + + // Attribute: + // protocols + // Type: + // integer array; recommended + // Description: + // Array of supported video bid response protocols. Refer to List + // 5.8. At least one supported protocol must be specified in + // either the protocol or protocols attribute. + Protocols []int64 `json:"protocols"` + + // Attribute: + // w + // Type: + // integer; recommended + // Description: + // Width of the video player in pixels. + W int64 `json:"w"` + + // Attribute: + // h + // Type: + // integer; recommended + // Description: + // Height of the video player in pixels. + H int64 `json:"h"` + + // Attribute: + // startdelay + // Type: + // integer; recommended + // Description: + // Indicates the start delay in seconds for pre-roll, mid-roll, or + // post-roll ad placements. Refer to List 5.10 for additional + // generic values. + StartDely int64 `json:"startdelay"` + + // Attribute: + // linearity + // Type: + // integer + // Description: + // Indicates if the impression must be linear, nonlinear, etc. If + // none specified, assume all are allowed. Refer to List 5.7. + Linearity int8 `json:"linearity"` + + // Attribute: + // sequence + // Type: + // integer + // Description: + // If multiple ad impressions are offered in the same bid request, + // the sequence number will allow for the coordinated delivery + // of multiple creatives. + Sequence int64 `json:"sequence"` + + // Attribute: + // sequence + // Type: + // integer array + // Description: + // Blocked creative attributes. Refer to List 5.3. + BAttr []int64 `json:"battr"` + + // Attribute: + // maxextended + // Type: + // integer + // Description: + // Maximum extended video ad duration if extension is allowed. + // If blank or 0, extension is not allowed. If -1, extension is + // allowed, and there is no time limit imposed. If greater than 0, + // then the value represents the number of seconds of extended + // play supported beyond the maxduration value. + MaxExtended int64 `json:"maxextended"` + + // Attribute: + // minbitrate + // Type: + // integer + // Description: + // Minimum bit rate in Kbps. Exchange may set this dynamically + // or universally across their set of publishers. + MinBitRate int64 `json:"minbitrate"` + + // Attribute: + // maxbitrate + // Type: + // integer + // Description: + // Maximum bit rate in Kbps. Exchange may set this dynamically + // or universally across their set of publishers. + MaxBitRate int64 `json:"maxbitrate"` + + // Attribute: + // boxingallowed + // Type: + // integer; default 1 + // Description: + // Indicates if letter-boxing of 4:3 content into a 16:9 window is + // allowed, where 0 = no, 1 = yes. + BoxingAllowed int8 `json:"boxingallowed"` + + // Attribute: + // playbackmethod + // Type: + // integer array + // Description: + // Allowed playback methods. If none specified, assume all are + // allowed. Refer to List 5.9. + PlaybackMethod []int64 `json:"playbackmethod"` + + // Attribute: + // delivery + // Type: + // integer array + // Description: + // Supported delivery methods (e.g., streaming, progressive). If + // none specified, assume all are supported. Refer to List 5.13. + Delivery []int64 `json:"delivery"` + + // Attribute: + // pos + // Type: + // integer + // Description: + // Ad position on screen. Refer to List 5.4 + Pos int64 `json:"pos"` + + CompanionAd []Banner `json:"companionad"` + + // Attribute: + // api + // Type: + // integer array + // Description: + // List of supported API frameworks for this impression. Refer to + // List 5.6. If an API is not explicitly listed, it is assumed not to be supported. + API []int64 `json:"api"` + + // Attribute: + // companiontype + // Type: + // integer array + // Description: + // Supported VAST companion ad types. Refer to List 5.12. + // Recommended if companion Banner objects are included via + // the companionad array. + CompanionType []int64 `json:"companiontype"` + + // Attribute: + // ext + // Type: + // object + // Description: + // Placeholder for exchange-specific extensions to OpenRTB. + Ext Ext `json:"ext"` +} + +// 3.2.5 Object: Native +// This object represents a native type impression. Native ad units are intended to blend seamlessly into +// the surrounding content (e.g., a sponsored Twitter or Facebook post). As such, the response must be +// well-structured to afford the publisher fine-grained control over rendering. +// The Native Subcommittee has developed a companion specification to OpenRTB called the Native Ad +// +// Specification. It defines the request parameters and response markup structure of native ad units. This +// object provides the means of transporting request parameters as an opaque string so that the specific +// parameters can evolve separately under the auspices of the Native Ad Specification. Similarly, the ad +// markup served will be structured according to that specification. +// +// The presence of a Native as a subordinate of the Imp object indicates that this impression is offered as +// a native type impression. At the publisher’s discretion, that same impression may also be offered as +// banner and/or video by also including as Imp subordinates the Banner and/or Video objects, +// respectively. However, any given bid for the impression must conform to one of the offered types. +type Native struct { + + // Attribute: + // request + // Type: + // string; required + // Description: + // Request payload complying with the Native Ad Specification. + request string `json:"request"` + + // Attribute: + // ver + // Type: + // string; recommended + // Description: + // Version of the Native Ad Specification to which request + // complies; highly recommended for efficient parsing + Ver string `json:"ver"` + + // Attribute: + // api + // Type: + // integer array + // Description: + // List of supported API frameworks for this impression. Refer to + // List 5.6. If an API is not explicitly listed, it is assumed not to be supported. + API []int64 `json:"api"` + + // Attribute: + // sequence + // Type: + // integer array + // Description: + // Blocked creative attributes. Refer to List 5.3. + BAttr []int64 `json:"battr"` + + // Attribute: + // ext + // Type: + // object + // Description: + // Placeholder for exchange-specific extensions to OpenRTB. + Ext Ext `json:"ext"` +} + // 3.2.6 Object: Site // This object should be included if the ad supported content is a website as opposed to a non-browser // application. A bid request must not contain both a Site and an App object. At a minimum, it is useful