diff --git a/.travis.yml b/.travis.yml index de1668a..ea07370 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,5 +1,5 @@ language: go go: - - 1.8.x + - 1.9.x - 1.x diff --git a/README.md b/README.md index df66d40..329cacf 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ # openrtb [![GoDoc](https://godoc.org/github.com/mxmCherry/openrtb?status.svg)](https://godoc.org/github.com/mxmCherry/openrtb) [![Build Status](https://travis-ci.org/mxmCherry/openrtb.svg?branch=master)](https://travis-ci.org/mxmCherry/openrtb) -[OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [v2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) types for Go programming language (Golang) +[OpenRTB](https://iabtechlab.com/standards/openrtb/), [AdCOM](https://iabtechlab.com/standards/openmedia) and [OpenRTB Dynamic Native Ads](https://iabtechlab.com/standards/openrtb-native/) types for [Go programming language](https://golang.org/) -Also includes [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API Specification Version 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) types: -- [4 Native Ad Request Markup Details](native/request/) -- [5 Native Ad Response Markup Details](native/response/) -- [7 Reference Lists/Enumerations](native/) +- [openrtb2](openrtb2/) - [OpenRTB](https://iabtechlab.com/standards/openrtb/) [2.5](https://iabtechlab.com/wp-content/uploads/2016/07/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) +- [openrtb3](openrtb3/) - [OpenRTB](https://iabtechlab.com/standards/openrtb/) [3.0](https://github.com/InteractiveAdvertisingBureau/openrtb) +- [adcom1](adcom1/) - [AdCOM](https://iabtechlab.com/standards/openmedia/) [1.0](https://github.com/InteractiveAdvertisingBureau/AdCOM) +- [native1](native1/) - [OpenRTB Dynamic Native Ads API](https://iabtechlab.com/standards/openrtb-native/) [1.2](https://iabtechlab.com/wp-content/uploads/2016/07/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) **Requires Go 1.8+** @@ -13,14 +13,25 @@ Go 1.8+ is needed for proper `Ext json.RawMessage` marshaling: non-pointer `json This library uses `json.RawMessage` since [v10.0.0](https://github.com/mxmCherry/openrtb/releases/tag/v10.0.0). +This library is tested with Go 1.9+ since [v12.0.0](https://github.com/mxmCherry/openrtb/releases/tag/v12.0.0). + # Using ```bash -go get -u "github.com/mxmCherry/openrtb" +go get -u "github.com/mxmCherry/openrtb/..." ``` ```go -import "github.com/mxmCherry/openrtb" +import ( + openrtb2 "github.com/mxmCherry/openrtb/openrtb2" + + openrtb3 "github.com/mxmCherry/openrtb/openrtb3" + adcom1 "github.com/mxmCherry/openrtb/adcom1" + + native1 "github.com/mxmCherry/openrtb/native1" + nreq "github.com/mxmCherry/openrtb/native1/request" + nres "github.com/mxmCherry/openrtb/native1/response" +) ``` This repo follows [semver](http://semver.org/) - see [releases](https://github.com/mxmCherry/openrtb/releases). @@ -37,14 +48,13 @@ Master always contains latest code, so better use some package manager to vendor - Key types should be chosen according to OpenRTB specification (attribute types) - Numeric types: - `int8` - short enums (with values <= 127), boolean-like attributes (like `BidRequest.test`) - - `int64` - time, duration, length, unbound enums (like `BidRequest.at` - exchange-specific auctions types are > 500) - - `uint64` - width, height, bitrate etc. (unbound positive numbers) + - `int64` - every other integral type - `float64` - coordinates, prices etc. - Enums: - all enums, described in section 5, must be typed with section name singularized (e.g., "5.2 Banner Ad Types" -> `type BannerAdType int8`) - all typed enums must have constants for each element, prefixed with type name (e.g., "5.2 Banner Ad Types - XHTML Text Ad (usually mobile)" -> `const BannerAdTypeXHTMLTextAd BannerAdType = 1`) - never use `iota` for enum constants - - section "5.1 Content Categories" should remain untyped and have no constants + - OpenRTB (2.x) section "5.1 Content Categories" should remain untyped and have no constants ## Pointers/omitempty Pointer | Omitempty | When to use | Example diff --git a/adcom1/README.md b/adcom1/README.md new file mode 100644 index 0000000..42e5003 --- /dev/null +++ b/adcom1/README.md @@ -0,0 +1,3 @@ +# adcom1 + +[AdCOM](https://iabtechlab.com/standards/openmedia/) [1.0](https://github.com/InteractiveAdvertisingBureau/AdCOM) types for [Go programming language](https://golang.org/) diff --git a/adcom1/ad.go b/adcom1/ad.go new file mode 100644 index 0000000..cf97fad --- /dev/null +++ b/adcom1/ad.go @@ -0,0 +1,161 @@ +package adcom1 + +import "encoding/json" + +// Ad object is the root of a structure that defines in instance of advertising media. +// It includes metadata about the ad overall and sub-objects that provide additional detail specific to the type of media comprising the creative. +type Ad struct { + // Attribute: + // id + // Type: + // string; required + // Definition: + // ID of the creative; unique at least throughout the scope of a vendor (e.g., an exchange or buying platform). + // Note that multiple instances of the same ad when used in transactions must have the same ID. + ID string `json:"id"` + + // Attribute: + // adomain + // Type: + // string array; recommended + // Definition: + // Advertiser domain; top two levels only (e.g., “ford.com”). + // This can be an array for the case of rotating creatives. + ADomain []string `json:"adomain,omitempty"` + + // Attribute: + // bundle + // Type: + // string array + // Definition: + // When the product of the ad is an app, the unique ID of that app as a bundle or package name (e.g., “com.foo.mygame”). + // This should NOT be an app store ID (e.g., no iTunes store IDs). + // This can be an array of for the case of rotating creatives. + Bundle []string `json:"bundle,omitempty"` + + // Attribute: + // iurl + // Type: + // string + // Definition: + // URL without cache-busting to an image that is representative of the ad content for cursory level ad quality checking. + IURL string `json:"iurl,omitempty"` + + // Attribute: + // cat + // Type: + // string array + // Definition: + // Array of content categories describing the ad using IDs from the taxonomy indicated in cattax. + Cat []string `json:"cat,omitempty"` + + // Attribute: + // cattax + // Type: + // integer; default 2 + // Definition: + // The taxonomy in use for the cat attribute. + // Refer to List: Category Taxonomies. + CatTax CategoryTaxonomy `json:"cattax,omitempty"` + + // Attribute: + // lang + // Type: + // string + // Definition: + // Language of the creative using ISO-639-1-alpha-2. + // In practice, vendors using this object may elect an alternate standard (e.g., BCP-47) in which case this must be communicated a priori. + // The non-standard code “xx” may also be used if the creative has no linguistic content (e.g., a banner with just a company logo). + Lang string `json:"lang,omitempty"` + + // Attribute: + // attr + // Type: + // integer array + // Definition: + // Set of attributes describing the creative. + // Refer to List: Creative Attributes. + Attr []CreativeAttribute `json:"attr,omitempty"` + + // Attribute: + // secure + // Type: + // integer + // Definition: + // Flag to indicate if the creative is secure (i.e., uses HTTPS for all assets and markup), where 0 = no, 1 = yes. + // There is no default and thus if omitted, the secure state is unknown. + // However, as a practical matter, the safe assumption is to treat unknown as non-secure. + Secure int8 `json:"secure,omitempty"` + + // Attribute: + // mrating + // Type: + // integer + // Definition: + // Media rating per IQG guidelines. + // Refer to List: Media Ratings. + MRating MediaRating `json:"mrating,omitempty"` + + // Attribute: + // init + // Type: + // integer + // Definition: + // Timestamp of the original instantiation of this ad (i.e., this object or any of its children) in Unix format (i.e., milliseconds since the epoch). + Init int64 `json:"init,omitempty"` + + // Attribute: + // lastmod + // Type: + // integer + // Definition: + // Timestamp of most recent modification to this ad (i.e., this object or any of its children other than the Audit object) in Unix format (i.e., milliseconds since the epoch). + LastMod int64 `json:"lastmod,omitempty"` + + // Attribute: + // display + // Type: + // Object; required * + // Definition: + // Media Subtype Object that indicates this is a display ad and provides additional detail as such. + // Refer to Object: Display. + // * Required if no other media subtype object is specified. + Display *Display `json:"display,omitempty"` + + // Attribute: + // video + // Type: + // object; required * + // Definition: + // Media Subtype Object that indicates this is a video ad and provides additional detail as such. + // Refer to Object: Video. + // * Required if no other media subtype object is specified. + Video *Video `json:"video,omitempty"` + + // Attribute: + // audio + // Type: + // object; required * + // Definition: + // Media Subtype Object that indicates this is an audio ad and provides additional detail as such. + // Refer to Object: Audio. + // * Required if no other media subtype object is specified. + Audio *Audio `json:"audio,omitempty"` + + // Attribute: + // audit + // Type: + // object + // Definition: + // An object depicting the audit status of the ad; typically part of a quality/safety review process. + // Refer to Object: Audit. + Audit *Audit `json:"audit,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/adcom1.go b/adcom1/adcom1.go new file mode 100644 index 0000000..8e2cc96 --- /dev/null +++ b/adcom1/adcom1.go @@ -0,0 +1,10 @@ +// Package adcom1 implements types for AdCOM Specification v1.0 +// https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md +package adcom1 + +/* + +// (.+?)\t((.+?)(?:;.+?)?)\t(.+?)\n +// Attribute:\n\t// $1\n\t// Type:\n\t// $2\n\t// Definition:\n\t// $4\n\t$1 $3 `json:"$1,omitempty"`\n\n + +*/ diff --git a/openrtb_suite_test.go b/adcom1/adcom1_suite_test.go similarity index 56% rename from openrtb_suite_test.go rename to adcom1/adcom1_suite_test.go index 9487389..306b230 100644 --- a/openrtb_suite_test.go +++ b/adcom1/adcom1_suite_test.go @@ -1,13 +1,13 @@ -package openrtb_test +package adcom1_test import ( + "testing" + . "github.com/onsi/ginkgo" . "github.com/onsi/gomega" - - "testing" ) -func TestOpenrtb(t *testing.T) { +func TestAdcom1(t *testing.T) { RegisterFailHandler(Fail) - RunSpecs(t, "Openrtb Suite") + RunSpecs(t, "Adcom1 Suite") } diff --git a/adcom1/adcom1_test.go b/adcom1/adcom1_test.go new file mode 100644 index 0000000..b004dfd --- /dev/null +++ b/adcom1/adcom1_test.go @@ -0,0 +1,31 @@ +package adcom1_test + +import ( + "encoding/json" + "io/ioutil" + "path/filepath" + + . "github.com/onsi/ginkgo/extensions/table" + . "github.com/onsi/gomega" + + . "github.com/mxmCherry/openrtb/adcom1" +) + +var _ = DescribeTable( + "Marshaling", + func(obj interface{}, file string) { + golden, err := ioutil.ReadFile(filepath.Join("testdata", file)) + Expect(err).NotTo(HaveOccurred()) + + Expect(json.Unmarshal(golden, obj)).To(Succeed()) + + b, err := json.Marshal(obj) + Expect(err).NotTo(HaveOccurred()) + + Expect(b).To(MatchJSON(golden)) + }, + + Entry("request context", new(RequestContext), "request-context.json"), + Entry("item specifications", new(ItemSpec), "item-specifications.json"), + Entry("media response", new(BidMedia), "media-response.json"), +) diff --git a/adcom1/api_framework.go b/adcom1/api_framework.go new file mode 100644 index 0000000..1ed2caa --- /dev/null +++ b/adcom1/api_framework.go @@ -0,0 +1,17 @@ +package adcom1 + +// APIFramework represents API frameworks either supported by a placement or required by an ad. +type APIFramework int + +// API frameworks either supported by a placement or required by an ad. +// +// Values of 500+ hold vendor-specific codes. +const ( + APIVPAID1 APIFramework = 1 // VPAID 1.0 + APIVPAID2 APIFramework = 2 // VPAID 2.0 + APIMRAID1 APIFramework = 3 // MRAID 1.0 + APIORMMA APIFramework = 4 // ORMMA + APIMRAID2 APIFramework = 5 // MRAID 2.0 + APIMRAID3 APIFramework = 6 // MRAID 3.0 + APIOMID1 APIFramework = 7 // OMID 1.0 +) diff --git a/adcom1/app.go b/adcom1/app.go new file mode 100644 index 0000000..90409a0 --- /dev/null +++ b/adcom1/app.go @@ -0,0 +1,114 @@ +package adcom1 + +import "encoding/json" + +// App object is used to define an ad supported non-browser application, in contrast to a typical website, example. +// As a derived class, an App object inherits all DistributionChannel attributes and adds those defined below. +type App struct { + DistributionChannel + + // Attribute: + // domain + // Type: + // string + // Definition: + // Domain of the app (e.g., “mygame.foo.com”). + Domain string `json:"domain,omitempty"` + + // Attribute: + // cat + // Type: + // string array + // Definition: + // Array of content categories describing the app using IDs from the taxonomy indicated in cattax. + Cat []string `json:"cat,omitempty"` + + // Attribute: + // sectcat + // Type: + // string array + // Definition: + // Array of content categories describing the current section of the app using IDs from the taxonomy indicated in cattax. + SectCat []string `json:"sectcat,omitempty"` + + // Attribute: + // pagecat + // Type: + // string array + // Definition: + // Array of content categories describing the current page or view of the app using IDs from the taxonomy indicated in cattax. + PageCat []string `json:"pagecat,omitempty"` + + // Attribute: + // cattax + // Type: + // integer + // Definition: + // The taxonomy in use for the cat, sectcat and pagecat attributes. + // Refer to List: Category Taxonomies. + CatTax CategoryTaxonomy `json:"cattax,omitempty"` + + // Attribute: + // privpolicy + // Type: + // integer + // Definition: + // Indicates if the app has a privacy policy, where 0 = no, 1 = yes. + PrivPolicy int8 `json:"privpolicy,omitempty"` + + // Attribute: + // keywords + // Type: + // string + // Definition: + // Comma separated list of keywords about the app. + Keywords string `json:"keywords,omitempty"` + + // Attribute: + // bundle + // Type: + // string + // Definition: + // Bundle or package name of the app (e.g., “com.foo.mygame”) and should NOT be app store IDs (e.g., not iTunes store IDs). + Bundle string `json:"bundle,omitempty"` + + // Attribute: + // storeid + // Type: + // string + // Definition: + // The ID of the app in an app store (e.g., Apple iTunes, Google Play). + StoreID string `json:"storeid,omitempty"` + + // Attribute: + // storeurl + // Type: + // string + // Definition: + // App store URL for an installed app; for IQG 2.1 compliance. + StoreURL string `json:"storeurl,omitempty"` + + // Attribute: + // ver + // Type: + // string + // Definition: + // Application version. + Ver string `json:"ver,omitempty"` + + // Attribute: + // paid + // Type: + // integer; default 0 + // Definition: + // Indicator of whether or not this is a paid app, where 0 = free, 1 = paid. + Paid int8 `json:"paid,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/asset.go b/adcom1/asset.go new file mode 100644 index 0000000..81050f1 --- /dev/null +++ b/adcom1/asset.go @@ -0,0 +1,81 @@ +package adcom1 + +import "encoding/json" + +// Asset object is the container for each asset comprising a native ad. +// Each asset is of a specific type and to reflect this, one and only one of the subtype objects (i.e., title, img, video, data) must be present; all others should be omitted. +type Asset struct { + // Attribute: + // id + // Type: + // integer + // Definition: + // The value of AssetFormat.id if this ad references a specific native placement defined by a Placement object and its structure. + ID int64 `json:"id,omitempty"` + + // Attribute: + // req + // Type: + // integer; default 0 + // Definition: + // Indicates if the asset is required to be displayed, where 0 = no, 1 = yes. + Req int8 `json:"req,omitempty"` + + // Attribute: + // title + // Type: + // object; required * + // Definition: + // Asset Subtype Object that indicates this is a title asset and provides additional detail as such. + // Refer to Object: TitleAsset. + // * Required if no other asset subtype object is specified. + Title *TitleAsset `json:"title,omitempty"` + + // Attribute: + // image + // Type: + // object; required * + // Definition: + // Asset Subtype Object that indicates this is an image asset and provides additional detail as such. + // Refer to Object: ImageAsset. + // * Required if no other asset subtype object is specified. + Image *ImageAsset `json:"image,omitempty"` + + // Attribute: + // video + // Type: + // object; required * + // Definition: + // Asset Subtype Object that indicates this is a video asset and provides additional detail as such. + // Refer to Object: VideoAsset. + // * Required if no other asset subtype object is specified. + Video *VideoAsset `json:"video,omitempty"` + + // Attribute: + // data + // Type: + // object; required * + // Definition: + // Asset Subtype Object that indicates this is a data asset and provides additional detail as such. + // Refer to Object: DataAsset. + // * Required if no other asset subtype object is specified. + Data *DataAsset `json:"data,omitempty"` + + // Attribute: + // link + // Type: + // object; required * + // Definition: + // Asset Subtype Object that indicates this is a link asset and provides additional detail as such. + // Refer to Object: LinkAsset. + // * Required if no other asset subtype object is specified. + Link *LinkAsset `json:"link,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/asset_format.go b/adcom1/asset_format.go new file mode 100644 index 0000000..f9b562f --- /dev/null +++ b/adcom1/asset_format.go @@ -0,0 +1,72 @@ +package adcom1 + +import "encoding/json" + +// AssetFormat object represents the permitted specifications of a single asset of a native ad. +// Along with its own attributes, exactly one of the asset subtype objects must be included. +// All others must be omitted. +type AssetFormat struct { + // Attribute: + // id + // Type: + // integer; required + // Definition: + // Asset ID, unique within the scope of this placement specification. + ID int64 `json:"id"` + + // Attribute: + // req + // Type: + // integer; default 0 + // Definition: + // Indicator of whether or not this asset is required, where 0 = no, 1 = yes. + Req int8 `json:"req,omitempty"` + + // Attribute: + // title + // Type: + // object; required * + // Definition: + // Asset Format Subtype Object that indicates this is specifying a title asset and provides additional detail as such. + // Refer to Object: TitleAssetFormat. + // * Required if no other asset format subtype object is specified. + Title *TitleAssetFormat `json:"title,omitempty"` + + // Attribute: + // img + // Type: + // object; required * + // Definition: + // Asset Format Subtype Object that indicates this is specifying an image asset and provides additional detail as such. + // Refer to Object: ImageAssetFormat. + // * Required if no other asset format subtype object is specified. + Img *ImageAssetFormat `json:"img,omitempty"` + + // Attribute: + // video + // Type: + // object; required * + // Definition: + // Asset Format Subtype Object, which leverages the VideoPlacement object, that indicates this is specifying a video asset and provides additional detail as such. + // Refer to Object: VideoPlacement. + // * Required if no other asset format subtype object is specified. + Video *VideoPlacement `json:"video,omitempty"` + + // Attribute: + // data + // Type: + // object; required * + // Definition: + // Asset Format Subtype Object that indicates this is specifying a data asset and provides additional detail as such. + // Refer to Object: DataAssetFormat. + // * Required if no other asset format subtype object is specified. + Data *DataAssetFormat `json:"data,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/audio.go b/adcom1/audio.go new file mode 100644 index 0000000..329f811 --- /dev/null +++ b/adcom1/audio.go @@ -0,0 +1,66 @@ +package adcom1 + +import "encoding/json" + +// Audio object provides additional detail about an ad specifically for audio ads. +type Audio struct { + // Attribute: + // mime + // Type: + // string array + // Definition: + // Mime type(s) of the ad creative(s) (e.g., “audio/mp4”). + MIME []string `json:"mime,omitempty"` + + // Attribute: + // api + // Type: + // integer array + // Definition: + // API required by the ad if applicable. + // Refer to List: API Frameworks. + API []APIFramework `json:"api,omitempty"` + + // Attribute: + // ctype + // Type: + // integer + // Definition: + // Subtype of audio creative. + // Refer to List: Creative Subtypes - Audio/Video. + CType CreativeSubtypeAV `json:"ctype,omitempty"` + + // Attribute: + // dur + // Type: + // integer + // Definition: + // Duration of the audio creative in seconds. + Dur int64 `json:"dur,omitempty"` + + // Attribute: + // adm + // Type: + // string + // Definition: + // Audio markup (e.g., DAAST). Note that including both adm and curl is not recommended. + AdM string `json:"adm,omitempty"` + + // Attribute: + // curl + // Type: + // string + // Definition: + // Optional means of retrieving markup by reference; a URL that returns audio markup (e.g., DAAST). + // If this ad is matched to a Placement specification, the Placement.curlx attribute indicates if this markup retrieval option is supported. + // Note that including both adm and curl is not recommended. + CURL string `json:"curl,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/audio_placement.go b/adcom1/audio_placement.go new file mode 100644 index 0000000..58654ad --- /dev/null +++ b/adcom1/audio_placement.go @@ -0,0 +1,190 @@ +package adcom1 + +import "encoding/json" + +// AudioPlacement object signals that the placement may be an audio placement and provides additional detail about permitted audio ads (e.g., DAAST). +type AudioPlacement struct { + // Attribute: + // delay + // Type: + // integer + // Definition: + // Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll placements. + // For additional generic values, refer to List: Start Delay Modes. + Delay int64 `json:"delay,omitempty"` + + // Attribute: + // skip + // Type: + // integer + // Definition: + // Indicates if the placement imposes ad skippability, where 0 = no, 1 = yes. + Skip int8 `json:"skip,omitempty"` + + // Attribute: + // skipmin + // Type: + // integer; default 0 + // Definition: + // The placement allows creatives of total duration greater than this number of seconds to be skipped; only applicable if the ad is skippable. + SkipMin int64 `json:"skipmin,omitempty"` + + // Attribute: + // skipafter + // Type: + // integer; default 0 + // Definition: + // Number of seconds a creative must play before the placement enables skipping; only applicable if the ad is skippable. + SkipAfter int64 `json:"skipafter,omitempty"` + + // Attribute: + // playmethod + // Type: + // integer + // Definition: + // Playback method in use for this placement. + // Refer to List: Playback Methods. + PlayMethod PlaybackMethod `json:"playmethod,omitempty"` + + // Attribute: + // playend + // Type: + // integer + // Definition: + // The event that causes playback to end for this placement. + // Refer to List: Playback Cessation Modes. + PlayEnd PlaybackCessationMode `json:"playend,omitempty"` + + // Attribute: + // feed + // Type: + // integer + // Definition: + // Type of audio feed of this placement. + // Refer to List: Feed Types. + Feed FeedType `json:"feed,omitempty"` + + // Attribute: + // nvol + // Type: + // integer + // Definition: + // Volume normalization mode of this placement. + // Refer to List: Volume Normalization Modes. + NVol VolumeNormalizationMode `json:"nvol,omitempty"` + + // Attribute: + // mime + // Type: + // string array; required + // Definition: + // Array of supported mime types (e.g., “audio/mp4”). + // If omitted, all types are assumed. + MIME []string `json:"mime,omitempty"` + + // Attribute: + // api + // Type: + // integer array + // Definition: + // List of supported APIs for this placement. + // If an API is not explicitly listed, it is assumed to be unsupported. + // Refer to List: API Frameworks. + API []APIFramework `json:"api,omitempty"` + + // Attribute: + // ctype + // Type: + // integer array + // Definition: + // Creative subtypes permitted for this placement. + // Refer to List: Creative Subtypes - Audio/Video. + CType []CreativeSubtypeAV `json:"ctype,omitempty"` + + // Attribute: + // mindur + // Type: + // integer + // Definition: + // Minimum creative duration in seconds. + MinDur int64 `json:"mindur,omitempty"` + + // Attribute: + // maxdur + // Type: + // integer + // Definition: + // Maximum creative duration in seconds. + MaxDur int64 `json:"maxdur,omitempty"` + + // Attribute: + // maxext + // Type: + // integer + // Definition: + // Maximum extended creative duration if extension is allowed. + // If 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 maxdur value. + MaxExt int64 `json:"maxext,omitempty"` + + // Attribute: + // minbitr + // Type: + // integer + // Definition: + // Minimum bit rate of the creative in Kbps. + MinBitR int64 `json:"minbitr,omitempty"` + + // Attribute: + // maxbitr + // Type: + // integer + // Definition: + // Maximum bit rate of the creative in Kbps. + MaxBitR int64 `json:"maxbitr,omitempty"` + + // Attribute: + // delivery + // Type: + // integer array + // Definition: + // Array of supported creative delivery methods. + // If omitted, all can be assumed. + // Refer to List: Delivery Methods. + Delivery []DeliveryMethod `json:"delivery,omitempty"` + + // Attribute: + // maxseq + // Type: + // integer + // Definition: + // The maximum number of ads that can be played in an ad pod. + MaxSeq int64 `json:"maxseq,omitempty"` + + // Attribute: + // comp + // Type: + // object array + // Definition: + // Array of objects indicating that companion ads are available and providing the specifications thereof. + // Refer to Object: Companion. + Comp []Companion `json:"comp,omitempty"` + + // Attribute: + // comptype + // Type: + // integer array + // Definition: + // Supported companion ad types; recommended if companion ads are specified in comp. + // Refer to List: Companion Types. + CompType []CompanionType `json:"comptype,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/audit.go b/adcom1/audit.go new file mode 100644 index 0000000..5ff4364 --- /dev/null +++ b/adcom1/audit.go @@ -0,0 +1,57 @@ +package adcom1 + +import "encoding/json" + +// Audit objects represents the outcome of some form of review of the ad. +// This is typical, for example, when scanning for malware or otherwise performing ad quality reviews. +type Audit struct { + // Attribute: + // status + // Type: + // integer + // Definition: + // The audit status of the ad. + // Refer to List: Audit Status Codes. + Status AuditStatus `json:"status,omitempty"` + + // Attribute: + // feedback + // Type: + // string array + // Definition: + // One or more human-readable explanations as to reasons for rejection or any changes to fields for ad quality reasons (e.g., adomain, cat, attr, etc.). + Feedback []string `json:"feedback,omitempty"` + + // Attribute: + // init + // Type: + // integer + // Definition: + // Timestamp of the original instantiation of this object in Unix format (i.e., milliseconds since the epoch). + Init int64 `json:"init,omitempty"` + + // Attribute: + // lastmod + // Type: + // integer + // Definition: + // Timestamp of most recent modification to this object in Unix format (i.e., milliseconds since the epoch). + LastMod int64 `json:"lastmod,omitempty"` + + // Attribute: + // corr + // Type: + // object + // Definition: + // Correction object wherein the auditor can specify changes to attributes of the Ad object or its children they believe to be proper. + // For example, if the original Ad indicated a category of “IAB3”, but the auditor deems the correct category to be “IAB13”, then corr could include a sparse Ad object including just the cat array indicating “IAB13”. + Corr *Ad `json:"corr,omitempty"` // TODO: probably, this won't work due to "omitempty" stuff. Probably, will need an all-pointer Ad equivalent. + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/audit_status.go b/adcom1/audit_status.go new file mode 100644 index 0000000..4dad2f8 --- /dev/null +++ b/adcom1/audit_status.go @@ -0,0 +1,16 @@ +package adcom1 + +// AuditStatus represents codes used in Audit objects to reflect status or workflow state. +type AuditStatus int + +// Codes used in Audit objects to reflect status or workflow state. +// +// Values of 500+ hold endor-specific codes. +const ( + AuditPendingAudit AuditStatus = 1 // Pending Audit: An audit has not yet been completed on this ad. A recommendation cannot be made to use this ad, but vendors' policies may override. + AuditPreApproved AuditStatus = 2 // Pre-Approved: An audit has not yet been completed on this ad. Subject to vendors' policies, it can be recommended for use. However, once the audit has been completed, its status will change and it may or may not be approved for continued use. + AuditApproved AuditStatus = 3 // Approved: The audit is complete and the ad is approved for use. Note, however, that some attributes (e.g., adomain, cat, attr, etc.) may have been changed in the process by the auditor. + AuditDenied AuditStatus = 4 // Denied: The audit is complete, but the ad has been found unacceptable in some material aspect and is disapproved for use. + AuditChangedResubmissionRequested AuditStatus = 5 // Changed; Resubmission Requested: A version of the ad has been detected in use that is materially different from the version that was previously audited, which may result in rejection during use until the ad is resubmitted for audit and approved. Vendors need to communicate offline as to the criteria that constitutes a material change. + AuditExpired AuditStatus = 6 // Expired: The ad has been marked as expired by the vendor. Vendors need to communicate offline as to the expected bidding behavior for ads with this status. +) diff --git a/adcom1/banner.go b/adcom1/banner.go new file mode 100644 index 0000000..4a17e79 --- /dev/null +++ b/adcom1/banner.go @@ -0,0 +1,32 @@ +package adcom1 + +import "encoding/json" + +// Banner object describes a basic banner creative. +// It is intended for display scenarios that require a simple, structured image/link pair and is more secure than allowing arbitrary HTML or JavaScript code. +type Banner struct { + // Attribute: + // img + // Type: + // string; required + // Definition: + // A URL that will return the image. + Img string `json:"img"` + + // Attribute: + // link + // Type: + // object + // Definition: + // Destination link if the image is activated (e.g., clicked); not applicable in some contexts (e.g., DOOH) and its inclusion does not guarantee it will be supported. + // Refer to Object: LinkAsset. + Link *LinkAsset `json:"link,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/bid_media.go b/adcom1/bid_media.go new file mode 100644 index 0000000..a71e511 --- /dev/null +++ b/adcom1/bid_media.go @@ -0,0 +1,10 @@ +package adcom1 + +// BidMedia represents a bunch of data for OpenRTB 3 Bid.media field. +// Refer to OpenRTB 3.0 specification for details. +// +// For AdCOM v1.x, the objects allowed here are “Ad” and any objects subordinate thereto as specified by AdCOM. +// +type BidMedia struct { + Ad *Ad `json:"ad,omitempty"` +} diff --git a/adcom1/category_taxonomy.go b/adcom1/category_taxonomy.go new file mode 100644 index 0000000..a7a9f6d --- /dev/null +++ b/adcom1/category_taxonomy.go @@ -0,0 +1,13 @@ +package adcom1 + +// CategoryTaxonomy identifies the taxonomy in effect when content categories are listed. +type CategoryTaxonomy int + +// CategoryTaxonomy options. +// +// Values of 500+ hold vendor-specific codes. +const ( + CatTaxIABContent1 CategoryTaxonomy = 1 // 1 IAB Content Category Taxonomy 1.0. + CatTaxIABContent2 CategoryTaxonomy = 2 // 2 IAB Content Category Taxonomy 2.0: www.iab.com/guidelines/taxonomy + CatTaxIABProduct1 CategoryTaxonomy = 3 // 3 IAB Ad Product Taxonomy 1.0. +) diff --git a/adcom1/click_type.go b/adcom1/click_type.go new file mode 100644 index 0000000..ea074f5 --- /dev/null +++ b/adcom1/click_type.go @@ -0,0 +1,14 @@ +package adcom1 + +// ClickType represents types of creative activation (i.e., click) behavior types. +type ClickType int + +// Types of creative activation (i.e., click) behavior types. +// +// Values of 500+ hold vendor-specific codes. +const ( + ClickNonClickable ClickType = 0 // Non-Clickable + ClickUnknown ClickType = 1 // Clickable - Details Unknown + ClickEmbedded ClickType = 2 // Clickable - Embedded Browser/Webview + ClickNative ClickType = 3 // Clickable - Native Browser +) diff --git a/adcom1/companion.go b/adcom1/companion.go new file mode 100644 index 0000000..c15f48f --- /dev/null +++ b/adcom1/companion.go @@ -0,0 +1,41 @@ +package adcom1 + +import "encoding/json" + +// Companion object is used in video and audio placements to specify an associated or so-called companion display ad. +// Video and audio placements can specify an array of companion ads. +type Companion struct { + // Attribute: + // id + // Type: + // string + // Definition: + // Identifier of the companion ad; unique within this placement. + ID string `json:"id,omitempty"` + + // Attribute: + // vcm + // Type: + // integer + // Definition: + // Indicates the companion ad rendering mode relative to the associated video or audio ad, where 0 = concurrent, 1 = end-card. + // For a given placement, typically only one companion at most should be designated as an end card. + VCm int8 `json:"vcm,omitempty"` + + // Attribute: + // display + // Type: + // object + // Definition: + // Display specification object representing the companion ad. + // Refer to Object: DisplayPlacement. + Display *DisplayPlacement `json:"display,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/companion_type.go b/adcom1/companion_type.go new file mode 100644 index 0000000..f58a44a --- /dev/null +++ b/adcom1/companion_type.go @@ -0,0 +1,13 @@ +package adcom1 + +// CompanionType represents options to indicate markup types allowed for companion ads that apply to video and audio ads. +// This table is derived from VAST 2.0+ and DAAST 1.0+ specifications. +type CompanionType int8 + +// options to indicate markup types allowed for companion ads that apply to video and audio ads. +// This table is derived from VAST 2.0+ and DAAST 1.0+ specifications. +const ( + CompanionStatic CompanionType = 1 // Static Resource + CompanionHTML CompanionType = 2 // HTML Resource + CompanionIFrame CompanionType = 3 // iframe Resource +) diff --git a/adcom1/connection_type.go b/adcom1/connection_type.go new file mode 100644 index 0000000..cacafc8 --- /dev/null +++ b/adcom1/connection_type.go @@ -0,0 +1,15 @@ +package adcom1 + +// ConnectionType represents options for the type of device connectivity. +type ConnectionType int8 + +// Options for the type of device connectivity. +const ( + ConnectionEthernet ConnectionType = 1 // 1 Ethernet; Wired Connection + ConnectionWIFI ConnectionType = 2 // 2 WIFI + ConnectionCellular ConnectionType = 3 // 3 Cellular Network - Unknown Generation + Connection2G ConnectionType = 4 // 4 Cellular Network - 2G + Connection3G ConnectionType = 5 // 5 Cellular Network - 3G + Connection4G ConnectionType = 6 // 6 Cellular Network - 4G + Connection5G ConnectionType = 7 // 7 Cellular Network - 5G +) diff --git a/adcom1/content.go b/adcom1/content.go new file mode 100644 index 0000000..701363b --- /dev/null +++ b/adcom1/content.go @@ -0,0 +1,227 @@ +package adcom1 + +import "encoding/json" + +// Content object describes the content in which an impression can appear, which may be syndicated or non-syndicated content. +// This object may be useful when syndicated content contains impressions and does not necessarily match the publisher's general content. +// An exchange may or may not have knowledge of the page where the content is running as a result of the syndication method (e.g., a video impression embedded in an iframe on an unknown web property or device). +type Content struct { + // Attribute: + // id + // Type: + // string + // Definition: + // ID uniquely identifying the content. + ID string `json:"id,omitempty"` + + // Attribute: + // episode + // Type: + // integer + // Definition: + // Episode number. + Episode int64 `json:"episode,omitempty"` + + // Attribute: + // title + // Type: + // string + // Definition: + // Content title. + // Video Examples: “Search Committee” (television), “Star Wars, A New Hope” (movie), or “Endgame” (made for web). + // Non-Video Example: “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article). + Title string `json:"title,omitempty"` + + // Attribute: + // series + // Type: + // string + // Definition: + // Content series. + // Video Examples: “The Office” (television), “Star Wars” (movie), or “Arby 'N' The Chief” (made for web). + // Non-Video Example: “Ecocentric” (Time Magazine blog). + Series string `json:"series,omitempty"` + + // Attribute: + // season + // Type: + // string + // Definition: + // Content season (e.g., “Season 3”). + Season string `json:"season,omitempty"` + + // Attribute: + // artist + // Type: + // string + // Definition: + // Artist credited with the content. + Artist string `json:"artist,omitempty"` + + // Attribute: + // genre + // Type: + // string + // Definition: + // Genre that best describes the content (e.g., rock, pop, etc). + Genre string `json:"genre,omitempty"` + + // Attribute: + // album + // Type: + // string + // Definition: + // Album to which the content belongs; typically for audio. + Album string `json:"album,omitempty"` + + // Attribute: + // isrc + // Type: + // string + // Definition: + // International Standard Recording Code conforming to ISO-3901. + ISRC string `json:"isrc,omitempty"` + + // Attribute: + // url + // Type: + // string + // Definition: + // URL of the content, for buy-side contextualization or review. + URL string `json:"url,omitempty"` + + // Attribute: + // cat + // Type: + // string array + // Definition: + // Array of content categories describing the content using IDs from the taxonomy indicated in cattax. + Cat []string `json:"cat,omitempty"` + + // Attribute: + // cattax + // Type: + // integer + // Definition: + // The taxonomy in use for the cat attribute. + // Refer to List: Category Taxonomies. + CatTax CategoryTaxonomy `json:"cattax,omitempty"` + + // Attribute: + // prodq + // Type: + // integer + // Definition: + // Production quality. + // Refer to List: Production Qualities. + ProdQ ProductionQuality `json:"prodq,omitempty"` + + // Attribute: + // context + // Type: + // integer + // Definition: + // Type of content (game, video, text, etc.). + // Refer to List: Content Contexts. + Context ContentContext `json:"context,omitempty"` + + // Attribute: + // rating + // Type: + // string + // Definition: + // Content rating (e.g., MPAA). + Rating string `json:"rating,omitempty"` + + // Attribute: + // urating + // Type: + // string + // Definition: + // User rating of the content (e.g., number of stars, likes, etc.). + URating string `json:"urating,omitempty"` + + // Attribute: + // mrating + // Type: + // integer + // Definition: + // Media rating per IQG guidelines. + // Refer to List: Media Ratings. + MRating MediaRating `json:"mrating,omitempty"` + + // Attribute: + // keywords + // Type: + // string + // Definition: + // Comma separated list of keywords describing the content. + Keywords string `json:"keywords,omitempty"` + + // Attribute: + // live + // Type: + // integer + // Definition: + // Indication of live content, where 0 = not live, 1 = live (e.g., stream, live blog). + Live int8 `json:"live,omitempty"` + + // Attribute: + // srcrel + // Type: + // integer + // Definition: + // Source relationship, where 0 = indirect, 1 = direct. + SrcRel int8 `json:"srcrel,omitempty"` + + // Attribute: + // len + // Type: + // integer + // Definition: + // Length of content in seconds; typically for video or audio. + Len int64 `json:"len,omitempty"` + + // Attribute: + // lang + // Type: + // string + // Definition: + // Content language using ISO-639-1-alpha-2. + Lang string `json:"lang,omitempty"` + + // Attribute: + // embed + // Type: + // integer + // Definition: + // Indicator of whether or not the content is embedded off-site from the the site or app described in those objects (e.g., an embedded video player), where 0 = no, 1 = yes. + Embed int8 `json:"embed,omitempty"` + + // Attribute: + // producer + // Type: + // object + // Definition: + // Details about the content producer. + // Refer to Object: Producer. + Producer *Producer `json:"producer,omitempty"` + + // Attribute: + // data + // Type: + // object array + // Definition: + // Additional user data. + // Each Data object represents a different data source. + // Refer to Object: Data. + Data []Data `json:"data,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/content_context.go b/adcom1/content_context.go new file mode 100644 index 0000000..7634a81 --- /dev/null +++ b/adcom1/content_context.go @@ -0,0 +1,17 @@ +package adcom1 + +// ContentContext represents options for indicating the type of content being used or consumed by the user in which ads may appear. +// This table has values derived from the TAG Inventory Quality Guidelines (IQG). +type ContentContext int8 + +// Options for indicating the type of content being used or consumed by the user in which ads may appear. +// This table has values derived from the TAG Inventory Quality Guidelines (IQG). +const ( + ContentVideo ContentContext = 1 // 1 Video (i.e., video file or stream such as Internet TV broadcasts) + ContentGame ContentContext = 2 // 2 Game (i.e., an interactive software game) + ContentMusic ContentContext = 3 // 3 Music (i.e., audio file or stream such as Internet radio broadcasts) + ContentApp ContentContext = 4 // 4 Application (i.e., an interactive software application) + ContentText ContentContext = 5 // 5 Text (i.e., primarily textual document such as a web page, eBook, or news article) + ContentOther ContentContext = 6 // 6 Other (i.e., none of the other categories applies) + ContentUnknown ContentContext = 7 // 7 Unknown +) diff --git a/adcom1/creative_attribute.go b/adcom1/creative_attribute.go new file mode 100644 index 0000000..e19bfa1 --- /dev/null +++ b/adcom1/creative_attribute.go @@ -0,0 +1,28 @@ +package adcom1 + +// CreativeAttribute specifies a standard list of creative attributes that can describe an actual ad or restrictions relative to a given placement. +type CreativeAttribute int + +// Standard list of creative attributes that can describe an actual ad or restrictions relative to a given placement. +// +// Values of 500+ hold vendor-specific codes. +const ( + AttrAudioAuto CreativeAttribute = 1 // Audio Ad (Autoplay) + AttrAudioUser CreativeAttribute = 2 // Audio Ad (User Initiated) + AttrExpandableAuto CreativeAttribute = 3 // Expandable (Automatic) + AttrExpandableUserClick CreativeAttribute = 4 // Expandable (User Initiated - Click) + AttrExpandableUserRollover CreativeAttribute = 5 // Expandable (User Initiated - Rollover) + AttrVideoAuto CreativeAttribute = 6 // In-Banner Video Ad (Autoplay) + AttrVideoUser CreativeAttribute = 7 // In-Banner Video Ad (User Initiated) + AttrPop CreativeAttribute = 8 // Pop (e.g., Over, Under, or Upon Exit) + AttrProvocative CreativeAttribute = 9 // Provocative or Suggestive Imagery + AttrExtremeAnimation CreativeAttribute = 10 // Shaky, Flashing, Flickering, Extreme Animation, Smileys + AttrSurvey CreativeAttribute = 11 // Surveys + AttrTextOnly CreativeAttribute = 12 // Text Only + AttrInteractive CreativeAttribute = 13 // User Interactive (e.g., Embedded Games) + AttrWindowsDialog CreativeAttribute = 14 // Windows Dialog or Alert Style + AttrHasAudioToggleButton CreativeAttribute = 15 // Has Audio On/Off Button + AttrHasSkipButton CreativeAttribute = 16 // Ad Provides Skip Button (e.g. VPAID-rendered skip button on pre-roll video) + AttrFlash CreativeAttribute = 17 // Adobe Flash + AttrResponsive CreativeAttribute = 18 // Responsive; Sizeless; Fluid (i.e., creatives that dynamically resize to environment) +) diff --git a/adcom1/creative_subtype_av.go b/adcom1/creative_subtype_av.go new file mode 100644 index 0000000..113239a --- /dev/null +++ b/adcom1/creative_subtype_av.go @@ -0,0 +1,20 @@ +package adcom1 + +// CreativeSubtypeAV represents subtypes of audio and video ad creatives. +type CreativeSubtypeAV int8 // TODO: rename to smth like AudioVideoCreativeSubtype? (sounds more natural) + +// Subtypes of audio and video ad creatives. +const ( + CreativeVAST10 CreativeSubtypeAV = 1 // VAST 1.0 + CreativeVAST20 CreativeSubtypeAV = 2 // VAST 2.0 + CreativeVAST30 CreativeSubtypeAV = 3 // VAST 3.0 + CreativeVAST10Wrapper CreativeSubtypeAV = 4 // VAST 1.0 Wrapper + CreativeVAST20Wrapper CreativeSubtypeAV = 5 // VAST 2.0 Wrapper + CreativeVAST30Wrapper CreativeSubtypeAV = 6 // VAST 3.0 Wrapper + CreativeVAST40 CreativeSubtypeAV = 7 // VAST 4.0 + CreativeVAST40Wrapper CreativeSubtypeAV = 8 // VAST 4.0 Wrapper + CreativeDAAST10 CreativeSubtypeAV = 9 // DAAST 1.0 + CreativeDAAST10Wrapper CreativeSubtypeAV = 10 // DAAST 1.0 Wrapper + CreativeVAST41 CreativeSubtypeAV = 11 // VAST 4.1 + CreativeVAST41Wrapper CreativeSubtypeAV = 12 // VAST 4.1 Wrapper +) diff --git a/adcom1/creative_subtype_display.go b/adcom1/creative_subtype_display.go new file mode 100644 index 0000000..23e18fa --- /dev/null +++ b/adcom1/creative_subtype_display.go @@ -0,0 +1,12 @@ +package adcom1 + +// CreativeSubtypeDisplay represents subtypes of display ad creatives. +type CreativeSubtypeDisplay int8 // TODO: rename to smth like DisplayCreativeSubtype? (sounds more natural) + +// Subtypes of display ad creatives. +const ( + CreativeHTML CreativeSubtypeDisplay = 1 // HTML + CreativeAMP CreativeSubtypeDisplay = 2 // AMPHTML + CreativeImage CreativeSubtypeDisplay = 3 // Structured Image Object + CreativeNative CreativeSubtypeDisplay = 4 // Structured Native Object +) diff --git a/adcom1/data.go b/adcom1/data.go new file mode 100644 index 0000000..a318b92 --- /dev/null +++ b/adcom1/data.go @@ -0,0 +1,41 @@ +package adcom1 + +import "encoding/json" + +// Data and segment objects together allow additional data about the related object (e.g., user, content) to be specified. +// This data may be from multiple sources whether from the exchange itself or third parties as specified by the id attribute. +// When in use, vendor-specific IDs should be communicated a priori among the parties. +type Data struct { + // Attribute: + // id + // Type: + // string + // Definition: + // Vendor-specific ID for the data provider. + ID string `json:"id,omitempty"` + + // Attribute: + // name + // Type: + // string + // Definition: + // Vendor-specific displayable name for the data provider. + Name string `json:"name,omitempty"` + + // Attribute: + // segment + // Type: + // object array + // Definition: + // Array of Segment objects that contain the actual data values. + // Refer to Object: Segment. + Segment []Segment `json:"segment,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/data_asset.go b/adcom1/data_asset.go new file mode 100644 index 0000000..c6b73c0 --- /dev/null +++ b/adcom1/data_asset.go @@ -0,0 +1,42 @@ +package adcom1 + +import "encoding/json" + +// DataAsset object identifies the native asset as a data asset. +// A data asset is used for all miscellaneous elements such as brand name, ratings, stars, review count, downloads, price, counts, etc. +// It is purposefully generic to support native elements not currently contemplated by this specification. +type DataAsset struct { + // Attribute: + // value + // Type: + // string; required + // Definition: + // A formatted string of data to be displayed (e.g., “5 stars”, “3.4 stars out of 5”, “$10”, etc.). + Value string `json:"value"` + + // Attribute: + // len + // Type: + // integer + // Definition: + // The length of the value contents. + // This length should conform to recommendations provided in List: Native Data Asset Types + Len int64 `json:"len,omitempty"` + + // Attribute: + // type + // Type: + // integer + // Definition: + // The type of data represented by this asset. + // Refer to List: Native Data Asset Types. + Type NativeDataAssetType `json:"type,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/data_asset_format.go b/adcom1/data_asset_format.go new file mode 100644 index 0000000..8ec7f1b --- /dev/null +++ b/adcom1/data_asset_format.go @@ -0,0 +1,33 @@ +package adcom1 + +import "encoding/json" + +// DataAssetFormat object is used to provide native asset format specifications for a data element. +// A data asset is used for all miscellaneous elements such as brand name, ratings, stars, review count, downloads, prices, etc. +// It is purposefully generic to support native elements not currently contemplated by this specification. +type DataAssetFormat struct { + // Attribute: + // type + // Type: + // integer; required + // Definition: + // The type of data asset supported. + // Refer to List: Native Data Asset Types. + Type NativeDataAssetType `json:"type,omitempty"` + + // Attribute: + // len + // Type: + // integer + // Definition: + // The maximum allowed length of the data value. + Len int64 `json:"len,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/delivery_method.go b/adcom1/delivery_method.go new file mode 100644 index 0000000..3b31bd6 --- /dev/null +++ b/adcom1/delivery_method.go @@ -0,0 +1,11 @@ +package adcom1 + +// DeliveryMethod represents options for the delivery of video or audio content. +type DeliveryMethod int8 + +// Options for the delivery of video or audio content. +const ( + DeliveryStreaming DeliveryMethod = 1 // Streaming + DeliveryProgressive DeliveryMethod = 2 // Progressive + DeliveryDownload DeliveryMethod = 3 // Download +) diff --git a/adcom1/device.go b/adcom1/device.go new file mode 100644 index 0000000..58e09d3 --- /dev/null +++ b/adcom1/device.go @@ -0,0 +1,233 @@ +package adcom1 + +import "encoding/json" + +// Device object provides information pertaining to the device through which the user is interacting. +// Device information includes its hardware, platform, location, and carrier data. +// The device can refer to a mobile handset, a desktop computer, set top box, or other digital device. +type Device struct { + // Attribute: + // type + // Type: + // integer + // Definition: + // The general type of device. + // Refer to List: Device Types. + Type DeviceType `json:"type,omitempty"` + + // Attribute: + // ua + // Type: + // string + // Definition: + // Browser user agent string. + UA string `json:"ua,omitempty"` + + // Attribute: + // ifa + // Type: + // string + // Definition: + // ID sanctioned for advertiser use in the clear (i.e., not hashed). + IFA string `json:"ifa,omitempty"` + + // Attribute: + // dnt + // Type: + // integer + // Definition: + // Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track. + DNT int8 `json:"dnt,omitempty"` + + // Attribute: + // lmt + // Type: + // integer + // Definition: + // “Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines. + Lmt int8 `json:"lmt,omitempty"` + + // Attribute: + // make + // Type: + // string + // Definition: + // Device make (e.g., "Apple"). + Make string `json:"make,omitempty"` + + // Attribute: + // model + // Type: + // string + // Definition: + // Device model (e.g., “iPhone10,1” when the specific device model is known, “iPhone” otherwise). + // The value obtained from the device O/S should be used when available. + Model string `json:"model,omitempty"` + + // Attribute: + // os + // Type: + // integer + // Definition: + // Device operating system. + // Refer to List: Operating Systems. + OS OperatingSystem `json:"os,omitempty"` + + // Attribute: + // osv + // Type: + // string + // Definition: + // Device operating system version (e.g., “3.1.2”). + OSV string `json:"osv,omitempty"` + + // Attribute: + // hwv + // Type: + // string + // Definition: + // Hardware version of the device (e.g., “5S” for iPhone 5S). + HWV string `json:"hwv,omitempty"` + + // Attribute: + // h + // Type: + // integer + // Definition: + // Physical height of the screen in pixels. + H int64 `json:"h,omitempty"` + + // Attribute: + // w + // Type: + // integer + // Definition: + // Physical width of the screen in pixels. + W int64 `json:"w,omitempty"` + + // Attribute: + // ppi + // Type: + // integer + // Definition: + // Screen size as pixels per linear inch. + PPI int64 `json:"ppi,omitempty"` + + // Attribute: + // pxratio + // Type: + // float + // Definition: + // The ratio of physical pixels to device independent pixels. + PxRatio float64 `json:"pxratio,omitempty"` + + // Attribute: + // js + // Type: + // integer + // Definition: + // Support for JavaScript, where 0 = no, 1 = yes. + JS int8 `json:"js,omitempty"` + + // Attribute: + // lang + // Type: + // string + // Definition: + // Browser language using ISO-639-1-alpha-2. + Lang string `json:"lang,omitempty"` + + // Attribute: + // ip + // Type: + // string + // Definition: + // IPv4 address closest to device. + IP string `json:"ip,omitempty"` + + // Attribute: + // ipv6 + // Type: + // string + // Definition: + // IP address closest to device as IPv6. + IPv6 string `json:"ipv6,omitempty"` + + // Attribute: + // xff + // Type: + // string + // Definition: + // The value of the “x-forwarded-for” header. + XFF string `json:"xff,omitempty"` + + // Attribute: + // iptr + // Type: + // integer + // Definition: + // Indicator of truncation of any of the IP attributes (i.e., ip, ipv6, xff), where 0 = no, 1 = yes (e.g., from 1.2.3.4 to 1.2.3.0). + // Refer to https://tools.ietf.org/html/rfc6235#section-4.1.1 for more information on IP truncation. + IPTr int8 `json:"iptr,omitempty"` + + // Attribute: + // carrier + // Type: + // string + // Definition: + // Carrier or ISP (e.g., “VERIZON”) using exchange curated string names which should be published to bidders a priori. + Carrier string `json:"carrier,omitempty"` + + // Attribute: + // mccmnc + // Type: + // string + // Definition: + // Mobile carrier as the concatenated MCC-MNC code (e.g., “310-005” identifies Verizon Wireless CDMA in the USA). + // Refer to https://en.wikipedia.org/wiki/Mobile_country_code for further information and references. + // Note that the dash between the MCC and MNC parts is required to remove parsing ambiguity. + MCCMNC string `json:"mccmnc,omitempty"` + + // Attribute: + // mccmncsim + // Type: + // string + // Definition: + // MCC and MNC of the SIM card using the same format as mccmnc. + // When both values are available, a difference between them reveals that a user is roaming. + MCCMNCSIM string `json:"mccmncsim,omitempty"` + + // Attribute: + // contype + // Type: + // integer + // Definition: + // Network connection type. + // Refer to List: Connection Types. + ConType ConnectionType `json:"contype,omitempty"` + + // Attribute: + // geofetch + // Type: + // integer + // Definition: + // Indicates if the geolocation API will be available to JavaScript code running in display ad, where 0 = no, 1 = yes. + GeoFetch int8 `json:"geofetch,omitempty"` + + // Attribute: + // geo + // Type: + // object + // Definition: + // Location of the device (i.e., typically the user's current location). + // Refer to Object: Geo. + Geo *Geo `json:"geo,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/device_type.go b/adcom1/device_type.go new file mode 100644 index 0000000..bca0e80 --- /dev/null +++ b/adcom1/device_type.go @@ -0,0 +1,16 @@ +package adcom1 + +// DeviceType represents types of devices. +// This table has values derived from the TAG Inventory Quality Guidelines (IQG). +type DeviceType int8 + +// Types of devices. +const ( + DeviceMobile DeviceType = 1 // Mobile/Tablet - General + DevicePC DeviceType = 2 // Personal Computer + DeviceTV DeviceType = 3 // Connected TV + DevicePhone DeviceType = 4 // Phone + DeviceTablet DeviceType = 5 // Tablet + DeviceConnected DeviceType = 6 // Connected Device + DeviceSetTopBox DeviceType = 7 // Set Top Box +) diff --git a/adcom1/display.go b/adcom1/display.go new file mode 100644 index 0000000..fe78b5b --- /dev/null +++ b/adcom1/display.go @@ -0,0 +1,137 @@ +package adcom1 + +import "encoding/json" + +// Display object provides additional detail about an ad specifically for display ads. +// There are multiple attributes for specifying creative details: banner for simple banner images native for native ads, adm for including general markup, and curl for referencing general markup via URL. +// In any given Display object, only one of these attributes should be used to avoid confusion. +// To the extent feasible, structured objects should be favored over general markup for quality and safety issues. +type Display struct { + // Attribute: + // mime + // Type: + // string + // Definition: + // Mime type of the ad (e.g., “image/jpeg”). + MIME string `json:"mime,omitempty"` + + // Attribute: + // api + // Type: + // integer array + // Definition: + // API required by the ad if applicable. + // Refer to List: API Frameworks. + API []APIFramework `json:"api,omitempty"` + + // Attribute: + // ctype + // Type: + // integer + // Definition: + // Subtype of display creative. + // Refer to List: Creative Subtypes - Display. + CType CreativeSubtypeDisplay `json:"ctype,omitempty"` + + // Attribute: + // w + // Type: + // integer + // Definition: + // Absolute width of the creative in device independent pixels (DIPS), typically for non-native ads. + // Note that mixing absolute and relative sizes is not recommended. + W int64 `json:"w,omitempty"` + + // Attribute: + // h + // Type: + // integer + // Definition: + // Absolute height of the creative in device independent pixels (DIPS), typically for non-native ads. + // Note that mixing absolute and relative sizes is not recommended. + H int64 `json:"h,omitempty"` + + // Attribute: + // wratio + // Type: + // integer + // Definition: + // Relative width of the creative when expressing size as a ratio, typically for non-native ads. + // Note that mixing absolute and relative sizes is not recommended. + // Dev note: + // This is kept as `int8` because ratio values are expected to be quite small (like 16:9). + WRatio int8 `json:"wratio,omitempty"` + + // Attribute: + // hratio + // Type: + // integer + // Definition: + // Relative height of the creative when expressing size as a ratio, typically for non-native ads. + // Note that mixing absolute and relative sizes is not recommended. + // Dev note: + // This is kept as `int8` because ratio values are expected to be quite small (like 16:9). + HRatio int8 `json:"hratio,omitempty"` + + // Attribute: + // priv + // Type: + // string + // Definition: + // URL of a page informing the user about a buyer's targeting activity. + Priv string `json:"priv,omitempty"` + + // Attribute: + // adm + // Type: + // string + // Definition: + // General display markup (e.g., HTML, AMPHTML) if not using a structured alternative (e.g., banner, native). + // Note that including both adm and curl is not recommended. + AdM string `json:"adm,omitempty"` + + // Attribute: + // curl + // Type: + // string + // Definition: + // Optional means of retrieving display markup by reference; a URL that can return HTML, AMPHTML, or a collection native Asset object and their subordinates). + // If this ad is matched to a Placement specification, the Placement.curlx attribute indicates if this markup retrieval option is supported. + // Note that including both adm and curl is not recommended. + CURL string `json:"curl,omitempty"` + + // Attribute: + // banner + // Type: + // object + // Definition: + // Structured banner image object, recommended for simple banner creatives. + // Refer to Object: Banner. + Banner *Banner `json:"banner,omitempty"` + + // Attribute: + // native + // Type: + // object + // Definition: + // Structured native object, recommended for native ads. + // Refer to Object: Native. + Native *Native `json:"native,omitempty"` + + // Attribute: + // event + // Type: + // object array + // Definition: + // Array of events that the advertiser or buying platform wants to track. + // Refer to Object: Event. + Event []Event `json:"event,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/display_context_type.go b/adcom1/display_context_type.go new file mode 100644 index 0000000..9ade7eb --- /dev/null +++ b/adcom1/display_context_type.go @@ -0,0 +1,24 @@ +package adcom1 + +// DisplayContextType represents types of context in which a native ad may appear (i.e., the type of content surrounding the ad on the page). +// This is intended to denote primary content although other content may also appear on the page. +// Note that there are two levels of detail grouped by 10s (i.e., 12 is a refined case of 100). +type DisplayContextType int + +// Types of context in which a native ad may appear (i.e., the type of content surrounding the ad on the page). +// +// Values of 500+ hold vendor-specific codes. +const ( + DisplayContextContent DisplayContextType = 10 // Content-centric context (e.g., newsfeed, article, image gallery, video gallery, etc.). + DisplayContextContentArticle DisplayContextType = 11 // - Primarily article content, which could include images, etc. as part of the article. + DisplayContextContentVideo DisplayContextType = 12 // - Primarily video content. + DisplayContextContentAudio DisplayContextType = 13 // - Primarily audio content. + DisplayContextContentImage DisplayContextType = 14 // - Primarily image content. + DisplayContextContentUserGenerated DisplayContextType = 15 // - User-generated content (e.g., forums, comments, etc.). + DisplayContextSocial DisplayContextType = 20 // Social-centric context (e.g., social network feed, email, chat, etc.). + DisplayContextSocialEmail DisplayContextType = 21 // - Primarily email content. + DisplayContextSocialChat DisplayContextType = 22 // - Primarily chat/IM content. + DisplayContextProduct DisplayContextType = 30 // Product context (e.g., product listings, details, recommendations, reviews, etc.). + DisplayContextProductApp DisplayContextType = 31 // - App store/marketplace. + DisplayContextProductReview DisplayContextType = 32 // - Product reviews site primarily, which may sell product secondarily. +) diff --git a/adcom1/display_format.go b/adcom1/display_format.go new file mode 100644 index 0000000..08273a2 --- /dev/null +++ b/adcom1/display_format.go @@ -0,0 +1,63 @@ +package adcom1 + +import "encoding/json" + +// DisplayFormat object represents an allowed set of parameters for a banner display ad and often appears as an array when multiple sizes are permitted. +type DisplayFormat struct { + // Attribute: + // w + // Type: + // integer + // Definition: + // Absolute width of the creative in units specified by DisplayPlacement.unit. + // Note that mixing absolute and relative sizes is not recommended. + W int64 `json:"w,omitempty"` + + // Attribute: + // h + // Type: + // integer + // Definition: + // Absolute height of the creative in units specified by DisplayPlacement.unit. + // Note that mixing absolute and relative sizes is not recommended. + H int64 `json:"h,omitempty"` + + // Attribute: + // wratio + // Type: + // integer + // Definition: + // Relative width of the creative when expressing size as a ratio. + // Note that mixing absolute and relative sizes is not recommended. + // Dev note: + // This is kept as `int8` because ratio values are expected to be quite small (like 16:9). + WRatio int8 `json:"wratio,omitempty"` + + // Attribute: + // hratio + // Type: + // integer + // Definition: + // Relative height of the creative when expressing size as a ratio. + // Note that mixing absolute and relative sizes is not recommended. + // Dev note: + // This is kept as `int8` because ratio values are expected to be quite small (like 16:9). + HRatio int8 `json:"hratio,omitempty"` + + // Attribute: + // expdir + // Type: + // integer array + // Definition: + // Directions in which the creative is permitted to expand. + // Refer to List: Expandable Directions. + ExpDir []ExpandableDirection `json:"expdir,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/display_placement.go b/adcom1/display_placement.go new file mode 100644 index 0000000..36c58bf --- /dev/null +++ b/adcom1/display_placement.go @@ -0,0 +1,175 @@ +package adcom1 + +import "encoding/json" + +// DisplayPlacement object signals that the placement may be a display placement. +// It provides additional detail about permitted display ads including simple banners, AMPHTML (i.e., Accelerated Mobile Pages), and native. +type DisplayPlacement struct { + // Attribute: + // pos + // Type: + // integer + // Definition: + // Placement position on screen. + // Refer to List: Placement Positions. + Pos PlacementPosition `json:"pos,omitempty"` + + // Attribute: + // instl + // Type: + // integer; default 0 + // Definition: + // Indicates if this is an interstitial placement, where 0 = no, 1 = yes. + Instl int8 `json:"instl,omitempty"` + + // Attribute: + // topframe + // Type: + // integer + // Definition: + // Indicates if the placement will be loaded into an iframe or not, where 0 = unfriendly iframe or unknown, 1 = top frame, friendly iframe, or SafeFrame. + // A value of "1" can be understood to mean that expandable ads are technically capable of being delivered. + TopFrame int8 `json:"topframe,omitempty"` + + // Attribute: + // ifrbust + // Type: + // string array + // Definition: + // Array of iframe busters supported by this placement. + // The meaning of strings in this attribute must be coordinated a priori among vendors. + IfrBust []string `json:"ifrbust,omitempty"` + + // Attribute: + // clktype + // Type: + // integer; default 1 + // Definition: + // Indicates the click type of this placement. + // Refer to List: Click Types. + ClkType ClickType `json:"clktype,omitempty"` + + // Attribute: + // ampren + // Type: + // integer + // Definition: + // AMPHTML rendering treatment for AMP ads in this placement, where 1 = early loading, 2 = standard loading. + AMPRen int8 `json:"ampren,omitempty"` + + // Attribute: + // ptype + // Type: + // Integer; recommended + // Definition: + // The display placement type. + // Refer to List: Display Placement Types. + PType DisplayPlacementType `json:"ptype,omitempty"` + + // Attribute: + // context + // Type: + // integer; recommended + // Definition: + // The context of the placement. + // Refer to List: Display Context Types. + Context DisplayContextType `json:"context,omitempty"` + + // Attribute: + // mime + // Type: + // string array + // Definition: + // Array of supported mime types (e.g., “image/jpeg”, “image/gif”). + // If omitted, all types are assumed. + MIME []string `json:"mime,omitempty"` + + // Attribute: + // api + // Type: + // integer array + // Definition: + // List of supported APIs. + // If an API is not explicitly listed, it is assumed to be unsupported. + // Refer to List: API Frameworks. + API []APIFramework `json:"api,omitempty"` + + // Attribute: + // ctype + // Type: + // integer array + // Definition: + // Creative subtypes permitted. + // Refer to List: Creative Subtypes - Display. + CType []CreativeSubtypeDisplay `json:"ctype,omitempty"` + + // Attribute: + // w + // Type: + // integer + // Definition: + // Width of the placement in units specified by unit. + // Note that this size applies to the placement itself; permitted creative sizes are specified elsewhere (e.g., DisplayFormat, ImageAssetFormat, etc.). + W int64 `json:"w,omitempty"` + + // Attribute: + // h + // Type: + // integer + // Definition: + // Width of the placement in units specified by unit. + // Note that this size applies to the placement itself; permitted creative sizes are specified elsewhere (e.g., DisplayFormat, ImageAssetFormat, etc.). + H int64 `json:"h,omitempty"` + + // Attribute: + // unit + // Type: + // integer; default 1 + // Definition: + // Unit of size used for placement size (i.e., w and h attributes). + // Refer to List: Size Units. + Unit SizeUnit `json:"unit,omitempty"` + + // Attribute: + // priv + // Type: + // integer; default 0 + // Definition: + // Indicator of whether or not the placement supports a buyer-specific privacy notice URL, where 0 = no, 1 = yes. + Priv int8 `json:"priv,omitempty"` + + // Attribute: + // displayfmt + // Type: + // object array + // Definition: + // Array of objects that govern the attributes (e.g., sizes) of a banner display placement. + // Refer to Object: DisplayFormat. + DisplayFmt []DisplayFormat `json:"displayfmt,omitempty"` + + // Attribute: + // nativefmt + // Type: + // object + // Definition: + // This object specified the required and permitted assets and attributes of a native display placement. + // Refer to Object: NativeFormat. + NativeFmt *NativeFormat `json:"nativefmt,omitempty"` + + // Attribute: + // event + // Type: + // object array + // Definition: + // Array of supported ad tracking events. + // Refer to Object: EventSpec. + Event []EventSpec `json:"event,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/display_placement_type.go b/adcom1/display_placement_type.go new file mode 100644 index 0000000..368e66b --- /dev/null +++ b/adcom1/display_placement_type.go @@ -0,0 +1,14 @@ +package adcom1 + +// DisplayPlacementType represents types of display placements; the locations where a native ad may be shown in relationship to the surrounding content. +type DisplayPlacementType int + +// General types of display placements. +// +// Values of 500+ hold vendor-specific codes. +const ( + DisplayPlacementFeed DisplayPlacementType = 1 // In the feed of content (e.g., as an item inside the organic feed, grid, listing, carousel, etc.). + DisplayPlacementUnit DisplayPlacementType = 2 // In the atomic unit of the content (e.g., in the article page or single image page). + DisplayPlacementOutside DisplayPlacementType = 3 // Outside the core content (e.g., in the ads section on the right rail, as a banner-style placement near the content, etc.). + DisplayPlacementWidget DisplayPlacementType = 4 // Recommendation widget; most commonly presented below article content. +) diff --git a/adcom1/distribution_channel.go b/adcom1/distribution_channel.go new file mode 100644 index 0000000..6e6bc39 --- /dev/null +++ b/adcom1/distribution_channel.go @@ -0,0 +1,43 @@ +package adcom1 + +// DistributionChannel is an abstraction of the various types of entities or channels through which ads are distributed. +// Examples include websites, mobile apps, and digital out-of-home (DOOH) systems. +// This generalized class contains those attributes and relationships that are common to all distribution channels and as such, all of its attributes and relationships are inherited by each of its derived classes. +// +// Note: As an abstract class, a DistributionChannel is never instantiated on its own. +// Only objects of its derived classes are actually realized. +type DistributionChannel struct { + // Attribute: + // id + // Type: + // string; recommended + // Definition: + // Vendor-specific unique identifier of the distribution channel. + ID string `json:"id,omitempty"` + + // Attribute: + // name + // Type: + // string + // Definition: + // Displayable name of the distribution channel. + Name string `json:"name,omitempty"` + + // Attribute: + // pub + // Type: + // object + // Definition: + // Details about the publisher of the distribution channel. + // Refer to Object: Publisher. + Pub *Publisher `json:"pub,omitempty"` + + // Attribute: + // content + // Type: + // object + // Definition: + // Details about the content within the distribution channel. + // Refer to Object: Content. + Content *Content `json:"content,omitempty"` +} diff --git a/adcom1/dooh.go b/adcom1/dooh.go new file mode 100644 index 0000000..9e301ff --- /dev/null +++ b/adcom1/dooh.go @@ -0,0 +1,50 @@ +package adcom1 + +import "encoding/json" + +// DOOH object is used to define an ad supported digital out-of-home (DOOH) experience such as a public kiosk or digital billboard. +// As a derived class, a Dooh object inherits all DistributionChannel attributes and adds those defined below. +type DOOH struct { + DistributionChannel + + // Attribute: + // venue + // Type: + // integer + // Definition: + // The type of out-of-home venue. + // Refer to List: DOOH Venue TypesList: DOOH Venue Types. + Venue DOOHVenueType `json:"venue,omitempty"` + + // Attribute: + // fixed + // Type: + // integer + // Definition: + // Indicates whether the DOOH placement is in a fixed location (e.g., kiosk, billboard, elevator) or is movable (e.g., taxi), where 1 = fixed, 2 = movable. + Fixed int8 `json:"fixed,omitempty"` + + // Attribute: + // etime + // Type: + // integer + // Definition: + // The exposure time in seconds per view that the creative will be displayed before refreshing to the next creative. + ETime int64 `json:"etime,omitempty"` + + // Attribute: + // dpi + // Type: + // integer + // Definition: + // Minimum DPI for text-based creative elements to display clearly. + DPI int64 `json:"dpi,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/dooh_venue_type.go b/adcom1/dooh_venue_type.go new file mode 100644 index 0000000..583f502 --- /dev/null +++ b/adcom1/dooh_venue_type.go @@ -0,0 +1,67 @@ +package adcom1 + +// DOOHVenueType represents the digital out-of-home venue types and is derived from DPAA Programmatic Standards. +type DOOHVenueType int + +// Digital out-of-home venue types. +// +// Values of 500+ hold vendor-specific codes. +const ( + VenueAirborne DOOHVenueType = 1 // Airborne + VenueAirportsGeneral DOOHVenueType = 2 // Airports - General + VenueAirportsBaggageClaim DOOHVenueType = 3 // Airports - Baggage Claim + VenueAirportsTerminal DOOHVenueType = 4 // Airports - Terminal + VenueAirportsLounge DOOHVenueType = 5 // Airports - Lounges + VenueATM DOOHVenueType = 6 // ATMs + VenueBacklight DOOHVenueType = 7 // Backlights + VenueBars DOOHVenueType = 8 // Bars + VenueBench DOOHVenueType = 9 // Benches + VenueBikeRack DOOHVenueType = 10 // Bike Racks + VenueBulletin DOOHVenueType = 11 // Bulletins + VenueBuses DOOHVenueType = 12 // Buses + VenueCafes DOOHVenueType = 13 // Cafes + VenueCasualDining DOOHVenueType = 14 // Casual Dining Restaurants + VenueChildCare DOOHVenueType = 15 // Child Care + VenueCinema DOOHVenueType = 16 // Cinema + VenueCityInformationPanel DOOHVenueType = 17 // City Information Panels + VenueConvenienceStore DOOHVenueType = 18 // Convenience Stores + VenueDedicatedWildPosting DOOHVenueType = 19 // Dedicated Wild Posting + VenueDoctorsOffice DOOHVenueType = 20 // Doctors Offices - General + VenueDoctorsOfficeObstetrics DOOHVenueType = 21 // Doctors Offices - Obstetrics + VenueDoctorsOfficePediatrics DOOHVenueType = 22 // Doctors Offices - Pediatrics + VenueFamilyEntertainment DOOHVenueType = 23 // Family entertainment + VenueFerry DOOHVenueType = 24 // Ferries + VenueFinancialService DOOHVenueType = 25 // Financial Services + VenueGasStation DOOHVenueType = 26 // Gas Stations + VenueGolfCourse DOOHVenueType = 27 // Golf Courses + VenueGym DOOHVenueType = 28 // Gyms + VenueHospital DOOHVenueType = 29 // Hospitals + VenueHotel DOOHVenueType = 30 // Hotels + VenueJuniorPoster DOOHVenueType = 31 // Junior Posters + VenueKiosk DOOHVenueType = 32 // Kiosks + VenueMall DOOHVenueType = 33 // Malls - General + VenueMallFoodCourt DOOHVenueType = 34 // Malls - Food Courts + VenueMarine DOOHVenueType = 35 // Marine + VenueMobileBillboard DOOHVenueType = 36 // Mobile Billboards + VenueMovieTheaterLobby DOOHVenueType = 37 // Movie Theater Lobbies + VenueNewsStand DOOHVenueType = 38 // Newsstands + VenueOfficeBuilding DOOHVenueType = 39 // Office Buildings + VenuePhoneKiosk DOOHVenueType = 40 // Phone Kiosks + VenuePoster DOOHVenueType = 41 // Posters + VenueQSR DOOHVenueType = 42 // QSR [Quick-Service Restaurants / Fast-Food] + VenueRail DOOHVenueType = 43 // Rail + VenueReceptacle DOOHVenueType = 44 // Receptacles + VenueResortLeisure DOOHVenueType = 45 // Resorts / Leisure + VenueRetail DOOHVenueType = 46 // Retail + VenueSalon DOOHVenueType = 47 // Salons + VenueShelter DOOHVenueType = 48 // Shelters + VenueSportsArena DOOHVenueType = 49 // Sports Arenas + VenueSubway DOOHVenueType = 50 // Subway + VenueTaxi DOOHVenueType = 51 // Taxis / Wrapped vehicles + VenueTruckSide DOOHVenueType = 52 // Truckside + VenueUniversity DOOHVenueType = 53 // Universities + VenueUrbanPanel DOOHVenueType = 54 // Urban Panels + VenueVeterinarianOffice DOOHVenueType = 55 // Veterinarian Offices + VenueWallSpectacular DOOHVenueType = 56 // Walls / Spectaculars + VenueOther DOOHVenueType = 57 // Other +) diff --git a/adcom1/event.go b/adcom1/event.go new file mode 100644 index 0000000..f08ceb9 --- /dev/null +++ b/adcom1/event.go @@ -0,0 +1,59 @@ +package adcom1 + +import "encoding/json" + +// Event object specifies a type of event that the advertiser or buying platform wants to track along with the information required to do so. +type Event struct { + // Attribute: + // type + // Type: + // integer; required + // Definition: + // Type of event to track. + // Refer to List: Event Types. + Type EventType `json:"type"` + + // Attribute: + // method + // Type: + // integer; required + // Definition: + // Method of tracking requested. + // Refer to List: Event Tracking Methods. + Method EventTrackingMethod `json:"method"` + + // Attribute: + // api + // Type: + // integer array + // Definition: + // The APIs being used by the tracker; only relevant when the tracking method is JavaScript. + // Refer to List: API Frameworks. + API []APIFramework `json:"api,omitempty"` + + // Attribute: + // url + // Type: + // string; required * + // Definition: + // The URL of the tracking pixel or JavaScript tag, respectively. + // * Required for Image-Pixel or JavaScript methods. + URL string `json:"url,omitempty"` + + // Attribute: + // cdata + // Type: + // object (Map) + // Definition: + // An array of key-value pairs to support vendor-specific data required for custom tracking. + // For example, the account number of a buyer with a tracking company might be represented as: {"acct": "123"}. + CData map[string]string `json:"cdata,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/event_spec.go b/adcom1/event_spec.go new file mode 100644 index 0000000..3c50a0b --- /dev/null +++ b/adcom1/event_spec.go @@ -0,0 +1,76 @@ +package adcom1 + +import "encoding/json" + +// EventSpec object specifies a type of ad tracking event and which methods of tracking are available for it. +// This object may appear as an array for a given placement indicating various types of available tracking events. +type EventSpec struct { + // Attribute: + // type + // Type: + // integer; required + // Definition: + // Type of supported ad tracking event. + // Refer to List: Event Types. + Type EventType `json:"type,omitempty"` + + // Attribute: + // method + // Type: + // integer array + // Definition: + // Array of supported event tracking methods for this event type. + // Refer to List: Event Tracking Methods. + Method []EventTrackingMethod `json:"method,omitempty"` + + // Attribute: + // api + // Type: + // integer array + // Definition: + // Event tracking APIs available for use; only relevant for JavaScript method trackers. + // Refer to List: API Frameworks. + API []APIFramework `json:"api,omitempty"` + + // Attribute: + // jstrk + // Type: + // string array + // Definition: + // Array of domains, top two levels only (e.g., “tracker.com”), that constitute a restriction list of JavaScript trackers. + // The sense of the restrictions is determined by wjs. + JSTrk []string `json:"jstrk,omitempty"` + + // Attribute: + // wjs + // Type: + // integer; default 1 + // Definition: + // Sense of the jstrk restriction list, where 0 = block list, 1 = whitelist. + WJS int8 `json:"wjs,omitempty"` + + // Attribute: + // pxtrk + // Type: + // string array + // Definition: + // Array of domains, top two levels only (e.g., “tracker.com”), that constitute a restriction list of pixel image trackers. + // The sense of the restrictions is determined by wpx. + PxTrk []string `json:"pxtrk,omitempty"` + + // Attribute: + // wpx + // Type: + // integer; default 1 + // Definition: + // Sense of the pxtrk restriction list, where 0 = block list, 1 = whitelist. + WPx int8 `json:"wpx,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/event_tracking_method.go b/adcom1/event_tracking_method.go new file mode 100644 index 0000000..5fdae92 --- /dev/null +++ b/adcom1/event_tracking_method.go @@ -0,0 +1,13 @@ +package adcom1 + +// EventTrackingMethod represents methods of tracking of ad events. +// Vendor specific codes may include custom measurement companies (e.g., Moat, Doubleverify, IAS, etc.). +type EventTrackingMethod int + +// Available methods of tracking of ad events. +// +// Values of 500+ hold vendor-specific codes. +const ( + TrackingImagePixel EventTrackingMethod = 1 // Image-Pixel: URL provided will be inserted as a 1x1 pixel at the time of the event. + TrackingJS EventTrackingMethod = 2 // JavaScript: URL provided will be inserted as a JavaScript tag at the time of the event. +) diff --git a/adcom1/event_type.go b/adcom1/event_type.go new file mode 100644 index 0000000..e6f3b78 --- /dev/null +++ b/adcom1/event_type.go @@ -0,0 +1,17 @@ +package adcom1 + +// EventType represents types of ad events available for tracking. +// These types refer to the actual event, timing, etc.; not the method of firing. +// Scripts that are performing measurement should be deployed at the "loaded" event. +type EventType int + +// Types of ad events available for tracking +// +// Values of 500+ hold vendor-specific codes. +const ( + EventLoaded EventType = 1 // loaded: Delivered as a part of the creative markup. Creative may be pre-cached or pre-loaded; prior to initial rendering. + EventImpression EventType = 2 // impression: Ad impression per IAB/MRC Ad Impression Measurement Guidelines. + EventViewMRC50 EventType = 3 // viewable-mrc50: Visible impression using MRC definition of 50% in view for 1 second. + EventViewMRC100 EventType = 4 // viewable-mrc100: 100% in view for 1 second (i.e., the GroupM standard). + EventViewVideo50 EventType = 5 // viewable-video50: Visible impression for video using MRC definition of 50% in view for 2 seconds. +) diff --git a/adcom1/expandable_direction.go b/adcom1/expandable_direction.go new file mode 100644 index 0000000..1d8519c --- /dev/null +++ b/adcom1/expandable_direction.go @@ -0,0 +1,13 @@ +package adcom1 + +// ExpandableDirection represents directions in which an expandable ad may expand, given the positioning of the ad unit on the page and constraints imposed by the content. +type ExpandableDirection int8 + +// Directions in which an expandable ad may expand. +const ( + ExpandableLeft ExpandableDirection = 1 // Left + ExpandableRight ExpandableDirection = 2 // Right + ExpandableUp ExpandableDirection = 3 // Up + ExpandableDown ExpandableDirection = 4 // Down + ExpandableFullScreen ExpandableDirection = 5 // Full Screen +) diff --git a/adcom1/feed_type.go b/adcom1/feed_type.go new file mode 100644 index 0000000..1452278 --- /dev/null +++ b/adcom1/feed_type.go @@ -0,0 +1,11 @@ +package adcom1 + +// FeedType represents types of feeds, typically for audio. +type FeedType int8 + +// Types of feeds, typically for audio. +const ( + FeedMusicService FeedType = 1 // Music Service + FeedRadioBroadcast FeedType = 2 // FM/AM Broadcast + FeedPodcast FeedType = 3 // Podcast +) diff --git a/adcom1/geo.go b/adcom1/geo.go new file mode 100644 index 0000000..bc6b79e --- /dev/null +++ b/adcom1/geo.go @@ -0,0 +1,125 @@ +package adcom1 + +import "encoding/json" + +// Geo object encapsulates various methods for specifying a geographic location. +// When subordinate to a Device object, it indicates the location of the device which can also be interpreted as the user's current location. +// When subordinate to a User object, it indicates the location of the user's home base (i.e., not necessarily their current location). +// +// The lat and lon attributes should only be passed if they conform to the accuracy depicted in the type attribute. +// For example, the centroid of a large region (e.g., postal code) should not be passed. +type Geo struct { + // Attribute: + // type + // Type: + // integer + // Definition: + // Source of location data; recommended when passing lat/lon. + // Refer to List: Location Types. + Type LocationType `json:"type,omitempty"` + + // Attribute: + // lat + // Type: + // float + // Definition: + // Latitude from -90.0 to +90.0, where negative is south. + Lat float64 `json:"lat,omitempty"` + + // Attribute: + // lon + // Type: + // float + // Definition: + // Longitude from -180.0 to +180.0, where negative is west. + Lon float64 `json:"lon,omitempty"` + + // Attribute: + // accur + // Type: + // integer + // Definition: + // Estimated location accuracy in meters; recommended when lat/lon are specified and derived from a device's location services (i.e., type = 1). + // Note that this is the accuracy as reported from the device. + // Consult OS specific documentation (e.g., Android, iOS) for exact interpretation. + Accur int64 `json:"accur,omitempty"` + + // Attribute: + // lastfix + // Type: + // integer + // Definition: + // Number of seconds since this geolocation fix was established. + // Note that devices may cache location data across multiple fetches. + // Ideally, this value should be from the time the actual fix was taken. + LastFix int64 `json:"lastfix,omitempty"` + + // Attribute: + // ipserv + // Type: + // integer + // Definition: + // Service or provider used to determine geolocation from IP address if applicable (i.e., type = 2). + // Refer to List: IP Location Services. + IPServ IPLocationService `json:"ipserv,omitempty"` + + // Attribute: + // country + // Type: + // string + // Definition: + // Country code using ISO-3166-1-alpha-2. + // Note that alpha-3 codes may be encountered and vendors are encouraged to be tolerant of them. + Country string `json:"country,omitempty"` + + // Attribute: + // region + // Type: + // string + // Definition: + // Region code using ISO-3166-2; 2-letter state code if USA. + Region string `json:"region,omitempty"` + + // Attribute: + // metro + // Type: + // string + // Definition: + // Regional marketing areas such as Nielsen's DMA codes or other similar taxonomy to be agreed among vendors prior to use. + // Note that DMA is a trademarked asset of The Nielsen Company. + // Vendors are encouraged to ensure their use of DMAs is properly licensed. + Metro string `json:"metro,omitempty"` + + // Attribute: + // city + // Type: + // string + // Definition: + // City using United Nations Code for Trade & Transport Locations “UN/LOCODE” with the space between country and city suppressed (e.g., Boston MA, USA = “USBOS”). + // Refer to UN/LOCODE Code List. + City string `json:"city,omitempty"` + + // Attribute: + // zip + // Type: + // string + // Definition: + // ZIP or postal code. + ZIP string `json:"zip,omitempty"` + + // Attribute: + // utcoffset + // Type: + // integer + // Definition: + // Local time as the number +/- of minutes from UTC. + UTCOffset int64 `json:"utcoffset,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/image_asset.go b/adcom1/image_asset.go new file mode 100644 index 0000000..b3e7308 --- /dev/null +++ b/adcom1/image_asset.go @@ -0,0 +1,48 @@ +package adcom1 + +import "encoding/json" + +// ImageAsset object identifies the native asset as a image asset. +// Image assets are use for such elements as the actual creative images and icons. +type ImageAsset struct { + // Attribute: + // url + // Type: + // string; required + // Definition: + // A URL that returns the image for the asset. + URL string `json:"url,omitempty"` + + // Attribute: + // w + // Type: + // integer; recommended + // Definition: + // Width of the image asset in device independent pixels (DIPS). + W int64 `json:"w,omitempty"` + + // Attribute: + // h + // Type: + // integer; recommended + // Definition: + // Height of the image asset in device independent pixels (DIPS). + H int64 `json:"h,omitempty"` + + // Attribute: + // type + // Type: + // integer + // Definition: + // The type of image represented by this asset. + // Refer to List: Native Image Asset Types. + Type NativeImageAssetType `json:"type,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/image_asset_format.go b/adcom1/image_asset_format.go new file mode 100644 index 0000000..5099fad --- /dev/null +++ b/adcom1/image_asset_format.go @@ -0,0 +1,91 @@ +package adcom1 + +import "encoding/json" + +// ImageAssetFormat object is used to provide native asset format specifications for an image element. +// Image elements are typically used for the actual creative image and icons. +type ImageAssetFormat struct { + // Attribute: + // type + // Type: + // integer + // Definition: + // The type of image asset supported. + // Refer to List: Native Image Asset Types. + Type NativeImageAssetType `json:"type,omitempty"` + + // Attribute: + // mime + // Type: + // string array + // Definition: + // Array of supported mime types (e.g., “image/jpeg”, “image/gif”). + // If omitted, all types are assumed. + MIME []string `json:"mime,omitempty"` + + // Attribute: + // w + // Type: + // integer + // Definition: + // Absolute width of the image asset in device independent pixels (DIPS). + // Note that mixing absolute and relative sizes is not recommended. + W int64 `json:"w,omitempty"` + + // Attribute: + // h + // Type: + // integer + // Definition: + // Absolute height of the image asset in device independent pixels (DIPS). + // Note that mixing absolute and relative sizes is not recommended. + H int64 `json:"h,omitempty"` + + // Attribute: + // wmin + // Type: + // integer + // Definition: + // The minimum requested absolute width of the image in device independent pixels (DIPS). + // This option should be used for any scaling of images by the client. + WMin int64 `json:"wmin,omitempty"` + + // Attribute: + // hmin + // Type: + // integer + // Definition: + // The minimum requested absolute height of the image in device independent pixels (DIPS). + // This option should be used for any scaling of images by the client. + HMin int64 `json:"hmin,omitempty"` + + // Attribute: + // wratio + // Type: + // integer + // Definition: + // Relative width of the image asset when expressing size as a ratio. + // Note that mixing absolute and relative sizes is not recommended. + // Dev note: + // This is kept as `int8` because ratio values are expected to be quite small (like 16:9). + WRatio int8 `json:"wratio,omitempty"` + + // Attribute: + // hratio + // Type: + // integer + // Definition: + // Relative height of the image asset when expressing size as a ratio. + // Note that mixing absolute and relative sizes is not recommended. + // Dev note: + // This is kept as `int8` because ratio values are expected to be quite small (like 16:9). + HRatio int8 `json:"hratio,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/ip_location_service.go b/adcom1/ip_location_service.go new file mode 100644 index 0000000..395ec1b --- /dev/null +++ b/adcom1/ip_location_service.go @@ -0,0 +1,12 @@ +package adcom1 + +// IPLocationService represents services and/or vendors used for resolving IP addresses to geolocations. +type IPLocationService int8 + +// Services and/or vendors used for resolving IP addresses to geolocations. +const ( + LocationServiceIP2Location IPLocationService = 1 // ip2location + LocationServiceNeustar IPLocationService = 2 // Neustar (Quova) + LocationServiceMaxMind IPLocationService = 3 // MaxMind + LocationServiceNetAcuity IPLocationService = 4 // NetAcuity (Digital Element) +) diff --git a/adcom1/item_spec.go b/adcom1/item_spec.go new file mode 100644 index 0000000..b91f142 --- /dev/null +++ b/adcom1/item_spec.go @@ -0,0 +1,10 @@ +package adcom1 + +// ItemSpec represents a bunch of data for OpenRTB 3 Item.spec field. +// Refer to OpenRTB 3.0 specification for details. +// +// For AdCOM v1.x, the objects allowed here are Placement and any objects subordinate to these as specified by AdCOM. +// +type ItemSpec struct { + Placement *Placement `json:"placement,omitempty"` +} diff --git a/adcom1/linearity_mode.go b/adcom1/linearity_mode.go new file mode 100644 index 0000000..0a09de2 --- /dev/null +++ b/adcom1/linearity_mode.go @@ -0,0 +1,10 @@ +package adcom1 + +// LinearityMode represents options for media linearity, typically for video. +type LinearityMode int8 + +// Options for media linearity, typically for video. +const ( + LinearityLinear LinearityMode = 1 // Linear (i.e., In-Stream such as Pre-Roll, Mid-Roll, Post-Roll) + LinearityNonLinear LinearityMode = 2 // Non-Linear (i.e., Overlay) +) diff --git a/adcom1/link_asset.go b/adcom1/link_asset.go new file mode 100644 index 0000000..4ef8ca9 --- /dev/null +++ b/adcom1/link_asset.go @@ -0,0 +1,39 @@ +package adcom1 + +import "encoding/json" + +// LinkAsset object identifies the native asset as a link asset and is used to define navigation for call-to-action or other activations (i.e., clicks) +// A link asset can be independent or associated with the overall native ad (i.e., a default for all assets). +type LinkAsset struct { + // Attribute: + // url + // Type: + // string; required + // Definition: + // Landing URL of the clickable link. + URL string `json:"url,omitempty"` + + // Attribute: + // urlfb + // Type: + // string + // Definition: + // Fallback URL for deep-link to be used if the URL specified in url is not supported by the device. + URLFB string `json:"urlfb,omitempty"` + + // Attribute: + // trkr + // Type: + // string array + // Definition: + // List of third-party tracker URLs to be fired on click. + Trkr []string `json:"trkr,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/location_type.go b/adcom1/location_type.go new file mode 100644 index 0000000..97e67da --- /dev/null +++ b/adcom1/location_type.go @@ -0,0 +1,11 @@ +package adcom1 + +// LocationType represents options to indicate how the geographic information was determined. +type LocationType int8 + +// Options to indicate how the geographic information was determined. +const ( + LocationGPS LocationType = 1 // GPS/Location Services + LocationIP LocationType = 2 // IP Address + LocationUserProvided LocationType = 3 // User Provided (e.g., registration data) +) diff --git a/adcom1/media_rating.go b/adcom1/media_rating.go new file mode 100644 index 0000000..b9df84d --- /dev/null +++ b/adcom1/media_rating.go @@ -0,0 +1,12 @@ +package adcom1 + +// MediaRating represents media ratings used in describing content based on the TAG Inventory Quality Guidelines (IQG) v2.1 categorization. +// Refer to www.iab.com/guidelines/digital-video-suite for more information. +type MediaRating int8 + +// Media ratings used in describing content based on the TAG Inventory Quality Guidelines (IQG) v2.1 categorization. +const ( + MediaRatingAll MediaRating = 1 // All Audiences + MediaRatingOver12 MediaRating = 2 // Everyone Over Age 12 + MediaRatingMature MediaRating = 3 // Mature Audiences +) diff --git a/adcom1/native.go b/adcom1/native.go new file mode 100644 index 0000000..0075d83 --- /dev/null +++ b/adcom1/native.go @@ -0,0 +1,32 @@ +package adcom1 + +import "encoding/json" + +// Native object is the root of a structure that defines a native display ad. +type Native struct { + // Attribute: + // link + // Type: + // object + // Definition: + // Default destination link for the native ad overall; used if an asset is activated (e.g., clicked) that doesn't specify it's own destination link. + // Refer to Object: LinkAsset. + Link *LinkAsset `json:"link,omitempty"` + + // Attribute: + // asset + // Type: + // object array + // Definition: + // Array of assets that comprise the native ad. + // Refer to Object: Asset. + Asset []Asset `json:"asset,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/native_data_asset_type.go b/adcom1/native_data_asset_type.go new file mode 100644 index 0000000..fda98e5 --- /dev/null +++ b/adcom1/native_data_asset_type.go @@ -0,0 +1,24 @@ +package adcom1 + +// NativeDataAssetType represents data asset types. +// This list is non-exhaustive and is intended to be expanded over time. +// Size recommendations are noted as "maximum length of at least", which means the publisher or supply platform should support a maximum length of at least this value and the buying platform knows that a string of this size should be accepted. +type NativeDataAssetType int + +// Common data asset types. +// +// Values of 500+ hold vendor-specific codes. +const ( + DataAssetSponsored NativeDataAssetType = 1 // sponsored: "Sponsored By" message which should contain the brand name of the sponsor. Recommended maximum length of at least 25 characters. + DataAssetDesc NativeDataAssetType = 2 // desc: Descriptive text associated with the product or service being advertised. Long text lengths may be truncated or ellipsed when rendered. Recommended maximum length of at least 140 characters. + DataAssetRating NativeDataAssetType = 3 // rating: Numeric rating of the product (e.g., an app's rating). Recommended integer range of 0-5. + DataAssetLikes NativeDataAssetType = 4 // likes: Number of social ratings or "likes" of the product. + DataAssetDownloads NativeDataAssetType = 5 // downloads: Number downloads and/or installs of the product. + DataAssetPrice NativeDataAssetType = 6 // price: Price of the product, app, or in-app purchase. Value should include currency symbol in localized format (e.g., "$10"). + DataAssetSalePrice NativeDataAssetType = 7 // saleprice: Sale price that can be used together with "price" to indicate a comparative discounted price. Value should include currency symbol in localized format (e.g., "$8.50"). + DataAssetPhone NativeDataAssetType = 8 // phone: A formatted phone number. + DataAssetAddress NativeDataAssetType = 9 // address: A formatted address. + DataAssetDesc2 NativeDataAssetType = 10 // desc2: Additional descriptive text associated with the product. + DataAssetDisplayURL NativeDataAssetType = 11 // displayurl: Display URL for the ad. To be used when sponsoring entity doesn't own the content (e.g., "Sponsored by Brand on Site", where Site is specified in this data asset). + DataAssetCTAText NativeDataAssetType = 12 // ctatext: Description of the call to action (CTA) button for the destination URL. Recommended maximum length of at least 15 characters. +) diff --git a/adcom1/native_format.go b/adcom1/native_format.go new file mode 100644 index 0000000..8739322 --- /dev/null +++ b/adcom1/native_format.go @@ -0,0 +1,24 @@ +package adcom1 + +import "encoding/json" + +// NativeFormat object refines a display placement to be specifically a native display placement. +// It serves as the root of a structure that includes the specifications for each of the assets that comprise the native placement. +type NativeFormat struct { + // Attribute: + // asset + // Type: + // object array; required + // Definition: + // Array of objects that specify the set of native assets and their permitted formats. + // Refer to Object: AssetFormat. + Asset []AssetFormat `json:"asset"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/native_image_asset_type.go b/adcom1/native_image_asset_type.go new file mode 100644 index 0000000..29e15f9 --- /dev/null +++ b/adcom1/native_image_asset_type.go @@ -0,0 +1,21 @@ +package adcom1 + +// NativeImageAssetType represents image asset types. +// This list is non-exhaustive and is intended to be expanded over time. +// Size recommendations are noted as "maximum height or width of at least", which means the publisher or supply platform should support a maximum height or width of at least this value and the buying platform knows that an image of this size should be accepted. +type NativeImageAssetType int + +// Common image asset types. +// +// Values 500+ hold vendor-specific codes. +const ( + // Icon: Icon image. Maximum height at least 50 device independent pixels (DIPS); aspect ratio 1:1. + ImageAssetIcon NativeImageAssetType = 1 + + // Main: Large image preview for the ad. At least one of 2 size variants required: + // + // Small: Maximum height at least 627 DIPS; maximum width at least 627, 836, or 1198 DIPS (i.e., aspect ratios of 1:1, 4:3, or 1.91:1, respectively). + // + // Large: Maximum height at least 200 DIPS; maximum width at least 200, 267, or 382 DIPS (i.e., aspect ratios of 1:1, 4:3, or 1.91:1, respectively). + ImageAssetMain NativeImageAssetType = 3 +) diff --git a/adcom1/operating_system.go b/adcom1/operating_system.go new file mode 100644 index 0000000..9a141fd --- /dev/null +++ b/adcom1/operating_system.go @@ -0,0 +1,39 @@ +package adcom1 + +// OperatingSystem represents device operating system. +type OperatingSystem int + +// Options for device operating system. +// +// Values of 500+ hold vendor-specific codes. +const ( + OSNotListed OperatingSystem = 0 // Other Not Listed + OS3DS OperatingSystem = 1 // 3DS System Software + OSAndroid OperatingSystem = 2 // Android + OSAppleTV OperatingSystem = 3 // Apple TV Software + OSAsha OperatingSystem = 4 // Asha + OSBada OperatingSystem = 5 // Bada + OSBlackBerry OperatingSystem = 6 // BlackBerry + OSBREW OperatingSystem = 7 // BREW + OSChromeOS OperatingSystem = 8 // ChromeOS + OSDarwin OperatingSystem = 9 // Darwin + OSFireOS OperatingSystem = 10 // FireOS + OSFirefoxOS OperatingSystem = 11 // FirefoxOS + OSHelenOS OperatingSystem = 12 // HelenOS + OSIOS OperatingSystem = 13 // iOS + OSLinux OperatingSystem = 14 // Linux + OSMacOS OperatingSystem = 15 // MacOS + OSMeeGo OperatingSystem = 16 // MeeGo + OSMorphOS OperatingSystem = 17 // MorphOS + OSNetBSD OperatingSystem = 18 // NetBSD + OSNucleusPLUS OperatingSystem = 19 // NucleusPLUS + OSPSVita OperatingSystem = 20 // PS Vita System Software + OSPS3 OperatingSystem = 21 // PS3 System Software + OSPS4 OperatingSystem = 22 // PS4 Software + OSPSP OperatingSystem = 23 // PSP System Software + OSSymbian OperatingSystem = 24 // Symbian + OSTizen OperatingSystem = 25 // Tizen + OSWatchOS OperatingSystem = 26 // WatchOS + OSWebOS OperatingSystem = 27 // WebOS + OSWindows OperatingSystem = 28 // Windows +) diff --git a/adcom1/placement.go b/adcom1/placement.go new file mode 100644 index 0000000..317b42f --- /dev/null +++ b/adcom1/placement.go @@ -0,0 +1,124 @@ +package adcom1 + +import "encoding/json" + +// Placement object represents the properties of a placement and the characteristics of ads permitted to be rendering within them. +// Placements of all types begin with this object as their root. +// It contains one or more subtype objects (i.e., display, video, audio) that define the kinds of media permitted as well as media specific placement behaviors. +// +// The other attributes in this object apply to all aspects and substructures of the placement (i.e., the same language, secure status, etc. apply to all media types and native assets as applicable). +type Placement struct { + // Attribute: + // tagid + // Type: + // string + // Definition: + // Identifier for specific ad placement or ad tag; unique within a distribution channel. + TagID string `json:"tagid,omitempty"` + + // Attribute: + // ssai + // Type: + // Integer; default 0 + // Definition: + // Indicates if server-side ad insertion (e.g., stitching an ad into an audio or video stream) is in use and the impact of this on asset and tracker retrieval, where 0 = status unknown, 1 = all client-side (i.e., not server-side), 2 = assets stitched server-side but tracking pixels fired client-side, 3 = all server-side. + SSAI int8 `json:"ssai,omitempty"` + + // Attribute: + // sdk + // Type: + // string + // Definition: + // Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video, audio, or mobile); used by some ad servers to customize ad code by partner. + SDK string `json:"sdk,omitempty"` + + // Attribute: + // sdkver + // Type: + // string + // Definition: + // Version of the SDK specified in the sdk attribute. + SDKVer string `json:"sdkver,omitempty"` + + // Attribute: + // reward + // Type: + // integer; default 0 + // Definition: + // Indicates if this is a rewarded placement, where 0 = no, 1 = yes. + Reward int8 `json:"reward,omitempty"` + + // Attribute: + // wlang + // Type: + // string array + // Definition: + // Whitelist of permitted languages of the creative using ISO-639-1-alpha-2. + // In practice, vendors using this object may elect an alternate standard (e.g., BCP-47) in which case this must be communicated a priori. + // Omission of this attribute indicates there are no restrictions. + WLang []string `json:"wlang,omitempty"` + + // Attribute: + // secure + // Type: + // integer + // Definition: + // Flag to indicate if the creative is secure (i.e., uses HTTPS for all assets and markup), where 0 = no, 1 = yes. + // There is no default and thus if omitted, the secure state is unknown. + // However, as a practical matter, the safe assumption is to treat unknown as non-secure. + Secure int8 `json:"secure,omitempty"` + + // Attribute: + // admx + // Type: + // integer + // Definition: + // Indicates if including markup is supported (i.e., the various adm attributes throughout the Placement structure), where 0 = no, 1 = yes. + AdMX int8 `json:"admx,omitempty"` + + // Attribute: + // curlx + // Type: + // integer + // Definition: + // Indicates if retrieving markup via URL reference is supported (i.e., the various curl attributes throughout the Placement structure), where 0 = no, 1 = yes. + CURLX int8 `json:"curlx,omitempty"` + + // Attribute: + // display + // Type: + // object; required * + // Definition: + // Placement Subtype Object that indicates that this may be a display placement and provides additional detail related thereto. + // Refer to Object: DisplayPlacement. + // * At least one placement subtype object is required. + Display *DisplayPlacement `json:"display,omitempty"` + + // Attribute: + // video + // Type: + // object; required * + // Definition: + // Placement Subtype Object that indicates that this may be a video placement and provides additional detail related thereto. + // Refer to Object: VideoPlacement. + // * At least one placement subtype object is required. + Video *VideoPlacement `json:"video,omitempty"` + + // Attribute: + // audio + // Type: + // object; required * + // Definition: + // Placement Subtype Object that indicates that this may be an audio placement and provides additional detail related thereto. + // Refer to Object: AudioPlacement. + // * At least one placement subtype object is required. + Audio *AudioPlacement `json:"audio,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/placement_position.go b/adcom1/placement_position.go new file mode 100644 index 0000000..5cc6fc0 --- /dev/null +++ b/adcom1/placement_position.go @@ -0,0 +1,16 @@ +package adcom1 + +// PlacementPosition represents placement positions as a relative measure of visibility or prominence. +// This table has values derived from the TAG Inventory Quality Guidelines (IQG). +type PlacementPosition int8 + +// Placement positions. +const ( + PositionAboveFold PlacementPosition = 1 // Above The Fold + PositionLocked PlacementPosition = 2 // Locked (i.e., fixed position) + PositionBelowFold PlacementPosition = 3 // Below The Fold + PositionHeader PlacementPosition = 4 // Header + PositionFooter PlacementPosition = 5 // Footer + PositionSideBar PlacementPosition = 6 // Sidebar + PositionFullScreen PlacementPosition = 7 // Fullscreen +) diff --git a/adcom1/playback_cessation_mode.go b/adcom1/playback_cessation_mode.go new file mode 100644 index 0000000..61ef999 --- /dev/null +++ b/adcom1/playback_cessation_mode.go @@ -0,0 +1,11 @@ +package adcom1 + +// PlaybackCessationMode represents modes for when media playback terminates. +type PlaybackCessationMode int8 + +// Modes for when media playback terminates. +const ( + PlaybackCompletion PlaybackCessationMode = 1 // On Video Completion or when Terminated by User + PlaybackLeavingViewport PlaybackCessationMode = 2 // On Leaving Viewport or when Terminated by User + PlaybackFloating PlaybackCessationMode = 3 // On Leaving Viewport Continues as a Floating/Slider Unit until Video Completion or when Terminated by User +) diff --git a/adcom1/playback_method.go b/adcom1/playback_method.go new file mode 100644 index 0000000..76f4928 --- /dev/null +++ b/adcom1/playback_method.go @@ -0,0 +1,14 @@ +package adcom1 + +// PlaybackMethod represents media playback methods. +type PlaybackMethod int8 + +// Media playback methods. +const ( + PlaybackPageLoadSoundOn PlaybackMethod = 1 // Initiates on Page Load with Sound On + PlaybackPageLoadSoundOff PlaybackMethod = 2 // Initiates on Page Load with Sound Off by Default + PlaybackClickSoundOn PlaybackMethod = 3 // Initiates on Click with Sound On + PlaybackMouseOverSoundOn PlaybackMethod = 4 // Initiates on Mouse-Over with Sound On + PlaybackViewportSoundOn PlaybackMethod = 5 // Initiates on Entering Viewport with Sound On + PlaybackViewportSoundOff PlaybackMethod = 6 // Initiates on Entering Viewport with Sound Off by Default +) diff --git a/adcom1/producer.go b/adcom1/producer.go new file mode 100644 index 0000000..c81d98f --- /dev/null +++ b/adcom1/producer.go @@ -0,0 +1,57 @@ +package adcom1 + +import "encoding/json" + +// Producer object defines the producer of the content in which ad will be displayed. +// This is particularly useful when the content is syndicated and may be distributed through different publishers and thus when the producer and publisher are not necessarily the same entity. +type Producer struct { + // Attribute: + // id + // Type: + // string, recommended + // Definition: + // Vendor-specific unique producer identifier. + // Useful if content is syndicated and may be posted on a site using embed tags. + ID string `json:"id,omitempty"` + + // Attribute: + // name + // Type: + // string + // Definition: + // Displayable name of the producer. + Name string `json:"name,omitempty"` + + // Attribute: + // domain + // Type: + // string + // Definition: + // Highest level domain of the producer (e.g., “producer.com”). + Domain string `json:"domain,omitempty"` + + // Attribute: + // cat + // Type: + // string array + // Definition: + // Array of content categories that describe the producer using IDs from the taxonomy indicated in cattax. + Cat []string `json:"cat,omitempty"` + + // Attribute: + // cattax + // Type: + // integer + // Definition: + // The taxonomy in use for the cat attribute. + // Refer to List: Category Taxonomies. + CatTax CategoryTaxonomy `json:"cattax,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/production_quality.go b/adcom1/production_quality.go new file mode 100644 index 0000000..4be250a --- /dev/null +++ b/adcom1/production_quality.go @@ -0,0 +1,12 @@ +package adcom1 + +// ProductionQuality represents content quality. +type ProductionQuality int8 + +// Options for content quality. +// These values are defined by the IAB; refer to www.iab.com/wp-content/uploads/2015/03/long-form-video-final.pdf for more information. +const ( + ProductionProfessional ProductionQuality = 1 // Professionally Produced + ProductionProsumer ProductionQuality = 2 // Prosumer + ProductionUser ProductionQuality = 3 // User Generated (UGC) +) diff --git a/adcom1/publisher.go b/adcom1/publisher.go new file mode 100644 index 0000000..baf7553 --- /dev/null +++ b/adcom1/publisher.go @@ -0,0 +1,55 @@ +package adcom1 + +import "encoding/json" + +// Publisher object describes the publisher of the media in which ads will be displayed. +type Publisher struct { + // Attribute: + // id + // Type: + // string, recommended + // Definition: + // Vendor-specific unique publisher identifier, as used in ads.txt files. + ID string `json:"id,omitempty"` + + // Attribute: + // name + // Type: + // string + // Definition: + // Displayable name of the publisher. + Name string `json:"name,omitempty"` + + // Attribute: + // domain + // Type: + // string + // Definition: + // Highest level domain of the publisher (e.g., “publisher.com”). + Domain string `json:"domain,omitempty"` + + // Attribute: + // cat + // Type: + // string array + // Definition: + // Array of content categories that describe the publisher using IDs from the taxonomy indicated in cattax. + Cat []string `json:"cat,omitempty"` + + // Attribute: + // cattax + // Type: + // integer + // Definition: + // The taxonomy in use for the cat attribute. + // Refer to List: Category Taxonomies. + CatTax CategoryTaxonomy `json:"cattax,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/regs.go b/adcom1/regs.go new file mode 100644 index 0000000..a48ff73 --- /dev/null +++ b/adcom1/regs.go @@ -0,0 +1,32 @@ +package adcom1 + +import "encoding/json" + +// Regs object contains any known legal, governmental, or industry regulations that are in effect. +type Regs struct { + // Attribute: + // coppa + // Type: + // integer + // Definition: + // Flag indicating if COPPA regulations apply, where 0 = no, 1 = yes. + // The Children's Online Privacy Protection Act (COPPA) was established by the U.S. Federal Trade Commission. + COPPA int8 `json:"coppa,omitempty"` + + // Attribute: + // gdpr + // Type: + // integer + // Definition: + // Flag indicating if GDPR regulations apply, where 0 = no, 1 = yes. + // The General Data Protection Regulation (GDPR) is a regulation of the European Union. + GDPR int8 `json:"gdpr,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/request_context.go b/adcom1/request_context.go new file mode 100644 index 0000000..fffa77d --- /dev/null +++ b/adcom1/request_context.go @@ -0,0 +1,17 @@ +package adcom1 + +// RequestContext represents a bunch of data for OpenRTB 3 Request.context field. +// Refer to OpenRTB 3.0 specification for details. +// +// For AdCOM v1.x, the objects allowed here all of which are optional are one of the DistributionChannel subtypes (i.e., Site, App, or Dooh), User, Device, Regs, Restrictions, and any objects subordinate to these as specified by AdCOM. +// +type RequestContext struct { + Site *Site `json:"site,omitempty"` + App *App `json:"app,omitempty"` + DOOH *DOOH `json:"dooh,omitempty"` + + User *User `json:"user,omitempty"` + Device *Device `json:"device,omitempty"` + Regs *Regs `json:"regs,omitempty"` + Restrictions *Restrictions `json:"restrictions,omitempty"` +} diff --git a/adcom1/restrictions.go b/adcom1/restrictions.go new file mode 100644 index 0000000..203465e --- /dev/null +++ b/adcom1/restrictions.go @@ -0,0 +1,57 @@ +package adcom1 + +import "encoding/json" + +// Restrictions object allows lists of restrictions on ad responses to be specified including specific content categories, advertisers, ads pertaining to specific apps, or creative attributes. +type Restrictions struct { + // Attribute: + // bcat + // Type: + // string array + // Definition: + // Block list of content categories using IDs from the taxonomy indicated in cattax. + BCat []string `json:"bcat,omitempty"` + + // Attribute: + // cattax + // Type: + // integer; default 2 + // Definition: + // The taxonomy in use for the bcat attribute + // Refer to List: Category Taxonomies. + CatTax CategoryTaxonomy `json:"cattax,omitempty"` + + // Attribute: + // badv + // Type: + // string array + // Definition: + // Block list of advertisers by their domains (e.g., “ford.com”). + BAdv []string `json:"badv,omitempty"` + + // Attribute: + // bapp + // Type: + // string array + // Definition: + // Block list of apps for which ads are disallowed + // These should be bundle or package names (e.g., “com.foo.mygame”) and should NOT be app store IDs (e.g., not iTunes store IDs). + BApp []string `json:"bapp,omitempty"` + + // Attribute: + // battr + // Type: + // integer array + // Definition: + // Block list of creative attributes + // Refer to List: Creative Attributes. + BAttr []CreativeAttribute `json:"battr,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/segment.go b/adcom1/segment.go new file mode 100644 index 0000000..3f13a00 --- /dev/null +++ b/adcom1/segment.go @@ -0,0 +1,40 @@ +package adcom1 + +import "encoding/json" + +// Segment objects are essentially key-value pairs that convey specific units of data. +// The parent Data object is a collection of such values from a given data provider. +// When in use, vendor-specific IDs should be communicated a priori among the parties. +type Segment struct { + // Attribute: + // id + // Type: + // string + // Definition: + // ID of the data segment specific to the data provider. + ID string `json:"id,omitempty"` + + // Attribute: + // name + // Type: + // string + // Definition: + // Displayable name of the data segment specific to the data provider. + Name string `json:"name,omitempty"` + + // Attribute: + // value + // Type: + // string + // Definition: + // String representation of the data segment value. + Value string `json:"value,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/site.go b/adcom1/site.go new file mode 100644 index 0000000..c690391 --- /dev/null +++ b/adcom1/site.go @@ -0,0 +1,114 @@ +package adcom1 + +import "encoding/json" + +// Site object is used to define an ad supported website, in contrast to a non-browser application, for example. +// As a derived class, a Site object inherits all DistributionChannel attributes and adds those defined below. +type Site struct { + DistributionChannel + + // Attribute: + // domain + // Type: + // string + // Definition: + // Domain of the site (e.g., “mysite.foo.com”). + Domain string `json:"domain,omitempty"` + + // Attribute: + // cat + // Type: + // string array + // Definition: + // Array of content categories describing the site using IDs from the taxonomy indicated in cattax. + Cat []string `json:"cat,omitempty"` + + // Attribute: + // sectcat + // Type: + // string array + // Definition: + // Array of content categories describing the current section of the site using IDs from the taxonomy indicated in cattax. + SectCat []string `json:"sectcat,omitempty"` + + // Attribute: + // pagecat + // Type: + // string array + // Definition: + // Array of content categories describing the current page or view of the site using IDs from the taxonomy indicated in cattax. + PageCat []string `json:"pagecat,omitempty"` + + // Attribute: + // cattax + // Type: + // integer + // Definition: + // The taxonomy in use for the cat, sectcat and pagecat attributes. + // Refer to List: Category Taxonomies. + CatTax CategoryTaxonomy `json:"cattax,omitempty"` + + // Attribute: + // privpolicy + // Type: + // integer + // Definition: + // Indicates if the site has a privacy policy, where 0 = no, 1 = yes. + PrivPolicy int8 `json:"privpolicy,omitempty"` + + // Attribute: + // keywords + // Type: + // string + // Definition: + // Comma separated list of keywords about the site. + Keywords string `json:"keywords,omitempty"` + + // Attribute: + // page + // Type: + // string + // Definition: + // URL of the page within the site. + Page string `json:"page,omitempty"` + + // Attribute: + // ref + // Type: + // string + // Definition: + // Referrer URL that caused navigation to the current page. + Ref string `json:"ref,omitempty"` + + // Attribute: + // search + // Type: + // string + // Definition: + // Search string that caused navigation to the current page. + Search string `json:"search,omitempty"` + + // Attribute: + // mobile + // Type: + // integer + // Definition: + // Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes. + Mobile int8 `json:"mobile,omitempty"` + + // Attribute: + // amp + // Type: + // integer + // Definition: + // Indicates if the page is built with AMP HTML, where 0 = no, 1 = yes. + AMP int8 `json:"amp,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/size_unit.go b/adcom1/size_unit.go new file mode 100644 index 0000000..524c849 --- /dev/null +++ b/adcom1/size_unit.go @@ -0,0 +1,11 @@ +package adcom1 + +// SizeUnit represents units of height and width used by creatives, assets, and placement specifications where noted. +type SizeUnit int8 + +// Units of height and width used by creatives, assets, and placement specifications where noted. +const ( + SizeDIP SizeUnit = 1 // Device Independent Pixels (DIPS) + SizeIn SizeUnit = 2 // Inches + SizeCm SizeUnit = 3 // Centimeters +) diff --git a/adcom1/start_delay_mode.go b/adcom1/start_delay_mode.go new file mode 100644 index 0000000..7287939 --- /dev/null +++ b/adcom1/start_delay_mode.go @@ -0,0 +1,12 @@ +package adcom1 + +// StartDelayMode represents video or audio start delay. +type StartDelayMode int64 + +// Options for the video or audio start delay. +// If the start delay value is greater than 0, then the position is mid-roll and the value indicates the start delay. +const ( + StartDelayPreRoll StartDelayMode = 0 // Pre-Roll + StartDelayGenericMidRoll StartDelayMode = -1 // Generic Mid-Roll + StartDelayGenericPostRoll StartDelayMode = -2 // Generic Post-Roll +) diff --git a/adcom1/testdata/item-specifications.json b/adcom1/testdata/item-specifications.json new file mode 100644 index 0000000..9d5e516 --- /dev/null +++ b/adcom1/testdata/item-specifications.json @@ -0,0 +1,30 @@ +{ + "placement": { + "tagid": "plc-ftr-123abc", + "secure": 1, + "display": { + "ctype": [ + 2, + 3 + ], + "displayfmt": [ + { + "w": 320, + "h": 50 + }, + { + "w": 320, + "h": 250 + } + ], + "event": [ + { + "type": 1, + "method": [ + 1 + ] + } + ] + } + } +} diff --git a/adcom1/testdata/media-response.json b/adcom1/testdata/media-response.json new file mode 100644 index 0000000..b66a5d4 --- /dev/null +++ b/adcom1/testdata/media-response.json @@ -0,0 +1,29 @@ +{ + "ad": { + "id": "d0bcb39723af87c2bb00942afee5710e", + "adomain": [ + "ford.com" + ], + "secure": 1, + "display": { + "mime": "image/jpeg", + "ctype": 3, + "w": 320, + "h": 50, + "banner": { + "img": "https://somebuyer.com/creative", + "link": { + "url": "https://somebuyer.com/click", + "urlfb": "https://somebuyer.com" + } + }, + "event": [ + { + "type": 1, + "method": 1, + "url": "https://somebuyer.com/pixel" + } + ] + } + } +} diff --git a/adcom1/testdata/request-context.json b/adcom1/testdata/request-context.json new file mode 100644 index 0000000..57e9e80 --- /dev/null +++ b/adcom1/testdata/request-context.json @@ -0,0 +1,51 @@ +{ + "regs": {}, + "restrictions": { + "bcat": [ + "IAB24", + "IAB25", + "IAB26" + ], + "cattax": 1, + "badv": [ + "ford.com", + "buick.com" + ] + }, + "site": { + "id": "1234", + "name": "Awesome Example Site", + "domain": "examplesitedomain.com", + "mobile": 1, + "pub": { + "id": "9876", + "name": "Example Publisher, Inc.", + "domain": "examplepubdomain.com" + } + }, + "user": { + "id": "a0af45c77890045deec100acb8443baff57c", + "buyeruid": "fcd4282456238256034abcdef220d9aa5892", + "yob": 1990, + "gender": "F" + }, + "device": { + "type": 4, + "ifa": "8846d6fa10008bceaaf322908dfcb221", + "ip": "1.2.3.4", + "ua": "...user agent string...", + "make": "Apple", + "model": "iPhone", + "hwv": "6s", + "os": 13, + "osv": "11.4.1", + "mccmnc": "310-005", + "geo": { + "type": 1, + "lat": 42.3601, + "lon": 71.0581, + "country": "USA", + "utcoffset": -300 + } + } +} diff --git a/adcom1/title_asset.go b/adcom1/title_asset.go new file mode 100644 index 0000000..cd51da7 --- /dev/null +++ b/adcom1/title_asset.go @@ -0,0 +1,30 @@ +package adcom1 + +import "encoding/json" + +// TitleAsset object identifies the native asset as a title asset, which is essentially just a plain text string with specified length. +type TitleAsset struct { + // Attribute: + // text + // Type: + // string; required + // Definition: + // The text content of the text element. + Text string `json:"text,omitempty"` + + // Attribute: + // len + // Type: + // integer + // Definition: + // The length of the contents of the text attribute. + Len int64 `json:"len,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/title_asset_format.go b/adcom1/title_asset_format.go new file mode 100644 index 0000000..29cce4a --- /dev/null +++ b/adcom1/title_asset_format.go @@ -0,0 +1,24 @@ +package adcom1 + +import "encoding/json" + +// TitleAssetFormat object is used to provide native asset format specifications for a title element. +// Title elements are simple strings. +type TitleAssetFormat struct { + // Attribute: + // len + // Type: + // integer; required + // Definition: + // The maximum allowed length of the title value. + // Recommended lengths are 25, 90, or 140. + Len int64 `json:"len,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/user.go b/adcom1/user.go new file mode 100644 index 0000000..a12b096 --- /dev/null +++ b/adcom1/user.go @@ -0,0 +1,85 @@ +package adcom1 + +import "encoding/json" + +// User object contains information known or derived about the human user of the device (i.e., the audience for advertising). +// The user ID is a vendor-specific artifact and may be subject to rotation or other privacy policies. +// However, this user ID must be stable long enough to serve reasonably as the basis for frequency capping and retargeting. +type User struct { + // Attribute: + // id + // Type: + // string; recommended + // Definition: + // Vendor-specific ID for the user. + // At least one of id or buyeruid is strongly recommended. + ID string `json:"id,omitempty"` + + // Attribute: + // buyeruid + // Type: + // string; recommended + // Definition: + // Buyer-specific ID for the user as mapped by an exchange for the buyer. + // At least one of id or buyeruid is strongly recommended. + BuyerUID string `json:"buyeruid,omitempty"` + + // Attribute: + // yob + // Type: + // integer + // Definition: + // Year of birth as a 4-digit integer. + YOB int64 `json:"yob,omitempty"` + + // Attribute: + // gender + // Type: + // string + // Definition: + // Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown). + Gender string `json:"gender,omitempty"` + + // Attribute: + // keywords + // Type: + // string + // Definition: + // Comma separated list of keywords, interests, or intent. + Keywords string `json:"keywords,omitempty"` + + // Attribute: + // consent + // Type: + // string + // Definition: + // GDPR consent string if applicable, complying with the comply with the IAB standard Consent String Format in the Transparency and Consent Framework technical specifications. + Consent string `json:"consent,omitempty"` + + // Attribute: + // geo + // Type: + // object + // Definition: + // Location of the user's home base (i.e., not necessarily their current location). + // Refer to Object: Geo. + Geo *Geo `json:"geo,omitempty"` + + // Attribute: + // data + // Type: + // object array + // Definition: + // Additional user data. + // Each Data object represents a different data source. + // Refer to Object: Data. + Data []Data `json:"data,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/video.go b/adcom1/video.go new file mode 100644 index 0000000..1f17dc2 --- /dev/null +++ b/adcom1/video.go @@ -0,0 +1,67 @@ +package adcom1 + +import "encoding/json" + +// Video object provides additional detail about an ad specifically for video ads. +type Video struct { + // Attribute: + // mime + // Type: + // string array + // Definition: + // Mime type(s) of the ad creative(s) (e.g., “video/mp4”). + MIME []string `json:"mime,omitempty"` + + // Attribute: + // api + // Type: + // integer array + // Definition: + // API required by the ad if applicable. + // Refer to List: API Frameworks. + API []APIFramework `json:"api,omitempty"` + + // Attribute: + // ctype + // Type: + // integer + // Definition: + // Subtype of video creative. + // Refer to List: Creative Subtypes - Audio/Video. + CType CreativeSubtypeAV `json:"ctype,omitempty"` + + // Attribute: + // dur + // Type: + // integer + // Definition: + // Duration of the video creative in seconds. + Dur int64 `json:"dur,omitempty"` + + // Attribute: + // adm + // Type: + // string + // Definition: + // Video markup (e.g., VAST). + // Note that including both adm and curl is not recommended. + AdM string `json:"adm,omitempty"` + + // Attribute: + // curl + // Type: + // string + // Definition: + // Optional means of retrieving markup by reference; a URL that returns video markup (e.g., VAST). + // If this ad is matched to a Placement specification, the Placement.curlx attribute indicates if this markup retrieval option is supported. + // Note that including both adm and curl is not recommended. + CURL string `json:"curl,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/video_asset.go b/adcom1/video_asset.go new file mode 100644 index 0000000..f912800 --- /dev/null +++ b/adcom1/video_asset.go @@ -0,0 +1,36 @@ +package adcom1 + +import "encoding/json" + +// VideoAsset object identifies the native asset as a video asset. +// Video markup (e.g., VAST) must be either included or referenced. +type VideoAsset struct { + // Attribute: + // adm + // Type: + // string; required * + // Definition: + // Video markup (e.g., VAST document) for the asset. + // * Exactly one of adm and curl is required. + // Including both is not recommended. + AdM string `json:"adm,omitempty"` + + // Attribute: + // curl + // Type: + // string; required * + // Definition: + // A URL that returns the video markup (e.g., VAST document) for the asset. + // If this ad is matched to a placement specification, the Placement.curlx attribute indicates if this markup retrieval option is supported. + // * Exactly one of adm and curl is required. + // Including both is not recommended. + CURL string `json:"curl,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/video_placement.go b/adcom1/video_placement.go new file mode 100644 index 0000000..c89fa53 --- /dev/null +++ b/adcom1/video_placement.go @@ -0,0 +1,242 @@ +package adcom1 + +import "encoding/json" + +// VideoPlacement object signals that the placement may be a video placement and provides additional detail about permitted video ads (e.g., VAST). +type VideoPlacement struct { + // Attribute: + // ptype + // Type: + // integer + // Definition: + // Placement subtype. + // Refer to List: Placement Subtypes - Video. + PType VideoPlacementSubtype `json:"ptype,omitempty"` + + // Attribute: + // pos + // Type: + // integer + // Definition: + // Placement position on screen. + // Refer to List: Placement Positions. + Pos PlacementPosition `json:"pos,omitempty"` + + // Attribute: + // delay + // Type: + // integer + // Definition: + // Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll placements. + // For additional generic values, refer to List: Start Delay Modes. + Delay int64 `json:"delay,omitempty"` + + // Attribute: + // skip + // Type: + // integer + // Definition: + // Indicates if the placement imposes ad skippability, where 0 = no, 1 = yes. + Skip int8 `json:"skip,omitempty"` + + // Attribute: + // skipmin + // Type: + // integer; default 0 + // Definition: + // The placement allows creatives of total duration greater than this number of seconds to be skipped; only applicable if the ad is skippable. + SkipMin int64 `json:"skipmin,omitempty"` + + // Attribute: + // skipafter + // Type: + // integer; default 0 + // Definition: + // Number of seconds a creative must play before the placement enables skipping; only applicable if the ad is skippable. + SkipAfter int64 `json:"skipafter,omitempty"` + + // Attribute: + // playmethod + // Type: + // integer + // Definition: + // Playback method in use for this placement. + // Refer to List: Playback Methods. + PlayMethod PlaybackMethod `json:"playmethod,omitempty"` + + // Attribute: + // playend + // Type: + // integer + // Definition: + // The event that causes playback to end for this placement. + // Refer to List: Playback Cessation Modes. + PlayEnd PlaybackCessationMode `json:"playend,omitempty"` + + // Attribute: + // clktype + // Type: + // integer + // Definition: + // Indicates the click type of the placement. + // Refer to List: Click Types. + ClkType ClickType `json:"clktype,omitempty"` + + // Attribute: + // mime + // Type: + // string array; required + // Definition: + // Array of supported mime types (e.g., “video/mp4”). + // If omitted, all types are assumed. + MIME []string `json:"mime,omitempty"` + + // Attribute: + // api + // Type: + // integer array + // Definition: + // List of supported APIs for this placement. + // If an API is not explicitly listed, it is assumed to be unsupported. + // Refer to List: API Frameworks. + API []APIFramework `json:"api,omitempty"` + + // Attribute: + // ctype + // Type: + // integer array + // Definition: + // Creative subtypes permitted for this placement. + // Refer to List: Creative Subtypes - Audio/Video. + CType []CreativeSubtypeAV `json:"ctype,omitempty"` + + // Attribute: + // w + // Type: + // integer + // Definition: + // Width of the placement in units specified by unit. + W int64 `json:"w,omitempty"` + + // Attribute: + // h + // Type: + // integer + // Definition: + // Height of the placement in units specified by unit. + H int64 `json:"h,omitempty"` + + // Attribute: + // unit + // Type: + // integer; default 1 + // Definition: + // Units of size used for w and h attributes. + // Refer to List: Size Units. + Unit SizeUnit `json:"unit,omitempty"` + + // Attribute: + // mindur + // Type: + // integer + // Definition: + // Minimum creative duration in seconds. + MinDur int64 `json:"mindur,omitempty"` + + // Attribute: + // maxdur + // Type: + // integer + // Definition: + // Maximum creative duration in seconds. + MaxDur int64 `json:"maxdur,omitempty"` + + // Attribute: + // maxext + // Type: + // integer; default 0 + // Definition: + // Maximum extended creative duration if extension is allowed. + // If 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 maxdur value. + MaxExt int64 `json:"maxext,omitempty"` + + // Attribute: + // minbitr + // Type: + // integer + // Definition: + // Minimum bit rate of the creative in Kbps. + MinBitR int64 `json:"minbitr,omitempty"` + + // Attribute: + // maxbitr + // Type: + // integer + // Definition: + // Maximum bit rate of the creative in Kbps. + MaxBitR int64 `json:"maxbitr,omitempty"` + + // Attribute: + // delivery + // Type: + // integer array + // Definition: + // Array of supported creative delivery methods. + // If omitted, all can be assumed. + // Refer to List: Delivery Methods. + Delivery []DeliveryMethod `json:"delivery,omitempty"` + + // Attribute: + // maxseq + // Type: + // integer + // Definition: + // The maximum number of ads that can be played in an ad pod. + MaxSeq int64 `json:"maxseq,omitempty"` + + // Attribute: + // linear + // Type: + // integer + // Definition: + // Indicates if the creative must be linear, nonlinear, etc. + // If none specified, no restrictions are assumed. + // Refer to List: Linearity Modes. + Linear LinearityMode `json:"linear,omitempty"` + + // Attribute: + // boxing + // Type: + // integer; default 1 + // Definition: + // Indicates if letterboxing of 4:3 creatives into a 16:9 window is allowed, where 0 = no, 1 = yes. + Boxing int8 `json:"boxing,omitempty"` + + // Attribute: + // comp + // Type: + // object array + // Definition: + // Array of objects indicating that companion ads are available and providing the specifications thereof. + // Refer to Object: Companion. + Comp []Companion `json:"comp,omitempty"` + + // Attribute: + // comptype + // Type: + // integer array + // Definition: + // Supported companion ad types; recommended if companion ads are specified in comp. + // Refer to List: Companion Types. + CompType []CompanionType `json:"comptype,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional vendor-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/adcom1/video_placement_subtype.go b/adcom1/video_placement_subtype.go new file mode 100644 index 0000000..5889675 --- /dev/null +++ b/adcom1/video_placement_subtype.go @@ -0,0 +1,13 @@ +package adcom1 + +// VideoPlacementSubtype represents types of video placements derived largely from the IAB Digital Video Guidelines. +type VideoPlacementSubtype int8 + +// Types of video placements derived largely from the IAB Digital Video Guidelines. +const ( + VideoInStream VideoPlacementSubtype = 1 // In-Stream: Played before, during or after the streaming video content that the consumer has requested (e.g., Pre-roll, Mid-roll, Post-roll). + VideoInBanner VideoPlacementSubtype = 2 // In-Banner: Exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on the page for its delivery. + VideoInArticle VideoPlacementSubtype = 3 // In-Article: Loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message. + VideoInFeed VideoPlacementSubtype = 4 // In-Feed: Found in content, social, or product feeds. + VideoAlwaysVisible VideoPlacementSubtype = 5 // Interstitial/Slider/Floating: Covers the entire or a portion of screen area, but is always on screen while displayed (i.e. cannot be scrolled out of view). +) diff --git a/adcom1/volume_normalization_mode.go b/adcom1/volume_normalization_mode.go new file mode 100644 index 0000000..e3235cc --- /dev/null +++ b/adcom1/volume_normalization_mode.go @@ -0,0 +1,13 @@ +package adcom1 + +// VolumeNormalizationMode represents types of volume normalization modes, typically for audio. +type VolumeNormalizationMode int8 + +// Types of volume normalization modes, typically for audio. +const ( + VolumeNormNone VolumeNormalizationMode = 0 // None + VolumeNormAvg VolumeNormalizationMode = 1 // Ad Volume Average Normalized to Content + VolumeNormPeak VolumeNormalizationMode = 2 // Ad Volume Peak Normalized to Content + VolumeNormLoudness VolumeNormalizationMode = 3 // Ad Loudness Normalized to Content + VolumeNormCustom VolumeNormalizationMode = 4 // Custom Volume Normalization +) diff --git a/native/README.md b/native/README.md deleted file mode 100644 index c107b4c..0000000 --- a/native/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# native [![GoDoc](https://godoc.org/github.com/mxmCherry/openrtb/native?status.svg)](https://godoc.org/github.com/mxmCherry/openrtb/native) - -[Go](https://golang.org/) implementation of [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API -Specification Version 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) types/enums. diff --git a/native/request/README.md b/native/request/README.md deleted file mode 100644 index 1fb7916..0000000 --- a/native/request/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# native/request [![GoDoc](https://godoc.org/github.com/mxmCherry/openrtb/native/request?status.svg)](https://godoc.org/github.com/mxmCherry/openrtb/native/request) - -[Go](https://golang.org/) implementation of [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API -Specification Version 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) section 4 Native Ad Request Markup Details types. diff --git a/native/request/testdata/v1.1/README.md b/native/request/testdata/v1.1/README.md deleted file mode 100644 index 8809268..0000000 --- a/native/request/testdata/v1.1/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# v1.1 - -JSON examples copied from [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API -Specification Version 1.1](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf) spec - section 6 Bid Request/Response Samples. - -Some empty/zero attributes were omited (not copied) because of [encoding/json](https://golang.org/pkg/encoding/json/) `omitempty` and [gomega.MatchJSON(...)](http://onsi.github.io/gomega/#matchjsonjson-interface). diff --git a/native/response/README.md b/native/response/README.md deleted file mode 100644 index 746ef15..0000000 --- a/native/response/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# native/response [![GoDoc](https://godoc.org/github.com/mxmCherry/openrtb/native/response?status.svg)](https://godoc.org/github.com/mxmCherry/openrtb/native/response) - -[Go](https://golang.org/) implementation of [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API -Specification Version 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) section 5 Native Ad Response Markup Details types. diff --git a/native/response/testdata/v1.1/README.md b/native/response/testdata/v1.1/README.md deleted file mode 100644 index 20c5d0b..0000000 --- a/native/response/testdata/v1.1/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# testdata - -JSON examples copied from [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API -Specification Version 1.1](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf) spec - section 6 Bid Request/Response Samples. - -Some empty/zero attributes were omited (not copied) because of [encoding/json](https://golang.org/pkg/encoding/json/) `omitempty` and [gomega.MatchJSON(...)](http://onsi.github.io/gomega/#matchjsonjson-interface). diff --git a/native/response/testdata/v1.2/README.md b/native/response/testdata/v1.2/README.md deleted file mode 100644 index 6306c77..0000000 --- a/native/response/testdata/v1.2/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# v1.2 - -JSON examples copied from [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API -Specification Version 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) spec - section 6 Bid Request/Response Samples. - -Some empty/zero attributes were omited (not copied) because of [encoding/json](https://golang.org/pkg/encoding/json/) `omitempty` and [gomega.MatchJSON(...)](http://onsi.github.io/gomega/#matchjsonjson-interface). diff --git a/native1/README.md b/native1/README.md new file mode 100644 index 0000000..991ab35 --- /dev/null +++ b/native1/README.md @@ -0,0 +1,5 @@ +# native1 [![GoDoc](https://godoc.org/github.com/mxmCherry/openrtb/native1?status.svg)](https://godoc.org/github.com/mxmCherry/openrtb/native1) + +[OpenRTB Dynamic Native Ads API](https://iabtechlab.com/standards/openrtb-native/) [1.2](https://iabtechlab.com/wp-content/uploads/2016/07/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) section "7 Reference Lists/Enumerations" types for [Go programming language](https://golang.org/) + +See [request](request/) for section "4 Native Ad Request Markup Details" and [response](response/) for section "5 Native Ad Response Markup Details". diff --git a/native/ad_unit.go b/native1/ad_unit.go similarity index 98% rename from native/ad_unit.go rename to native1/ad_unit.go index a3a758a..53ea841 100644 --- a/native/ad_unit.go +++ b/native1/ad_unit.go @@ -1,4 +1,4 @@ -package native +package native1 // 7.2 Native Ad Unit IDs in version 1.1. // Deprecated/removed in version 1.2. diff --git a/native/context_sub_type.go b/native1/context_sub_type.go similarity index 99% rename from native/context_sub_type.go rename to native1/context_sub_type.go index f57d0bf..63a9bb2 100644 --- a/native/context_sub_type.go +++ b/native1/context_sub_type.go @@ -1,4 +1,4 @@ -package native +package native1 // 7.2 Context Sub Type IDs // diff --git a/native/context_type.go b/native1/context_type.go similarity index 98% rename from native/context_type.go rename to native1/context_type.go index 5942576..ea89d0a 100644 --- a/native/context_type.go +++ b/native1/context_type.go @@ -1,4 +1,4 @@ -package native +package native1 // 7.1 Context Type IDs // diff --git a/native/data_asset_type.go b/native1/data_asset_type.go similarity index 99% rename from native/data_asset_type.go rename to native1/data_asset_type.go index a8c3b74..9f9a431 100644 --- a/native/data_asset_type.go +++ b/native1/data_asset_type.go @@ -1,4 +1,4 @@ -package native +package native1 // 7.4 Data Asset Types // diff --git a/native/event_tracking_method.go b/native1/event_tracking_method.go similarity index 97% rename from native/event_tracking_method.go rename to native1/event_tracking_method.go index 3be3b60..07d82f3 100644 --- a/native/event_tracking_method.go +++ b/native1/event_tracking_method.go @@ -1,4 +1,4 @@ -package native +package native1 // 7.7 Event Tracking Methods Table type EventTrackingMethod int8 diff --git a/native/event_type.go b/native1/event_type.go similarity index 96% rename from native/event_type.go rename to native1/event_type.go index 2f8ebdb..abd05a9 100644 --- a/native/event_type.go +++ b/native1/event_type.go @@ -1,4 +1,4 @@ -package native +package native1 // 7.6 Event Types Table type EventType int8 diff --git a/native/image_asset_type.go b/native1/image_asset_type.go similarity index 99% rename from native/image_asset_type.go rename to native1/image_asset_type.go index 2784198..2498b22 100644 --- a/native/image_asset_type.go +++ b/native1/image_asset_type.go @@ -1,4 +1,4 @@ -package native +package native1 // 7.5 Image Asset Types // diff --git a/native/layout.go b/native1/layout.go similarity index 97% rename from native/layout.go rename to native1/layout.go index 0c81308..04689da 100644 --- a/native/layout.go +++ b/native1/layout.go @@ -1,4 +1,4 @@ -package native +package native1 // 7.1 Native Layout IDs in version 1.1. // Deprecated/removed in version 1.2. diff --git a/native/native.go b/native1/native1.go similarity index 68% rename from native/native.go rename to native1/native1.go index 702e996..dd92b50 100644 --- a/native/native.go +++ b/native1/native1.go @@ -1,5 +1,5 @@ -// Package native provides OpenRTB Dynamic Native Ads API Specification Version 1.2 +// Package native1 provides OpenRTB Dynamic Native Ads API Specification Version 1.2 // section 7 Reference Lists/Enumerations types/constants: // https://www.iab.com/guidelines/real-time-bidding-rtb-project/ // https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf -package native +package native1 diff --git a/native/placement_type.go b/native1/placement_type.go similarity index 97% rename from native/placement_type.go rename to native1/placement_type.go index cb65f4e..b88560b 100644 --- a/native/placement_type.go +++ b/native1/placement_type.go @@ -1,4 +1,4 @@ -package native +package native1 // 7.3 Placement Type IDs // diff --git a/native/protocol.go b/native1/protocol.go similarity index 98% rename from native/protocol.go rename to native1/protocol.go index adfd902..23ab7ba 100644 --- a/native/protocol.go +++ b/native1/protocol.go @@ -1,4 +1,4 @@ -package native +package native1 // 5.8 Protocols (from OpenRTB spec 2.5) // diff --git a/native1/request/README.md b/native1/request/README.md new file mode 100644 index 0000000..2d663eb --- /dev/null +++ b/native1/request/README.md @@ -0,0 +1,3 @@ +# native1/request [![GoDoc](https://godoc.org/github.com/mxmCherry/openrtb/native1/request?status.svg)](https://godoc.org/github.com/mxmCherry/openrtb/native1/request) + +[OpenRTB Dynamic Native Ads API](https://iabtechlab.com/standards/openrtb-native/) [1.2](https://iabtechlab.com/wp-content/uploads/2016/07/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) section "4 Native Ad Request Markup Details" types for [Go programming language](https://golang.org/) diff --git a/native/request/asset.go b/native1/request/asset.go similarity index 94% rename from native/request/asset.go rename to native1/request/asset.go index 6cd78db..73d8e54 100644 --- a/native/request/asset.go +++ b/native1/request/asset.go @@ -14,11 +14,11 @@ import "encoding/json" // 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 native by DSPs by limiting the diverse types/sizes/requirements of assets they must have available to purchase a native ad impression. +// 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 native inventory. +// DSPs should feel confident that if they support these standards they'll be able to access most native1 inventory. type Asset struct { // Field: // id diff --git a/native/request/data.go b/native1/request/data.go similarity index 77% rename from native/request/data.go rename to native1/request/data.go index 1f9d31e..a7d4cbd 100644 --- a/native/request/data.go +++ b/native1/request/data.go @@ -3,13 +3,13 @@ package request import ( "encoding/json" - "github.com/mxmCherry/openrtb/native" + "github.com/mxmCherry/openrtb/native1" ) // 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. +// 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 Data struct { @@ -23,7 +23,7 @@ type Data struct { // 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 native.DataAssetType `json:"type"` + Type native1.DataAssetType `json:"type"` // Field: // len diff --git a/native/request/event_tracker.go b/native1/request/event_tracker.go similarity index 88% rename from native/request/event_tracker.go rename to native1/request/event_tracker.go index 1e59c1e..13e8060 100644 --- a/native/request/event_tracker.go +++ b/native1/request/event_tracker.go @@ -3,7 +3,7 @@ package request import ( "encoding/json" - "github.com/mxmCherry/openrtb/native" + "github.com/mxmCherry/openrtb/native1" ) // 4.7 Event Trackers Request Object @@ -20,7 +20,7 @@ type EventTracker struct { // Description: // Type of event available for tracking. // See Event Types table. - Event native.EventType `json:"event"` + Event native1.EventType `json:"event"` // Field: // methods @@ -31,7 +31,7 @@ type EventTracker struct { // Description: // Array of the types of tracking available for the given event. // See Event Tracking Methods table - Methods []native.EventTrackingMethod `json:"methods"` + Methods []native1.EventTrackingMethod `json:"methods"` // Field: // ext diff --git a/native/request/image.go b/native1/request/image.go similarity index 91% rename from native/request/image.go rename to native1/request/image.go index 17d6c13..a1c29eb 100644 --- a/native/request/image.go +++ b/native1/request/image.go @@ -3,7 +3,7 @@ package request import ( "encoding/json" - "github.com/mxmCherry/openrtb/native" + "github.com/mxmCherry/openrtb/native1" ) // 4.4 Image Object @@ -22,7 +22,7 @@ type Image struct { // 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 native.ImageAssetType `json:"type,omitempty"` + Type native1.ImageAssetType `json:"type,omitempty"` // Field: // w @@ -32,7 +32,7 @@ type Image struct { // integer // Description: // Width of the image in pixels. - W uint64 `json:"w,omitempty"` + W int64 `json:"w,omitempty"` // Field: // wmin @@ -45,7 +45,7 @@ type Image struct { // 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"` + WMin int64 `json:"wmin,omitempty"` // Field: // h @@ -55,7 +55,7 @@ type Image struct { // integer // Description: // Height of the image in pixels. - H uint64 `json:"h,omitempty"` + H int64 `json:"h,omitempty"` // Field: // hmin @@ -68,7 +68,7 @@ type Image struct { // 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"` + HMin int64 `json:"hmin,omitempty"` // Field: // mimes diff --git a/native/request/request.go b/native1/request/request.go similarity index 82% rename from native/request/request.go rename to native1/request/request.go index 1b68f4c..067cfd3 100644 --- a/native/request/request.go +++ b/native1/request/request.go @@ -7,17 +7,17 @@ package request import ( "encoding/json" - "github.com/mxmCherry/openrtb/native" + "github.com/mxmCherry/openrtb/native1" ) // 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. +// 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 native request to have a root node with a single field “native” that would contain the object above as its value. +// 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 Request struct { @@ -40,9 +40,9 @@ type Request struct { // Type: // integer // Description: - // The Layout ID of the native ad unit. + // The Layout ID of the native1 ad unit. // See the Table of Layout IDs below. - Layout native.Layout `json:"layout,omitempty"` + Layout native1.Layout `json:"layout,omitempty"` // Field: // adunit @@ -51,9 +51,9 @@ type Request struct { // Type: // integer // Description: - // The Ad unit ID of the native ad unit. + // 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 native.AdUnit `json:"adunit,omitempty"` + AdUnit native1.AdUnit `json:"adunit,omitempty"` // Field: // context @@ -64,7 +64,7 @@ type Request struct { // Description: // The context in which the ad appears. // See Table of Context IDs below for a list of supported context types. - Context native.ContextType `json:"context,omitempty"` + Context native1.ContextType `json:"context,omitempty"` // Field: // contextsubtype @@ -75,7 +75,7 @@ type Request struct { // 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 native.ContextSubType `json:"contextsubtype,omitempty"` + ContextSubType native1.ContextSubType `json:"contextsubtype,omitempty"` // Field: // plcmttype @@ -86,7 +86,7 @@ type Request struct { // 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 native.PlacementType `json:"plcmttype,omitempty"` + PlcmtType native1.PlacementType `json:"plcmttype,omitempty"` // Field: // plcmtcnt @@ -171,8 +171,8 @@ type Request struct { // Default: // 0 // Description: - // Set to 1 when the native ad supports buyer-specific privacy notice. - // Set to 0 (or field absent) when the native ad doesn’t support custom privacy links or if support is unknown. + // 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: diff --git a/native/request/request_suite_test.go b/native1/request/request_suite_test.go similarity index 100% rename from native/request/request_suite_test.go rename to native1/request/request_suite_test.go diff --git a/native/request/request_test.go b/native1/request/request_test.go similarity index 95% rename from native/request/request_test.go rename to native1/request/request_test.go index 6ae8f48..8cb1673 100644 --- a/native/request/request_test.go +++ b/native1/request/request_test.go @@ -5,7 +5,7 @@ import ( "io/ioutil" "path/filepath" - . "github.com/mxmCherry/openrtb/native/request" + . "github.com/mxmCherry/openrtb/native1/request" . "github.com/onsi/ginkgo" . "github.com/onsi/ginkgo/extensions/table" diff --git a/native1/request/testdata/v1.1/README.md b/native1/request/testdata/v1.1/README.md new file mode 100644 index 0000000..3e0d9da --- /dev/null +++ b/native1/request/testdata/v1.1/README.md @@ -0,0 +1,5 @@ +# native1/request/testdata/v1.1 + +JSON examples copied from [OpenRTB Dynamic Native Ads API](https://iabtechlab.com/standards/openrtb-native/) [1.1](https://iabtechlab.com/wp-content/uploads/2016/04/OpenRTB-Native-Ads-Specification-2016.pdf) section "6 Bid Request/Response Samples". + +Some empty/zero attributes were omited (not copied) because of [encoding/json](https://golang.org/pkg/encoding/json/) `omitempty` and [gomega.MatchJSON(...)](http://onsi.github.io/gomega/#matchjsonjson-interface). diff --git a/native/request/testdata/v1.1/content-context.json b/native1/request/testdata/v1.1/content-context.json similarity index 100% rename from native/request/testdata/v1.1/content-context.json rename to native1/request/testdata/v1.1/content-context.json diff --git a/native/request/testdata/v1.1/social-context.json b/native1/request/testdata/v1.1/social-context.json similarity index 100% rename from native/request/testdata/v1.1/social-context.json rename to native1/request/testdata/v1.1/social-context.json diff --git a/native/request/testdata/v1.2/README.md b/native1/request/testdata/v1.2/README.md similarity index 59% rename from native/request/testdata/v1.2/README.md rename to native1/request/testdata/v1.2/README.md index da10a8d..73743f0 100644 --- a/native/request/testdata/v1.2/README.md +++ b/native1/request/testdata/v1.2/README.md @@ -1,7 +1,6 @@ -# v1.2 +# native1/request/testdata/v1.2 -JSON examples copied from [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [Dynamic Native Ads API -Specification Version 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) spec - section 6 Bid Request/Response Samples. +JSON examples copied from [OpenRTB Dynamic Native Ads API](https://iabtechlab.com/standards/openrtb-native/) [1.2](https://iabtechlab.com/wp-content/uploads/2016/07/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) section "6 Bid Request/Response Samples". Some empty/zero attributes were omited (not copied) because of [encoding/json](https://golang.org/pkg/encoding/json/) `omitempty` and [gomega.MatchJSON(...)](http://onsi.github.io/gomega/#matchjsonjson-interface). diff --git a/native/request/testdata/v1.2/content-context.json b/native1/request/testdata/v1.2/content-context.json similarity index 100% rename from native/request/testdata/v1.2/content-context.json rename to native1/request/testdata/v1.2/content-context.json diff --git a/native/request/testdata/v1.2/social-context.json b/native1/request/testdata/v1.2/social-context.json similarity index 100% rename from native/request/testdata/v1.2/social-context.json rename to native1/request/testdata/v1.2/social-context.json diff --git a/native/request/testdata/v1.2/third-party.json b/native1/request/testdata/v1.2/third-party.json similarity index 100% rename from native/request/testdata/v1.2/third-party.json rename to native1/request/testdata/v1.2/third-party.json diff --git a/native/request/title.go b/native1/request/title.go similarity index 100% rename from native/request/title.go rename to native1/request/title.go diff --git a/native/request/video.go b/native1/request/video.go similarity index 91% rename from native/request/video.go rename to native1/request/video.go index bf4d9a6..7c36bb5 100644 --- a/native/request/video.go +++ b/native1/request/video.go @@ -3,7 +3,7 @@ package request import ( "encoding/json" - "github.com/mxmCherry/openrtb/native" + "github.com/mxmCherry/openrtb/native1" ) // 4.5 Video Object @@ -23,7 +23,7 @@ type Video struct { // 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. + // Note that native1 frequently does not support flash. MIMEs []string `json:"mimes"` // Field: @@ -55,7 +55,7 @@ type Video struct { // 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 []native.Protocol `json:"protocols"` + Protocols []native1.Protocol `json:"protocols"` // Field: // ext diff --git a/native1/response/README.md b/native1/response/README.md new file mode 100644 index 0000000..803f8db --- /dev/null +++ b/native1/response/README.md @@ -0,0 +1,3 @@ +# native1/response [![GoDoc](https://godoc.org/github.com/mxmCherry/openrtb/native1/response?status.svg)](https://godoc.org/github.com/mxmCherry/openrtb/native1/response) + +[OpenRTB Dynamic Native Ads API](https://iabtechlab.com/standards/openrtb-native/) [1.2](https://iabtechlab.com/wp-content/uploads/2016/07/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) section "5 Native Ad Response Markup Details" types for [Go programming language](https://golang.org/) diff --git a/native/response/asset.go b/native1/response/asset.go similarity index 100% rename from native/response/asset.go rename to native1/response/asset.go diff --git a/native/response/data.go b/native1/response/data.go similarity index 84% rename from native/response/data.go rename to native1/response/data.go index bf92bb5..d033e6f 100644 --- a/native/response/data.go +++ b/native1/response/data.go @@ -3,14 +3,14 @@ package response import ( "encoding/json" - "github.com/mxmCherry/openrtb/native" + "github.com/mxmCherry/openrtb/native1" ) // 5.5 Object: Data // // Corresponds to the Data Object in the request, with the value filled in. -// The Data Object is to be used for all miscellaneous elements of the native unit such as Brand Name, Ratings, Review Count, Stars, Downloads, Price count etc. -// It is also generic for future native elements not contemplated at the time of the writing of this document. +// The Data Object is to be used for all miscellaneous elements of the native1 unit such as Brand Name, Ratings, Review Count, Stars, Downloads, Price count etc. +// It is also generic for future native1 elements not contemplated at the time of the writing of this document. type Data struct { // Field: // type @@ -21,7 +21,7 @@ type Data struct { // Description: // Required for assetsurl/dcourl responses, not required for embedded asset responses. // The type of data element being submitted from the Data Asset Types table. - Type native.DataAssetType `json:"type,omitempty"` + Type native1.DataAssetType `json:"type,omitempty"` // Field: // len diff --git a/native/response/event_tracker.go b/native1/response/event_tracker.go similarity index 93% rename from native/response/event_tracker.go rename to native1/response/event_tracker.go index 53d0542..e907654 100644 --- a/native/response/event_tracker.go +++ b/native1/response/event_tracker.go @@ -3,7 +3,7 @@ package response import ( "encoding/json" - "github.com/mxmCherry/openrtb/native" + "github.com/mxmCherry/openrtb/native1" ) // 5.8 Event Tracker Response Object @@ -21,7 +21,7 @@ type EventTracker struct { // Description: // Type of event to track. // See Event Types table. - Event native.EventType `json:"event"` + Event native1.EventType `json:"event"` // Field: // method @@ -32,7 +32,7 @@ type EventTracker struct { // Description: // Type of tracking requested // See Event Tracking Methods table. - Method native.EventTrackingMethod `json:"method"` + Method native1.EventTrackingMethod `json:"method"` // Field: // url diff --git a/native/response/image.go b/native1/response/image.go similarity index 91% rename from native/response/image.go rename to native1/response/image.go index bd96ce2..0629515 100644 --- a/native/response/image.go +++ b/native1/response/image.go @@ -3,7 +3,7 @@ package response import ( "encoding/json" - "github.com/mxmCherry/openrtb/native" + "github.com/mxmCherry/openrtb/native1" ) // 5.4 Object: Image @@ -22,7 +22,7 @@ type Image struct { // Description: // Required for assetsurl or dcourl responses, not required for embedded asset responses. // The type of image element being submitted from the Image Asset Types table. - Type native.ImageAssetType `json:"type,omitempty"` + Type native1.ImageAssetType `json:"type,omitempty"` // Field: // url @@ -44,7 +44,7 @@ type Image struct { // Width of the image in pixels. // Recommended for embedded asset responses. // Required for assetsurl/dcourlresponses if multiple assets of same type submitted. - W uint64 `json:"w,omitempty"` + W int64 `json:"w,omitempty"` // Field: // h @@ -56,7 +56,7 @@ type Image struct { // Height of the image in pixels. // Recommended for embedded asset responses. // Required for assetsurl/dcourl responses if multiple assets of same type submitted. - H uint64 `json:"h,omitempty"` + H int64 `json:"h,omitempty"` // Field: // ext diff --git a/native/response/link.go b/native1/response/link.go similarity index 100% rename from native/response/link.go rename to native1/response/link.go diff --git a/native/response/response.go b/native1/response/response.go similarity index 92% rename from native/response/response.go rename to native1/response/response.go index 69cb927..898cd75 100644 --- a/native/response/response.go +++ b/native1/response/response.go @@ -8,8 +8,8 @@ import "encoding/json" // 5.1 Object: Response // -// The native object is the top level JSON object which identifies a native response. -// Note: Prior to VERSION 1.1, the native response’s root node was an object with a single field “native” that would contain the object above as its value. +// The native1 object is the top level JSON object which identifies a native response. +// Note: Prior to VERSION 1.1, the native1 response’s root node was an object with a single field “native” that would contain the object above as its value. // The Native Object specified above is now the root object. // // Note re: assetsurl format responses: In the case of assetsurl or dcourl (beta) bidding, since the ultimate buyer/creative engine cannot alter the assets response based on the details inside the assets request (as it does not receive said request), it is critical that all required assets are provided, and such communications will need to be handled offline for recommended/optional elements. @@ -44,7 +44,7 @@ type Response struct { // Type: // object array // Description: - // List of native ad’s assets. + // List of native1 ad’s assets. // Required if no assetsurl. // Recommended as fallback even if assetsurl is provided. Assets []Asset `json:"assets,omitempty"` @@ -70,7 +70,7 @@ type Response struct { // string // Description: // URL where a dynamic creative specification may be found for populating this ad, per the Dynamic Content Ads Specification. - // Note this is a beta option as the interpretation of the Dynamic Content Ads Specification and how to assign those elements into a native ad is outside the scope of this spec and must be agreed offline between the parties or as may be specified in a future revision of the Dynamic Content Ads spec. + // Note this is a beta option as the interpretation of the Dynamic Content Ads Specification and how to assign those elements into a native1 ad is outside the scope of this spec and must be agreed offline between the parties or as may be specified in a future revision of the Dynamic Content Ads spec. // Where present, overrides the asset object in the response. DCOURL string `json:"dcourl,omitempty"` diff --git a/native/response/response_suite_test.go b/native1/response/response_suite_test.go similarity index 100% rename from native/response/response_suite_test.go rename to native1/response/response_suite_test.go diff --git a/native/response/response_test.go b/native1/response/response_test.go similarity index 95% rename from native/response/response_test.go rename to native1/response/response_test.go index b7f7cca..63712ce 100644 --- a/native/response/response_test.go +++ b/native1/response/response_test.go @@ -5,7 +5,7 @@ import ( "io/ioutil" "path/filepath" - . "github.com/mxmCherry/openrtb/native/response" + . "github.com/mxmCherry/openrtb/native1/response" . "github.com/onsi/ginkgo" . "github.com/onsi/ginkgo/extensions/table" diff --git a/native1/response/testdata/v1.1/README.md b/native1/response/testdata/v1.1/README.md new file mode 100644 index 0000000..c3b44cf --- /dev/null +++ b/native1/response/testdata/v1.1/README.md @@ -0,0 +1,5 @@ +# native1/response/testdata/v1.1 + +JSON examples copied from [OpenRTB Dynamic Native Ads API](https://iabtechlab.com/standards/openrtb-native/) [1.1](https://iabtechlab.com/wp-content/uploads/2016/04/OpenRTB-Native-Ads-Specification-2016.pdf)section "6 Bid Request/Response Samples". + +Some empty/zero attributes were omited (not copied) because of [encoding/json](https://golang.org/pkg/encoding/json/) `omitempty` and [gomega.MatchJSON(...)](http://onsi.github.io/gomega/#matchjsonjson-interface). diff --git a/native/response/testdata/v1.1/clickout.json b/native1/response/testdata/v1.1/clickout.json similarity index 100% rename from native/response/testdata/v1.1/clickout.json rename to native1/response/testdata/v1.1/clickout.json diff --git a/native/response/testdata/v1.1/video.json b/native1/response/testdata/v1.1/video.json similarity index 100% rename from native/response/testdata/v1.1/video.json rename to native1/response/testdata/v1.1/video.json diff --git a/native1/response/testdata/v1.2/README.md b/native1/response/testdata/v1.2/README.md new file mode 100644 index 0000000..0057a51 --- /dev/null +++ b/native1/response/testdata/v1.2/README.md @@ -0,0 +1,5 @@ +# native1/response/testdata/v1.2 + +JSON examples copied from [OpenRTB Dynamic Native Ads API](https://iabtechlab.com/standards/openrtb-native/) [1.2](https://iabtechlab.com/wp-content/uploads/2016/07/OpenRTB-Native-Ads-Specification-Final-1.2.pdf) section "6 Bid Request/Response Samples". + +Some empty/zero attributes were omited (not copied) because of [encoding/json](https://golang.org/pkg/encoding/json/) `omitempty` and [gomega.MatchJSON(...)](http://onsi.github.io/gomega/#matchjsonjson-interface). diff --git a/native/response/testdata/v1.2/clickout.json b/native1/response/testdata/v1.2/clickout.json similarity index 100% rename from native/response/testdata/v1.2/clickout.json rename to native1/response/testdata/v1.2/clickout.json diff --git a/native/response/testdata/v1.2/third-party.json b/native1/response/testdata/v1.2/third-party.json similarity index 100% rename from native/response/testdata/v1.2/third-party.json rename to native1/response/testdata/v1.2/third-party.json diff --git a/native/response/testdata/v1.2/video.json b/native1/response/testdata/v1.2/video.json similarity index 100% rename from native/response/testdata/v1.2/video.json rename to native1/response/testdata/v1.2/video.json diff --git a/native/response/title.go b/native1/response/title.go similarity index 100% rename from native/response/title.go rename to native1/response/title.go diff --git a/native/response/video.go b/native1/response/video.go similarity index 100% rename from native/response/video.go rename to native1/response/video.go diff --git a/openrtb2/README.md b/openrtb2/README.md new file mode 100644 index 0000000..0f7ae09 --- /dev/null +++ b/openrtb2/README.md @@ -0,0 +1,3 @@ +# openrtb3 + +[OpenRTB](https://iabtechlab.com/standards/openrtb/) [2.5](https://iabtechlab.com/wp-content/uploads/2016/07/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) types for [Go programming language](https://golang.org/) diff --git a/ad_position.go b/openrtb2/ad_position.go similarity index 98% rename from ad_position.go rename to openrtb2/ad_position.go index 90ee34e..2f76994 100644 --- a/ad_position.go +++ b/openrtb2/ad_position.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.4 Ad Position // diff --git a/api_framework.go b/openrtb2/api_framework.go similarity index 96% rename from api_framework.go rename to openrtb2/api_framework.go index 835e46d..f5403bd 100644 --- a/api_framework.go +++ b/openrtb2/api_framework.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.6 API Frameworks // diff --git a/app.go b/openrtb2/app.go similarity index 99% rename from app.go rename to openrtb2/app.go index 589dace..ce08d67 100644 --- a/app.go +++ b/openrtb2/app.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/audio.go b/openrtb2/audio.go similarity index 96% rename from audio.go rename to openrtb2/audio.go index ddca515..9b2ac5a 100644 --- a/audio.go +++ b/openrtb2/audio.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" @@ -63,7 +63,7 @@ type Audio struct { // If multiple ad impressions are offered in the same bid request, // the sequence number will allow for the coordinated delivery // of multiple creatives. - Sequence uint64 `json:"sequence,omitempty"` + Sequence int64 `json:"sequence,omitempty"` // Attribute: // battr @@ -91,7 +91,7 @@ type Audio struct { // integer // Description: // Minimum bit rate in Kbps. - MinBitrate uint64 `json:"minbitrate,omitempty"` + MinBitrate int64 `json:"minbitrate,omitempty"` // Attribute: // maxbitrate @@ -99,7 +99,7 @@ type Audio struct { // integer // Description: // Maximum bit rate in Kbps. - MaxBitrate uint64 `json:"maxbitrate,omitempty"` + MaxBitrate int64 `json:"maxbitrate,omitempty"` // Attribute: // delivery @@ -147,7 +147,7 @@ type Audio struct { // The maximum number of ads that can be played in an ad pod. // OpenRTB API Specification Version 2.5 IAB Technology Lab // www.iab.com/openrtb Page 18 - MaxSeq uint64 `json:"maxseq,omitempty"` + MaxSeq int64 `json:"maxseq,omitempty"` // Attribute: // feed diff --git a/banner.go b/openrtb2/banner.go similarity index 95% rename from banner.go rename to openrtb2/banner.go index 70968fc..23fc078 100644 --- a/banner.go +++ b/openrtb2/banner.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" @@ -30,7 +30,7 @@ type Banner struct { // Description: // Exact width in device independent pixels (DIPS); // recommended if no format objects are specified. - W *uint64 `json:"w,omitempty"` + W *int64 `json:"w,omitempty"` // Attribute: // h @@ -39,7 +39,7 @@ type Banner struct { // Description: // Exact height in device independent pixels (DIPS); // recommended if no format objects are specified. - H *uint64 `json:"h,omitempty"` + H *int64 `json:"h,omitempty"` // Attribute: // wmax @@ -48,7 +48,7 @@ type Banner struct { // Description: // NOTE: Deprecated in favor of the format array. // Maximum width in device independent pixels (DIPS). - WMax uint64 `json:"wmax,omitempty"` + WMax int64 `json:"wmax,omitempty"` // Attribute: // hmax @@ -57,7 +57,7 @@ type Banner struct { // Description: // NOTE: Deprecated in favor of the format array. // Maximum height in device independent pixels (DIPS). - HMax uint64 `json:"hmax,omitempty"` + HMax int64 `json:"hmax,omitempty"` // Attribute: // wmin @@ -66,7 +66,7 @@ type Banner struct { // Description: // NOTE: Deprecated in favor of the format array. // Minimum width in device independent pixels (DIPS). - WMin uint64 `json:"wmin,omitempty"` + WMin int64 `json:"wmin,omitempty"` // Attribute: // hmin @@ -75,7 +75,7 @@ type Banner struct { // Description: // NOTE: Deprecated in favor of the format array. // Minimum height in device independent pixels (DIPS). - HMin uint64 `json:"hmin,omitempty"` + HMin int64 `json:"hmin,omitempty"` // Attribute: // btype diff --git a/banner_ad_type.go b/openrtb2/banner_ad_type.go similarity index 96% rename from banner_ad_type.go rename to openrtb2/banner_ad_type.go index 65b6efe..f597250 100644 --- a/banner_ad_type.go +++ b/openrtb2/banner_ad_type.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.2 Banner Ad Types // diff --git a/bid.go b/openrtb2/bid.go similarity index 98% rename from bid.go rename to openrtb2/bid.go index 956d7bb..d4e7b5c 100644 --- a/bid.go +++ b/openrtb2/bid.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" @@ -232,7 +232,7 @@ type Bid struct { // integer // Description: // Width of the creative in device independent pixels (DIPS). - W uint64 `json:"w,omitempty"` + W int64 `json:"w,omitempty"` // Attribute: // h @@ -240,7 +240,7 @@ type Bid struct { // integer // Description: // Height of the creative in device independent pixels (DIPS). - H uint64 `json:"h,omitempty"` + H int64 `json:"h,omitempty"` // Attribute: // wratio @@ -249,7 +249,7 @@ type Bid struct { // Description: // Relative width of the creative when expressing size as a ratio. // Required for Flex Ads. - WRatio uint64 `json:"wratio,omitempty"` + WRatio int64 `json:"wratio,omitempty"` // Attribute: // hratio @@ -258,7 +258,7 @@ type Bid struct { // Description: // Relative height of the creative when expressing size as a ratio. // Required for Flex Ads. - HRatio uint64 `json:"hratio,omitempty"` + HRatio int64 `json:"hratio,omitempty"` // Attribute: // exp diff --git a/bid_request.go b/openrtb2/bid_request.go similarity index 99% rename from bid_request.go rename to openrtb2/bid_request.go index 6ac82dc..07ad36d 100644 --- a/bid_request.go +++ b/openrtb2/bid_request.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/bid_request_test.go b/openrtb2/bid_request_test.go similarity index 94% rename from bid_request_test.go rename to openrtb2/bid_request_test.go index c22b5b1..270304a 100644 --- a/bid_request_test.go +++ b/openrtb2/bid_request_test.go @@ -1,11 +1,11 @@ -package openrtb_test +package openrtb2_test import ( "encoding/json" "io/ioutil" "path/filepath" - . "github.com/mxmCherry/openrtb" + . "github.com/mxmCherry/openrtb/openrtb2" . "github.com/onsi/ginkgo" . "github.com/onsi/ginkgo/extensions/table" diff --git a/bid_response.go b/openrtb2/bid_response.go similarity index 99% rename from bid_response.go rename to openrtb2/bid_response.go index a9572cf..acc2c9a 100644 --- a/bid_response.go +++ b/openrtb2/bid_response.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/bid_response_test.go b/openrtb2/bid_response_test.go similarity index 94% rename from bid_response_test.go rename to openrtb2/bid_response_test.go index e2bc236..aba9e0a 100644 --- a/bid_response_test.go +++ b/openrtb2/bid_response_test.go @@ -1,11 +1,11 @@ -package openrtb_test +package openrtb2_test import ( "encoding/json" "io/ioutil" "path/filepath" - . "github.com/mxmCherry/openrtb" + . "github.com/mxmCherry/openrtb/openrtb2" . "github.com/onsi/ginkgo" . "github.com/onsi/ginkgo/extensions/table" diff --git a/companion_type.go b/openrtb2/companion_type.go similarity index 96% rename from companion_type.go rename to openrtb2/companion_type.go index 4c38e50..2c538db 100644 --- a/companion_type.go +++ b/openrtb2/companion_type.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.14 Companion Types // diff --git a/connection_type.go b/openrtb2/connection_type.go similarity index 98% rename from connection_type.go rename to openrtb2/connection_type.go index 7cc78fa..215121b 100644 --- a/connection_type.go +++ b/openrtb2/connection_type.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.22 Connection Type // diff --git a/content.go b/openrtb2/content.go similarity index 98% rename from content.go rename to openrtb2/content.go index 395abed..7e59c71 100644 --- a/content.go +++ b/openrtb2/content.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" @@ -24,7 +24,7 @@ type Content struct { // integer // Description: // Episode number. - Episode uint64 `json:"episode,omitempty"` + Episode int64 `json:"episode,omitempty"` // Attribute: // title diff --git a/content_context.go b/openrtb2/content_context.go similarity index 98% rename from content_context.go rename to openrtb2/content_context.go index c0291f3..d3e89a1 100644 --- a/content_context.go +++ b/openrtb2/content_context.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.18 Content Context // diff --git a/content_delivery_method.go b/openrtb2/content_delivery_method.go similarity index 95% rename from content_delivery_method.go rename to openrtb2/content_delivery_method.go index f33bd00..d84b4bc 100644 --- a/content_delivery_method.go +++ b/openrtb2/content_delivery_method.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.15 Content Delivery Methods // diff --git a/creative_attribute.go b/openrtb2/creative_attribute.go similarity index 99% rename from creative_attribute.go rename to openrtb2/creative_attribute.go index 32f3908..326340d 100644 --- a/creative_attribute.go +++ b/openrtb2/creative_attribute.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.3 Creative Attributes // diff --git a/data.go b/openrtb2/data.go similarity index 98% rename from data.go rename to openrtb2/data.go index 77387a7..b255410 100644 --- a/data.go +++ b/openrtb2/data.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/deal.go b/openrtb2/deal.go similarity index 99% rename from deal.go rename to openrtb2/deal.go index 98bf652..9919f84 100644 --- a/deal.go +++ b/openrtb2/deal.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/device.go b/openrtb2/device.go similarity index 98% rename from device.go rename to openrtb2/device.go index 4d1ef8c..a356976 100644 --- a/device.go +++ b/openrtb2/device.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" @@ -123,7 +123,7 @@ type Device struct { // integer // Description: // Physical height of the screen in pixels. - H uint64 `json:"h,omitempty"` + H int64 `json:"h,omitempty"` // Attribute: // w @@ -131,7 +131,7 @@ type Device struct { // integer // Description: // Physical width of the screen in pixels. - W uint64 `json:"w,omitempty"` + W int64 `json:"w,omitempty"` // Attribute: // ppi @@ -139,7 +139,7 @@ type Device struct { // integer // Description: // Screen size as pixels per linear inch. - PPI uint64 `json:"ppi,omitempty"` + PPI int64 `json:"ppi,omitempty"` // Attribute: // pxratio diff --git a/device_type.go b/openrtb2/device_type.go similarity index 98% rename from device_type.go rename to openrtb2/device_type.go index b710f6b..33dfa5a 100644 --- a/device_type.go +++ b/openrtb2/device_type.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.21 Device Type // diff --git a/expandable_direction.go b/openrtb2/expandable_direction.go similarity index 96% rename from expandable_direction.go rename to openrtb2/expandable_direction.go index d51a28d..3f90291 100644 --- a/expandable_direction.go +++ b/openrtb2/expandable_direction.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.5 Expandable Direction // diff --git a/feed_type.go b/openrtb2/feed_type.go similarity index 93% rename from feed_type.go rename to openrtb2/feed_type.go index 785edab..5f62578 100644 --- a/feed_type.go +++ b/openrtb2/feed_type.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.16 Feed Types // diff --git a/format.go b/openrtb2/format.go similarity index 86% rename from format.go rename to openrtb2/format.go index f15835c..eb97101 100644 --- a/format.go +++ b/openrtb2/format.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" @@ -15,7 +15,7 @@ type Format struct { // integer // Description: // Width in device independent pixels (DIPS). - W uint64 `json:"w,omitempty"` + W int64 `json:"w,omitempty"` // Attribute: // h @@ -23,7 +23,7 @@ type Format struct { // integer // Description: // Height in device independent pixels (DIPS). - H uint64 `json:"h,omitempty"` + H int64 `json:"h,omitempty"` // Attribute: // wratio @@ -31,7 +31,7 @@ type Format struct { // integer // Description: // Relative width when expressing size as a ratio - WRatio uint64 `json:"wratio,omitempty"` + WRatio int64 `json:"wratio,omitempty"` // Attribute: // hratio @@ -39,7 +39,7 @@ type Format struct { // Integer // Description: // Relative height when expressing size as a ratio. - HRatio uint64 `json:"hratio,omitempty"` + HRatio int64 `json:"hratio,omitempty"` // Attribute: // wmin @@ -48,7 +48,7 @@ type Format struct { // Description: // The minimum width in device independent pixels (DIPS) at // which the ad will be displayed the size is expressed as a ratio. - WMin uint64 `json:"wmin,omitempty"` + WMin int64 `json:"wmin,omitempty"` // Attribute: // ext diff --git a/geo.go b/openrtb2/geo.go similarity index 98% rename from geo.go rename to openrtb2/geo.go index a709449..0417f9d 100644 --- a/geo.go +++ b/openrtb2/geo.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" @@ -48,7 +48,7 @@ type Geo struct { // services (i.e., type = 1). Note that this is the accuracy as // reported from the device. Consult OS specific documentation // (e.g., Android, iOS) for exact interpretation. - Accuracy uint64 `json:"accuracy,omitempty"` + Accuracy int64 `json:"accuracy,omitempty"` // Attribute: // lastfix diff --git a/imp.go b/openrtb2/imp.go similarity index 99% rename from imp.go rename to openrtb2/imp.go index b636845..d46411e 100644 --- a/imp.go +++ b/openrtb2/imp.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/ip_location_service.go b/openrtb2/ip_location_service.go similarity index 96% rename from ip_location_service.go rename to openrtb2/ip_location_service.go index 1053a00..012ccf8 100644 --- a/ip_location_service.go +++ b/openrtb2/ip_location_service.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.23 IP Location Services // diff --git a/iqg_media_rating.go b/openrtb2/iqg_media_rating.go similarity index 95% rename from iqg_media_rating.go rename to openrtb2/iqg_media_rating.go index eeeb773..5130d5f 100644 --- a/iqg_media_rating.go +++ b/openrtb2/iqg_media_rating.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.19 IQG Media Ratings // diff --git a/location_type.go b/openrtb2/location_type.go similarity index 95% rename from location_type.go rename to openrtb2/location_type.go index ec44166..6799687 100644 --- a/location_type.go +++ b/openrtb2/location_type.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.20 Location Type // diff --git a/loss_reason_code.go b/openrtb2/loss_reason_code.go similarity index 99% rename from loss_reason_code.go rename to openrtb2/loss_reason_code.go index ff0eff9..c22ce12 100644 --- a/loss_reason_code.go +++ b/openrtb2/loss_reason_code.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.25 Loss Reason Codes // diff --git a/metric.go b/openrtb2/metric.go similarity index 98% rename from metric.go rename to openrtb2/metric.go index e160860..2d6f98b 100644 --- a/metric.go +++ b/openrtb2/metric.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/native.go b/openrtb2/native.go similarity index 99% rename from native.go rename to openrtb2/native.go index 377d865..0888e09 100644 --- a/native.go +++ b/openrtb2/native.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/no_bid_reason_code.go b/openrtb2/no_bid_reason_code.go similarity index 98% rename from no_bid_reason_code.go rename to openrtb2/no_bid_reason_code.go index 9ac8555..785cfad 100644 --- a/no_bid_reason_code.go +++ b/openrtb2/no_bid_reason_code.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.24 No-Bid Reason Codes // diff --git a/openrtb.go b/openrtb2/openrtb.go similarity index 92% rename from openrtb.go rename to openrtb2/openrtb.go index 1df57e1..a76d11e 100644 --- a/openrtb.go +++ b/openrtb2/openrtb.go @@ -1,4 +1,4 @@ // Package openrtb provides OpenRTB v2.5 types: // https://www.iab.com/guidelines/real-time-bidding-rtb-project/ // https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf -package openrtb +package openrtb2 diff --git a/openrtb2/openrtb_suite_test.go b/openrtb2/openrtb_suite_test.go new file mode 100644 index 0000000..e3aa765 --- /dev/null +++ b/openrtb2/openrtb_suite_test.go @@ -0,0 +1,13 @@ +package openrtb2_test + +import ( + . "github.com/onsi/ginkgo" + . "github.com/onsi/gomega" + + "testing" +) + +func TestOpenrtb2(t *testing.T) { + RegisterFailHandler(Fail) + RunSpecs(t, "Openrtb2 Suite") +} diff --git a/playback_cessation_mode.go b/openrtb2/playback_cessation_mode.go similarity index 97% rename from playback_cessation_mode.go rename to openrtb2/playback_cessation_mode.go index 3ef3d56..0d28218 100644 --- a/playback_cessation_mode.go +++ b/openrtb2/playback_cessation_mode.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.11 Playback Cessation Modes // diff --git a/playback_method.go b/openrtb2/playback_method.go similarity index 97% rename from playback_method.go rename to openrtb2/playback_method.go index 87d8289..4f01e6a 100644 --- a/playback_method.go +++ b/openrtb2/playback_method.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.10 Playback Methods // diff --git a/pmp.go b/openrtb2/pmp.go similarity index 98% rename from pmp.go rename to openrtb2/pmp.go index 24d43d3..c969f2e 100644 --- a/pmp.go +++ b/openrtb2/pmp.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/producer.go b/openrtb2/producer.go similarity index 98% rename from producer.go rename to openrtb2/producer.go index c03f961..2acd6ee 100644 --- a/producer.go +++ b/openrtb2/producer.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/production_quality.go b/openrtb2/production_quality.go similarity index 98% rename from production_quality.go rename to openrtb2/production_quality.go index 67f4aa6..2403240 100644 --- a/production_quality.go +++ b/openrtb2/production_quality.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.13 Production Quality // diff --git a/protocol.go b/openrtb2/protocol.go similarity index 97% rename from protocol.go rename to openrtb2/protocol.go index 9b2860c..2e12345 100644 --- a/protocol.go +++ b/openrtb2/protocol.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.8 Protocols // diff --git a/ptr.go b/openrtb2/ptr.go similarity index 50% rename from ptr.go rename to openrtb2/ptr.go index 65b8a2a..79b82c6 100644 --- a/ptr.go +++ b/openrtb2/ptr.go @@ -1,11 +1,11 @@ -package openrtb +package openrtb2 // Int8Ptr returns pointer to passed argument. func Int8Ptr(n int8) *int8 { return &n } -// Uint64Ptr returns pointer to passed argument. -func Uint64Ptr(n uint64) *uint64 { +// Int64Ptr returns pointer to passed argument. +func Int64Ptr(n int64) *int64 { return &n } diff --git a/publisher.go b/openrtb2/publisher.go similarity index 98% rename from publisher.go rename to openrtb2/publisher.go index 51b2fa5..fdeeff1 100644 --- a/publisher.go +++ b/openrtb2/publisher.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/regs.go b/openrtb2/regs.go similarity index 98% rename from regs.go rename to openrtb2/regs.go index 6413859..84a9231 100644 --- a/regs.go +++ b/openrtb2/regs.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/seat_bid.go b/openrtb2/seat_bid.go similarity index 98% rename from seat_bid.go rename to openrtb2/seat_bid.go index e01f700..6ab7956 100644 --- a/seat_bid.go +++ b/openrtb2/seat_bid.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/segment.go b/openrtb2/segment.go similarity index 98% rename from segment.go rename to openrtb2/segment.go index d5c4d07..625be07 100644 --- a/segment.go +++ b/openrtb2/segment.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/site.go b/openrtb2/site.go similarity index 99% rename from site.go rename to openrtb2/site.go index dcbeab3..e07a47b 100644 --- a/site.go +++ b/openrtb2/site.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/source.go b/openrtb2/source.go similarity index 98% rename from source.go rename to openrtb2/source.go index f341d44..d622121 100644 --- a/source.go +++ b/openrtb2/source.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/start_delay.go b/openrtb2/start_delay.go similarity index 97% rename from start_delay.go rename to openrtb2/start_delay.go index 07546f7..dcde3e2 100644 --- a/start_delay.go +++ b/openrtb2/start_delay.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.12 Start Delay // diff --git a/openrtb2/testdata/README.md b/openrtb2/testdata/README.md new file mode 100644 index 0000000..85b1e8e --- /dev/null +++ b/openrtb2/testdata/README.md @@ -0,0 +1,5 @@ +# testdata + +JSON examples copied from [OpenRTB](https://iabtechlab.com/standards/openrtb/) [2.5](https://iabtechlab.com/wp-content/uploads/2016/07/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) spec - section 6. Bid Request/Response Samples. + +Some empty/zero attributes were omited (not copied) because of [encoding/json](https://golang.org/pkg/encoding/json/) `omitempty` and [gomega.MatchJSON(...)](http://onsi.github.io/gomega/#matchjsonjson-interface). diff --git a/testdata/bid-request/expandable-creative.json b/openrtb2/testdata/bid-request/expandable-creative.json similarity index 100% rename from testdata/bid-request/expandable-creative.json rename to openrtb2/testdata/bid-request/expandable-creative.json diff --git a/testdata/bid-request/mobile.json b/openrtb2/testdata/bid-request/mobile.json similarity index 100% rename from testdata/bid-request/mobile.json rename to openrtb2/testdata/bid-request/mobile.json diff --git a/testdata/bid-request/native-ad.json b/openrtb2/testdata/bid-request/native-ad.json similarity index 100% rename from testdata/bid-request/native-ad.json rename to openrtb2/testdata/bid-request/native-ad.json diff --git a/testdata/bid-request/pmp-with-direct-deal.json b/openrtb2/testdata/bid-request/pmp-with-direct-deal.json similarity index 100% rename from testdata/bid-request/pmp-with-direct-deal.json rename to openrtb2/testdata/bid-request/pmp-with-direct-deal.json diff --git a/testdata/bid-request/simple-banner.json b/openrtb2/testdata/bid-request/simple-banner.json similarity index 100% rename from testdata/bid-request/simple-banner.json rename to openrtb2/testdata/bid-request/simple-banner.json diff --git a/testdata/bid-request/video.json b/openrtb2/testdata/bid-request/video.json similarity index 100% rename from testdata/bid-request/video.json rename to openrtb2/testdata/bid-request/video.json diff --git a/testdata/bid-response/ad-served-on-win-notice.json b/openrtb2/testdata/bid-response/ad-served-on-win-notice.json similarity index 100% rename from testdata/bid-response/ad-served-on-win-notice.json rename to openrtb2/testdata/bid-response/ad-served-on-win-notice.json diff --git a/testdata/bid-response/direct-deal-ad-served-on-win-notice.json b/openrtb2/testdata/bid-response/direct-deal-ad-served-on-win-notice.json similarity index 100% rename from testdata/bid-response/direct-deal-ad-served-on-win-notice.json rename to openrtb2/testdata/bid-response/direct-deal-ad-served-on-win-notice.json diff --git a/testdata/bid-response/native-markup-returned-inline.json b/openrtb2/testdata/bid-response/native-markup-returned-inline.json similarity index 100% rename from testdata/bid-response/native-markup-returned-inline.json rename to openrtb2/testdata/bid-response/native-markup-returned-inline.json diff --git a/testdata/bid-response/vast-xml-document-returned-inline.json b/openrtb2/testdata/bid-response/vast-xml-document-returned-inline.json similarity index 100% rename from testdata/bid-response/vast-xml-document-returned-inline.json rename to openrtb2/testdata/bid-response/vast-xml-document-returned-inline.json diff --git a/user.go b/openrtb2/user.go similarity index 99% rename from user.go rename to openrtb2/user.go index ad1783f..271c3a8 100644 --- a/user.go +++ b/openrtb2/user.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" diff --git a/video.go b/openrtb2/video.go similarity index 97% rename from video.go rename to openrtb2/video.go index d7d7d4e..19702e0 100644 --- a/video.go +++ b/openrtb2/video.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 import "encoding/json" @@ -66,7 +66,7 @@ type Video struct { // integer; recommended // Description: // Width of the video player in device independent pixels (DIPS). - W uint64 `json:"w,omitempty"` + W int64 `json:"w,omitempty"` // Attribute: // h @@ -74,7 +74,7 @@ type Video struct { // integer; recommended // Description: // Height of the video player in device independent pixels (DIPS). - H uint64 `json:"h,omitempty"` + H int64 `json:"h,omitempty"` // Attribute: // startdelay @@ -169,7 +169,7 @@ type Video struct { // integer // Description: // Minimum bit rate in Kbps. - MinBitRate uint64 `json:"minbitrate,omitempty"` + MinBitRate int64 `json:"minbitrate,omitempty"` // Attribute: // maxbitrate @@ -177,7 +177,7 @@ type Video struct { // integer // Description: // Maximum bit rate in Kbps. - MaxBitRate uint64 `json:"maxbitrate,omitempty"` + MaxBitRate int64 `json:"maxbitrate,omitempty"` // Attribute: // boxingallowed diff --git a/video_linearity.go b/openrtb2/video_linearity.go similarity index 97% rename from video_linearity.go rename to openrtb2/video_linearity.go index 9440910..07fc9bb 100644 --- a/video_linearity.go +++ b/openrtb2/video_linearity.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.7 Video Linearity // diff --git a/video_placement_type.go b/openrtb2/video_placement_type.go similarity index 98% rename from video_placement_type.go rename to openrtb2/video_placement_type.go index 18e6e06..41b6042 100644 --- a/video_placement_type.go +++ b/openrtb2/video_placement_type.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.9 Video Placement Types // diff --git a/volume_normalization_mode.go b/openrtb2/volume_normalization_mode.go similarity index 98% rename from volume_normalization_mode.go rename to openrtb2/volume_normalization_mode.go index 6cbee27..44e6475 100644 --- a/volume_normalization_mode.go +++ b/openrtb2/volume_normalization_mode.go @@ -1,4 +1,4 @@ -package openrtb +package openrtb2 // 5.17 Volume Normalization Modes // diff --git a/openrtb3/README.md b/openrtb3/README.md new file mode 100644 index 0000000..731197f --- /dev/null +++ b/openrtb3/README.md @@ -0,0 +1,3 @@ +# openrtb3 + +[OpenRTB](https://iabtechlab.com/standards/openrtb/) [3.0](https://github.com/InteractiveAdvertisingBureau/openrtb) types for [Go programming language](https://golang.org/) diff --git a/openrtb3/auction_type.go b/openrtb3/auction_type.go new file mode 100644 index 0000000..bcaf51a --- /dev/null +++ b/openrtb3/auction_type.go @@ -0,0 +1,13 @@ +package openrtb3 + +// AuctionType defines an auction type. +type AuctionType int64 + +// AuctionType values. +const ( + FirstPrice AuctionType = 1 + SecondPricePlus = 2 + DealPrice = 3 // the value passed in flr is the agreed upon deal price + + // Values greater than 500 can be used for exchange-specific auction types. +) diff --git a/openrtb3/bid.go b/openrtb3/bid.go new file mode 100644 index 0000000..f41c7ef --- /dev/null +++ b/openrtb3/bid.go @@ -0,0 +1,130 @@ +package openrtb3 + +import "encoding/json" + +// Bid is an OpenRTB bid object. +// A Seatbid object contains one or more Bid objects, each of which relates to a specific item in the bid request offer via the “item” attribute and constitutes an offer to buy that item for a given price. +type Bid struct { + // Attribute: + // id + // Type: + // string; recommended + // Definition: + // Bidder generated bid ID to assist with logging/tracking. + ID string `json:"id,omitempty"` + + // Attribute: + // item + // Type: + // string; required + // Definition: + // ID of the item object in the related bid request; specifically item.id. + Item string `json:"item,omitempty"` + + // Attribute: + // price + // Type: + // float; required + // Definition: + // Bid price expressed as CPM although the actual transaction is for a unit item only + // Note that while the type indicates float, integer math is highly recommended when handling currencies (e.g., BigDecimal in Java). + Price float64 `json:"price,omitempty"` + + // Attribute: + // deal + // Type: + // string + // Definition: + // Reference to a deal from the bid request if this bid pertains to a private marketplace deal; specifically deal.id. + Deal string `json:"deal,omitempty"` + + // Attribute: + // cid + // Type: + // string + // Definition: + // Campaign ID or other similar grouping of brand-related ads + // Typically used to increase the efficiency of audit processes. + CID string `json:"cid,omitempty"` + + // Attribute: + // tactic + // Type: + // string + // Definition: + // Tactic ID to enable buyers to label bids for reporting to the exchange the tactic through which their bid was submitted + // The specific usage and meaning of the tactic ID should be communicated between buyer and exchanges a priori. + Tactic string `json:"tactic,omitempty"` + + // Attribute: + // purl + // Type: + // string + // Definition: + // Pending notice URL called by the exchange when a bid has been declared the winner within the scope of an OpenRTB compliant supply chain (i.e., there may still be non-compliant decisioning such as header bidding) + // Substitution macros may be included. + PURL string `json:"purl,omitempty"` + + // Attribute: + // burl + // Type: + // string; recommended + // Definition: + // Billing notice URL called by the exchange when a winning bid becomes billable based on exchange-specific business policy (e.g., markup rendered) + // Substitution macros may be included. + BURL string `json:"burl,omitempty"` + + // Attribute: + // lurl + // Type: + // string + // Definition: + // Loss notice URL called by the exchange when a bid is known to have been lost + // Substitution macros may be included + // Exchange-specific policy may preclude support for loss notices or the disclosure of winning clearing prices resulting in ${OPENRTB_PRICE} macros being removed (i.e., replaced with a zero-length string). + LURL string `json:"lurl,omitempty"` + + // Attribute: + // exp + // Type: + // integer + // Definition: + // Advisory as to the number of seconds the buyer is willing to wait between auction and fulfilment. + Exp int64 `json:"exp,omitempty"` + + // Attribute: + // mid + // Type: + // string + // Definition: + // ID to enable media to be specified by reference if previously uploaded to the exchange rather than including it by value in the domain objects. + MID string `json:"mid,omitempty"` + + // Attribute: + // macro + // Type: + // object array + // Definition: + // Array of Macro objects that enable bid specific values to be substituted into markup; especially useful for previously uploaded media referenced via the mid attribute + // Refer to Object: Macro. + Macro []Macro `json:"macro,omitempty"` + + // Attribute: + // media + // Type: + // object + // Definition: + // Layer-4 domain object structure that specifies the media to be presented if the bid is won conforming to the specification and version referenced in openrtb.domainspec and openrtb.domainver + // For AdCOM v1.x, the objects allowed here are “Ad” and any objects subordinate thereto as specified by AdCOM. + // Dev note: + // This object is implemented as ../adcom1.BidMedia type. + Media json.RawMessage `json:"media,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional demand source specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/openrtb3/body.go b/openrtb3/body.go new file mode 100644 index 0000000..3c1b552 --- /dev/null +++ b/openrtb3/body.go @@ -0,0 +1,6 @@ +package openrtb3 + +// Body is a top-level wrapper for OpenRTB requests. +type Body struct { + OpenRTB OpenRTB `json:"openrtb"` +} diff --git a/openrtb3/deal.go b/openrtb3/deal.go new file mode 100644 index 0000000..fba2dee --- /dev/null +++ b/openrtb3/deal.go @@ -0,0 +1,67 @@ +package openrtb3 + +import "encoding/json" + +// Deal object constitutes a specific deal that was struck a priori between a seller and a buyer. +// Its presence indicates that this item is available under the terms of that deal. +type Deal struct { + // Attribute: + // id + // Type: + // string; required + // Definition: + // A unique identifier for the deal. + ID string `json:"id,omitempty"` + + // Attribute: + // flr + // Type: + // float + // Definition: + // Minimum deal price for this item expressed in CPM. + Flr float64 `json:"flr,omitempty"` + + // Attribute: + // flrcur + // Type: + // string; default "USD" + // Definition: + // Currency of the flr attribute specified using ISO-4217 alpha codes. + FlrCur string `json:"flrcur,omitempty"` + + // Attribute: + // at + // Type: + // integer + // Definition: + // Optional override of the overall auction type of the request, where 1 = First Price, 2 = Second Price Plus, 3 = the value passed in flr is the agreed upon deal price. + // Additional auction types can be defined by the exchange using 500+ values. + AT AuctionType `json:"at,omitempty"` + + // Attribute: + // wseat + // Type: + // string array + // Definition: + // Whitelist of buyer seats allowed to bid on this deal. + // IDs of seats and the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori. + // Omission implies no restrictions. + WSeat []string `json:"wseat,omitempty"` + + // Attribute: + // wadomain + // Type: + // string array + // Definition: + // Array of advertiser domains (e.g., advertiser.com) allowed to bid on this deal. + // Omission implies no restrictions. + WADomain []string `json:"wadomain,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional exchange-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/openrtb3/item.go b/openrtb3/item.go new file mode 100644 index 0000000..fd106ba --- /dev/null +++ b/openrtb3/item.go @@ -0,0 +1,118 @@ +package openrtb3 + +import "encoding/json" + +// Item object represents a unit of goods being offered for sale either on the open market or in relation to a private marketplace deal. +// The id attribute is required since there may be multiple items being offered in the same bid request and bids must reference the specific item of interest. +// This object interfaces to Layer-4 domain objects for deeper specification of the item being offered (e.g., an impression). +type Item struct { + // Attribute: + // id + // Type: + // string; required + // Definition: + // A unique identifier for this item within the context of the offer (typically starts with “1” and increments). + ID string `json:"id"` + + // Attribute: + // qty + // Type: + // integer; default 1 + // Definition: + // The number of instances (i.e., “quantity”) of this item being offered (e.g., multiple identical impressions in a digital out-of-home scenario). + Qty int64 `json:"qty,omitempty"` + + // Attribute: + // seq + // Type: + // integer + // Definition: + // If multiple items are offered in the same bid request, the sequence number allows for the coordinated delivery. + Seq int64 `json:"seq,omitempty"` + + // Attribute: + // flr + // Type: + // float + // Definition: + // Minimum bid price for this item expressed in CPM. + Flr float64 `json:"flr,omitempty"` + + // Attribute: + // flrcur + // Type: + // string; default “USD” + // Definition: + // Currency of the flr attribute specified using ISO-4217 alpha codes. + FlrCur string `json:"flrcur,omitempty"` + + // Attribute: + // exp + // Type: + // integer + // Definition: + // Advisory as to the number of seconds that may elapse between auction and fulfilment. + Exp int64 `json:"exp,omitempty"` + + // Attribute: + // dt + // Type: + // integer + // Definition: + // Timestamp when the item is expected to be fulfilled (e.g when a DOOH impression will be displayed) in Unix format (i.e., milliseconds since the epoch). + DT int64 `json:"dt,omitempty"` + + // Attribute: + // dlvy + // Type: + // integer; default 0 + // Definition: + // Item (e.g., an Ad object) delivery method required, where 0 = either method, 1 = the item must be sent as part of the transaction (e.g., by value in the bid itself, fetched by URL included in the bid), and 2 = an item previously uploaded to the exchange must be referenced by its ID. + // Note that if an exchange does not supported prior upload, then the default of 0 is effectively the same as 1 since there can be no items to reference. + Dlvy int8 `json:"dlvy,omitempty"` + + // Attribute: + // metric + // Type: + // object array + // Definition: + // An array of Metric objects. + // Refer to Object: Metric. + Metric []Metric `json:"metric,omitempty"` + + // Attribute: + // deal + // Type: + // object array + // Definition: + // Array of Deal objects that convey special terms applicable to this item. + // Refer to Object: Deal. + Deal []Deal `json:"deal,omitempty"` + + // Attribute: + // private + // Type: + // integer; default 0 + // Definition: + // Indicator of auction eligibility to seats named in Deal objects, where 0 = all bids are accepted, 1 = bids are restricted to the deals specified and the terms thereof. + Private int8 `json:"private,omitempty"` + + // Attribute: + // spec + // Type: + // object; required + // Definition: + // Layer-4 domain object structure that provides specifies the item being offered conforming to the specification and version referenced in openrtb.domainspec and openrtb.domainver. + // For AdCOM v1.x, the objects allowed here are Placement and any objects subordinate to these as specified by AdCOM. + // Dev note: + // This object is implemented as ../adcom1.ItemSpec type. + Spec json.RawMessage `json:"spec"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional exchange-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/openrtb3/loss_reason.go b/openrtb3/loss_reason.go new file mode 100644 index 0000000..4d4ae3f --- /dev/null +++ b/openrtb3/loss_reason.go @@ -0,0 +1,41 @@ +package openrtb3 + +// LossReason represents OpenRTB Loss Reason Code enumeration. +// +// It lists the options for an exchange to inform a bidder as to the reason why they did not win an item. +type LossReason int64 + +// LossReason options. +// +// Values of 500+ are exchange specific values; should be communicated with buyers a priori. +const ( + LossWon LossReason = 0 // Bid Won + LossInternalError LossReason = 1 // Internal Error + LossExpired LossReason = 2 // Impression Opportunity Expired + LossInvalidResponse LossReason = 3 // Invalid Bid Response + LossInvalidDealID LossReason = 4 // Invalid Deal ID + LossInvalidAuctionID LossReason = 5 // Invalid Auction ID + LossInvalidAdvertiserDomain LossReason = 6 // Invalid Advertiser Domain + LossMissingMarkup LossReason = 7 // Missing Markup + LossMissingCreativeID LossReason = 8 // Missing Creative ID + LossMissingBidPrice LossReason = 9 // Missing Bid Price + LossMissingApproval LossReason = 10 // Missing Minimum Creative Approval Data + LossBelowAuctionFloor LossReason = 100 // Bid was Below Auction Floor + LossBelowDealFloor LossReason = 101 // Bid was Below Deal Floor + LossLostToHigherBid LossReason = 102 // Lost to Higher Bid + LossLostToDealBid LossReason = 103 // Lost to a Bid for a Deal + LossSeatBlocked LossReason = 104 // Buyer Seat Blocked + LossCreativeFiltered LossReason = 200 // Creative Filtered - General; Reason Unknown + LossPendingProcessing LossReason = 201 // Creative Filtered - Pending Processing by Exchange (e.g., approval, transcoding, etc.) + LossDisapproved LossReason = 202 // Creative Filtered - Disapproved by Exchange + LossSizeNotAllowed LossReason = 203 // Creative Filtered - Size Not Allowed + LossIncorrectFormat LossReason = 204 // Creative Filtered - Incorrect Creative Format + LossAdvertiserExclusions LossReason = 205 // Creative Filtered - Advertiser Exclusions + LossNotSecure LossReason = 206 // Creative Filtered - Not Secure + LossLanguageExclusions LossReason = 207 // Creative Filtered - Language Exclusions + LossCategoryExclusions LossReason = 208 // Creative Filtered - Category Exclusions + LossAttributeExclusions LossReason = 209 // Creative Filtered - Creative Attribute Exclusions + LossAdTypeExclusions LossReason = 210 // Creative Filtered - Ad Type Exclusions + LossAnimationTooLong LossReason = 211 // Creative Filtered - Animation Too Long + LossNotAllowedInDeal LossReason = 212 // Creative Filtered - Not Allowed in Deal +) diff --git a/openrtb3/macro.go b/openrtb3/macro.go new file mode 100644 index 0000000..d006b5d --- /dev/null +++ b/openrtb3/macro.go @@ -0,0 +1,33 @@ +package openrtb3 + +import "encoding/json" + +// Macro object constitutes a buyer defined key/value pair used to inject dynamic values into media markup +// While they apply to any media markup irrespective of how it is conveyed, the principle use case is for media that was uploaded to the exchange prior to the transaction (e.g., pre-registered for creative quality review) and referenced in bid +// The full form of the macro to be substituted at runtime is ${CUSTOM_KEY}, where “KEY” is the name supplied in the key attribute +// This ensures no conflict with standard OpenRTB macros. +type Macro struct { + // Attribute: + // key + // Type: + // string; required + // Definition: + // Name of a buyer specific macro. + Key string `json:"key"` + + // Attribute: + // value + // Type: + // string + // Definition: + // Value to substitute for each instance of the macro found in markup. + Value string `json:"value,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional demand source specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/openrtb3/metric.go b/openrtb3/metric.go new file mode 100644 index 0000000..9b98c84 --- /dev/null +++ b/openrtb3/metric.go @@ -0,0 +1,42 @@ +package openrtb3 + +import "encoding/json" + +// Metric object is associated with an item as an array of metrics. +// These metrics can offer insight to assist with decisioning such as average recent viewability, click-through rate, etc. +// Each metric is identified by its type, reports the value of the metric, and optionally identifies the source or vendor measuring the value. +type Metric struct { + // Attribute: + // type + // Type: + // string; required + // Definition: + // Type of metric being presented using exchange curated string names which should be published to bidders a priori. + Type string `json:"type"` + + // Attribute: + // value + // Type: + // float; required + // Definition: + // Number representing the value of the metric. + // Probabilities must be in the range 0.0 – 1.0. + Value float64 `json:"value,omitempty"` + + // Attribute: + // vendor + // Type: + // string; recommended + // Definition: + // Source of the value using exchange curated string names which should be published to bidders a priori. + // If the exchange itself is the source versus a third party, “EXCHANGE” is recommended. + Vendor string `json:"vendor,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional exchange-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/openrtb3/no_bid_reason.go b/openrtb3/no_bid_reason.go new file mode 100644 index 0000000..64b554d --- /dev/null +++ b/openrtb3/no_bid_reason.go @@ -0,0 +1,28 @@ +package openrtb3 + +// NoBidReason represents OpenRTB No-Bid Reason Code enumeration. +// +// It lists the options for a bidder to signal the exchange as to why it did not offer a bid for the item. +type NoBidReason int64 + +// NoBidReason options. +// +// Values of 500+ are exchange specific values; should be communicated with buyers a priori. +const ( + NoBidUnknownError NoBidReason = 0 // Unknown Error + NoBidTechnicalError NoBidReason = 1 // Technical Error + NoBidInvalidRequest NoBidReason = 2 // Invalid Request + NoBidCrawler NoBidReason = 3 // Known Web Crawler + NoBidNonHuman NoBidReason = 4 // Suspected Non-Human Traffic + NoBidProxy NoBidReason = 5 // Cloud, Data Center, or Proxy IP + NoBidUnsupportedDevice NoBidReason = 6 // Unsupported Device + NoBidBlockedPublisher NoBidReason = 7 // Blocked Publisher or Site + NoBidUnmatchedUser NoBidReason = 8 // Unmatched User + NoBidDailyUserCap NoBidReason = 9 // Daily User Cap Met + NoBidDailyDomainCap NoBidReason = 10 // Daily Domain Cap Met + NoBidAuthorizationUnavailable NoBidReason = 11 // Ads.txt Authorization Unavailable + NoBidAuthorizationViolation NoBidReason = 12 // Ads.txt Authorization Violation + NoBidAuthenticationUnavailable NoBidReason = 13 // Ads.cert Authentication Unavailable + NoBidAuthenticationViolation NoBidReason = 14 // Ads.cert Authentication Violation + NoBidInsufficientTime NoBidReason = 15 // Insufficient Auction Time +) diff --git a/openrtb3/openrtb3.go b/openrtb3/openrtb3.go new file mode 100644 index 0000000..e293133 --- /dev/null +++ b/openrtb3/openrtb3.go @@ -0,0 +1,60 @@ +// Package openrtb3 implements types for OpenRTB Specification v3.0 +// https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/OpenRTB%20v3.0%20FINAL.md +package openrtb3 + +// OpenRTB top-level object is the root for both request and response payloads. +// It includes versioning information and references to the Layer-4 domain model on which transactions are based. +// By default, the domain model used by OpenRTB is the Advertising Common Object Model (AdCOM). +// +// Some of these attributes are optional. +// The ver attribute, for example, indicates the OpenRTB specification version to which this payload conforms. +// This is also conveyed in Layer-1 via an HTTP header. +// Its utility here is more to assist in diagnostics by making the payload more self-documenting outside the context of a runtime transaction. +// +// The domainver attribute, however, does have runtime utility since the structures of Layer-4 objects may vary over time based on their specification versions. +// This attribute can assist in invoking the correct domain object parser or unmarshalling code. +type OpenRTB struct { + // Attribute: + // ver + // Type: + // string + // Definition: + // Version of the Layer-3 OpenRTB specification (e.g., "3.0"). + Ver string `json:"ver,omitempty"` + + // Attribute: + // domainspec + // Type: + // string; default “adcom” + // Definition: + // Identifier of the Layer-4 domain model used to define items for sale, media associated with bids, etc. + DomainSpec string `json:"domainspec,omitempty"` + + // Attribute: + // domainver + // Type: + // string; required + // Definition: + // Specification version of the Layer-4 domain model referenced in the domainspec attribute. + DomainVer string `json:"domainver"` + + // Attribute: + // request + // Type: + // object; required * + // Definition: + // Bid request container. + // * Required only for request payloads. + // Refer to Object: Request. + Request *Request `json:"request,omitempty"` + + // Attribute: + // response + // Type: + // object; required * + // Definition: + // Bid response container. + // * Required only for response payloads. + // Refer to Object: Response. + Response *Response `json:"response,omitempty"` +} diff --git a/openrtb3/openrtb3_suite_test.go b/openrtb3/openrtb3_suite_test.go new file mode 100644 index 0000000..ea12189 --- /dev/null +++ b/openrtb3/openrtb3_suite_test.go @@ -0,0 +1,13 @@ +package openrtb3_test + +import ( + "testing" + + . "github.com/onsi/ginkgo" + . "github.com/onsi/gomega" +) + +func TestOpenrtb3(t *testing.T) { + RegisterFailHandler(Fail) + RunSpecs(t, "Openrtb3 Suite") +} diff --git a/openrtb3/openrtb3_test.go b/openrtb3/openrtb3_test.go new file mode 100644 index 0000000..b9fae67 --- /dev/null +++ b/openrtb3/openrtb3_test.go @@ -0,0 +1,31 @@ +package openrtb3_test + +import ( + "encoding/json" + "io/ioutil" + "path/filepath" + + . "github.com/mxmCherry/openrtb/openrtb3" + + . "github.com/onsi/ginkgo/extensions/table" + . "github.com/onsi/gomega" +) + +var _ = DescribeTable( + "Marshaling", + func(file string) { + golden, err := ioutil.ReadFile(filepath.Join("testdata", file)) + Expect(err).NotTo(HaveOccurred()) + + v := new(Body) + Expect(json.Unmarshal(golden, v)).To(Succeed()) + + b, err := json.Marshal(v) + Expect(err).NotTo(HaveOccurred()) + + Expect(b).To(MatchJSON(golden)) + }, + + Entry("request", "request.json"), + Entry("response", "response.json"), +) diff --git a/openrtb3/request.go b/openrtb3/request.go new file mode 100644 index 0000000..dffd22f --- /dev/null +++ b/openrtb3/request.go @@ -0,0 +1,126 @@ +package openrtb3 + +import "encoding/json" + +// Request object contains a globally unique bid request ID. +// This id attribute is required as is an Item array with at least one object (i.e., at least one item for sale). +// Other attributes establish rules and restrictions that apply to all items being offered. +// This object also interfaces to Layer-4 domain objects for context such as the user, device, site or app, etc. +type Request struct { + // Attribute: + // id + // Type: + // string; required + // Definition: + // Unique ID of the bid request; provided by the exchange. + ID string `json:"id"` + + // Attribute: + // test + // Type: + // integer; default 0 + // Definition: + // Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode. + Test int8 `json:"test,omitempty"` + + // Attribute: + // tmax + // Type: + // integer + // Definition: + // Maximum time in milliseconds the exchange allows for bids to be received including Internet latency to avoid timeout. + // This value supersedes any a priori guidance from the exchange. + // If an exchange acts as an intermediary, it should decrease the outbound tmax value from what it received to account for its latency and the additional internet hop. + TMax int64 `json:"tmax,omitempty"` + + // Attribute: + // at + // Type: + // integer; default 2 + // Definition: + // Auction type, where 1 = First Price, 2 = Second Price Plus. + // Values greater than 500 can be used for exchange-specific auction types. + AT AuctionType `json:"at,omitempty"` + + // Attribute: + // cur + // Type: + // string array; default [“USD”] + // Definition: + // Array of accepted currencies for bids on this bid request using ISO-4217 alpha codes. + // Recommended if the exchange accepts multiple currencies. + // If omitted, the single currency of “USD” is assumed. + Cur []string `json:"cur,omitempty"` + + // Attribute: + // seat + // Type: + // string array + // Definition: + // Restriction list of buyer seats for bidding on this item. + // Knowledge of buyer’s customers and their seat IDs must be coordinated between parties a priori. + // Omission implies no restrictions. + Seat []string `json:"seat,omitempty"` + + // Attribute: + // wseat + // Type: + // integer; default 1 + // Definition: + // Flag that determines the restriction interpretation of the seat array, where 0 = block list, 1 = whitelist. + WSeat int8 `json:"wseat,omitempty"` + + // Attribute: + // cdata + // Type: + // string + // Definition: + // Allows bidder to retrieve data set on its behalf in the exchange’s cookie (refer to cdata in Object: Response) if supported by the exchange. + // The string must be in base85 cookie-safe characters. + CData string `json:"cdata,omitempty"` + + // Attribute: + // source + // Type: + // object + // Definition: + // A Source object that provides data about the inventory source and which entity makes the final decision + // Refer to Object: Source. + Source *Source `json:"source,omitempty"` + + // Attribute: + // item + // Type: + // object array; required + // Definition: + // Array of Item objects (at least one) that constitute the set of goods being offered for sale. + // Refer to Object: Item. + Item []Item `json:"item"` + + // Attribute: + // package + // Type: + // integer + // Definition: + // Flag to indicate if the Exchange can verify that the items offered represent all of the items available in context (e.g., all impressions on a web page, all video spots such as pre/mid/post roll) to support road-blocking, where 0 = no, 1 = yes. + Package int8 `json:"package,omitempty"` + + // Attribute: + // context + // Type: + // object; recommended + // Definition: + // Layer-4 domain object structure that provides context for the items being offered conforming to the specification and version referenced in openrtb.domainspec and openrtb.domainver. + // For AdCOM v1.x, the objects allowed here all of which are optional are one of the DistributionChannel subtypes (i.e., Site, App, or Dooh), User, Device, Regs, Restrictions, and any objects subordinate to these as specified by AdCOM. + // Dev note: + // This object is implemented as ../adcom1.RequestContext type. + Context json.RawMessage `json:"context,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional exchange-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/openrtb3/response.go b/openrtb3/response.go new file mode 100644 index 0000000..4f906aa --- /dev/null +++ b/openrtb3/response.go @@ -0,0 +1,73 @@ +package openrtb3 + +import "encoding/json" + +// Response object is the bid response object under the Openrtb root. +// Its id attribute is a reflection of the bid request ID. +// The bidid attribute is an optional response tracking ID for bidders. +// If specified, it will be available for use in substitution macros placed in markup and notification URLs. +// At least one Seatbid object is required, which contains at least one Bid for an item. +// Other attributes are optional. +// +// To express a “no-bid”, the most compact option is simply to return an empty response with HTTP 204. +// However, if the bidder wishes to convey a reason for not bidding, a Response object can be returned with just a reason code in the nbr attribute. +type Response struct { + // Attribute: + // id + // Type: + // string; required + // Definition: + // ID of the bid request to which this is a response; must match the request.id attribute. + ID string `json:"id,omitempty"` + + // Attribute: + // bidid + // Type: + // string + // Definition: + // Bidder generated response ID to assist with logging/tracking. + BidID string `json:"bidid,omitempty"` + + // Attribute: + // nbr + // Type: + // integer + // Definition: + // Reason for not bidding if applicable (see List: No-Bid Reason Codes). + // Note that while many exchanges prefer a simple HTTP 204 response to indicate a no-bid, responses indicating a reason code can be useful in debugging scenarios. + NBR NoBidReason `json:"nbr,omitempty"` + + // Attribute: + // cur + // Type: + // string; default “USD” + // Definition: + // Bid currency using ISO-4217 alpha codes. + Cur string `json:"cur,omitempty"` + + // Attribute: + // cdata + // Type: + // string + // Definition: + // Allows bidder to set data in the exchange’s cookie, which can be retrieved on bid requests (refer to cdata in Object: Request) if supported by the exchange. + // The string must be in base85 cookie-safe characters. + CData string `json:"cdata,omitempty"` + + // Attribute: + // seatbid + // Type: + // object array + // Definition: + // Array of Seatbid objects; 1+ required if a bid is to be made. + // Refer to Object: Seatbid. + SeatBid []SeatBid `json:"seatbid,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional demand source specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/openrtb3/seat_bid.go b/openrtb3/seat_bid.go new file mode 100644 index 0000000..5604201 --- /dev/null +++ b/openrtb3/seat_bid.go @@ -0,0 +1,42 @@ +package openrtb3 + +import "encoding/json" + +// SeatBid is an OpenRTB seatbid object. +// A bid response can contain multiple Seatbid objects, each on behalf of a different buyer seat and each containing one or more individual bids. +// If multiple items are presented in the request offer, the package attribute can be used to specify if a seat is willing to accept any impressions that it can win (default) or if it is interested in winning any only if it can win them all as a group. +type SeatBid struct { + // Attribute: + // seat + // Type: + // string, recommended + // Definition: + // ID of the buyer seat on whose behalf this bid is made. + Seat string `json:"seat,omitempty"` + + // Attribute: + // package + // Type: + // integer; default 0 + // Definition: + // For offers with multiple items, this flag Indicates if the bidder is willing to accept wins on a subset of bids or requires the full group as a package, where 0 = individual wins accepted; 1 = package win or loss only. + Package int8 `json:"package,omitempty"` + + // Attribute: + // bid + // Type: + // object array; required + // Definition: + // Array of 1+ Bid objects each related to an item. + // Multiple bids can relate to the same item. + // Refer to Object: Bid. + Bid []Bid `json:"bid,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional demand source specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/openrtb3/source.go b/openrtb3/source.go new file mode 100644 index 0000000..daf00cc --- /dev/null +++ b/openrtb3/source.go @@ -0,0 +1,83 @@ +package openrtb3 + +import "encoding/json" + +// Source object carries data about the source of the transaction including the unique ID of the transaction itself, source authentication information, and the chain of custody. +// +// NOTE: Attributes ds, dsmap, cert, and digest support digitally signed bid requests as defined by the Ads.cert: Signed Bid Requests specification. +// As the Ads.cert specification is still in its BETA state, these attributes should be considered to be in a similar state. +type Source struct { + // Attribute: + // tid + // Type: + // string; recommended + // Definition: + // Transaction ID that must be common across all participants throughout the entire supply chain of this transaction. + // This also applies across all participating exchanges in a header bidding or similar publisher-centric broadcast scenario. + TID string `json:"tid,omitempty"` + + // Attribute: + // ts + // Type: + // integer; recommended + // Definition: + // Timestamp when the request originated at the beginning of the supply chain in Unix format (i.e., milliseconds since the epoch). + // This value must be held as immutable throughout subsequent intermediaries. + TS int64 `json:"ts,omitempty"` + + // Attribute: + // ds + // Type: + // string; recommended + // Definition: + // Digital signature used to authenticate the origin of this request computed by the publisher or its trusted agent from a digest string composed of a set of immutable attributes found in the bid request. + // Refer to Section “Inventory Authentication” for more details. + DS string `json:"ds,omitempty"` + + // Attribute: + // dsmap + // Type: + // string + // Definition: + // An ordered list of identifiers that indicates the attributes used to create the digest. + // This map provides the essential instructions for recreating the digest from the bid request, which is a necessary step in validating the digital signature in the ds attribute. + // Refer to Section “Inventory Authentication” for more details. + DSMap string `json:"dsmap,omitempty"` + + // Attribute: + // cert + // Type: + // string; recommended + // Definition: + // File name of the certificate (i.e., the public key) used to generate the digital signature in the ds attribute. + // Refer to Section “Inventory Authentication” for more details. + Cert string `json:"cert,omitempty"` + + // Attribute: + // digest + // Type: + // string + // Definition: + // The full digest string that was signed to produce the digital signature. + // Refer to Section “Inventory Authentication” for more details. + // NOTE: This is only intended for debugging purposes as needed. + // It is not intended for normal Production traffic due to the bandwidth impact. + Digest string `json:"digest,omitempty"` + + // Attribute: + // pchain + // Type: + // string + // Definition: + // Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol. + // NOTE: Authentication features in this Source object combined with the “ads.txt” specification may lead to the deprecation of this attribute. + PChain string `json:"pchain,omitempty"` + + // Attribute: + // ext + // Type: + // object + // Definition: + // Optional exchange-specific extensions. + Ext json.RawMessage `json:"ext,omitempty"` +} diff --git a/openrtb3/testdata/README.md b/openrtb3/testdata/README.md new file mode 100644 index 0000000..dd7db19 --- /dev/null +++ b/openrtb3/testdata/README.md @@ -0,0 +1,5 @@ +# testdata + +JSON examples copied from [OpenRTB](https://iabtechlab.com/standards/openrtb/) [3.0](https://github.com/InteractiveAdvertisingBureau/openrtb) spec - section "Examples". + +Some empty/zero attributes were omited (not copied) because of [encoding/json](https://golang.org/pkg/encoding/json/) `omitempty` and [gomega.MatchJSON(...)](http://onsi.github.io/gomega/#matchjsonjson-interface). diff --git a/openrtb3/testdata/request.json b/openrtb3/testdata/request.json new file mode 100644 index 0000000..f83d3e2 --- /dev/null +++ b/openrtb3/testdata/request.json @@ -0,0 +1,58 @@ +{ + "openrtb": { + "ver": "3.0", + "domainspec": "adcom", + "domainver": "1.0", + "request": { + "id": "0123456789ABCDEF", + "tmax": 150, + "at": 2, + "cur": [ + "USD", + "EUR" + ], + "source": { + "tid": "FEDCBA9876543210", + "ts": 1541796182157, + "ds": "AE23865DF890100BECCD76579DD4769DBBA9812CEE8ED90BF", + "dsmap": "...", + "cert": "ads-cert.1.txt", + "pchain": "..." + }, + "item": [ + { + "id": "1", + "qty": 1, + "deal": [ + { + "id": "1234", + "flr": 1.5 + } + ], + "spec": { + "placement": { + "dummy": "dummy" + } + } + } + ], + "context": { + "site": { + "dummy": "dummy" + }, + "user": { + "dummy": "dummy" + }, + "device": { + "dummy": "dummy" + }, + "regs": { + "dummy": "dummy" + }, + "restrictions": { + "dummy": "dummy" + } + } + } + } +} diff --git a/openrtb3/testdata/response.json b/openrtb3/testdata/response.json new file mode 100644 index 0000000..2e8f664 --- /dev/null +++ b/openrtb3/testdata/response.json @@ -0,0 +1,44 @@ +{ + "openrtb": { + "ver": "3.0", + "domainspec": "adcom", + "domainver": "1.0", + "response": { + "id": "0123456789ABCDEF", + "bidid": "0011223344AABBCC", + "seatbid": [ + { + "seat": "XYZ", + "bid": [ + { + "id": "yaddayadda", + "item": "1", + "deal": "1234", + "price": 1.5, + "tactic": "...", + "purl": "...", + "burl": "...", + "lurl": "...", + "mid": "...", + "macro": [ + { + "key": "TIMESTAMP", + "value": "1127987134" + }, + { + "key": "CLICKTOKEN", + "value": "A7D800F2716DB" + } + ], + "media": { + "ad": { + "dummy": "dummy" + } + } + } + ] + } + ] + } + } +} diff --git a/testdata/README.md b/testdata/README.md deleted file mode 100644 index 65049c4..0000000 --- a/testdata/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# testdata - -JSON examples copied from [OpenRTB](https://www.iab.com/guidelines/real-time-bidding-rtb-project/) [v2.5](https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf) spec - section 6. Bid Request/Response Samples. - -Some empty/zero attributes were omited (not copied) because of [encoding/json](https://golang.org/pkg/encoding/json/) `omitempty` and [gomega.MatchJSON(...)](http://onsi.github.io/gomega/#matchjsonjson-interface).