response

package
Version: v15.0.1 Latest Latest
Warning

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

Go to latest
Published: Apr 28, 2021 License: Unlicense Imports: 2 Imported by: 4

README

native1/response GoDoc

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

Documentation

Overview

Package response provides OpenRTB Native 1.2 response types (section "5 Native Ad Response Markup Details")

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Int64Ptr

func Int64Ptr(n int64) *int64

Int64Ptr returns pointer to passed argument.

Types

type Asset

type Asset struct {
	// Field:
	//   id
	// Scope:
	//   optional
	// Type:
	//   int
	// Description:
	//   Optional if assetsurl/dcourl is being used; required if embedded asset is being used.
	ID *int64 `json:"id,omitempty"`

	// Field:
	//   required
	// Scope:
	//   optional
	// Type:
	//   int
	// Default:
	//   0
	// Description:
	//   Set to 1 if asset is required. (bidder requires it to be displayed).
	Required int8 `json:"required,omitempty"`

	// Field:
	//   title
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   Title object for title assets.
	//   Asset object may contain only one of title, img, data or video.
	Title *Title `json:"title,omitempty"`

	// Field:
	//   img
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   Image object for image assets.
	//   Asset object may contain only one of title, img, data or video.
	Img *Image `json:"img,omitempty"`

	// Field:
	//   video
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   Video object for video assets. See Video response object definition.
	//   Note that in-stream video ads are not part of Native.
	//   Native ads may contain a video as the ad creative itself.
	//   Asset object may contain only one of title, img, data or video.
	Video *Video `json:"video,omitempty"`

	// Field:
	//   data
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   Data object for ratings, prices etc.
	//   Asset object may contain only one of title, img, data or video.
	Data *Data `json:"data,omitempty"`

	// Field:
	//   link
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   Link object for call to actions. The link object applies if the asset item is activated (clicked).
	//   If there is no link object on the asset, the parent link object on the bid response applies.
	Link *Link `json:"link,omitempty"`

	// Field:
	//   ext
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification
	//   Bidders are encouraged not to use asset.ext for exchanging text assets.
	//   Use data.ext with custom type instead.
	Ext json.RawMessage `json:"ext,omitempty"`
}

5.2 Object: Asset

Corresponds to the Asset Object in the request. The main container object for each asset requested or supported by Exchange on behalf of the rendering client. Any object that is required is to be flagged as such. Only one of the {title,img,video,data} objects should be present in each object. All others should be null/absent. The id is to be unique within the AssetObject array so that the response can be aligned.

type Data

type Data struct {
	// Field:
	//   type
	// Scope:
	//   optional
	// Type:
	//   integer
	// 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 native1.DataAssetType `json:"type,omitempty"`

	// Field:
	//   len
	// Scope:
	//   optional
	// Type:
	//   integer
	// Description:
	//   Required for assetsurl/dcourl responses, not required for embedded asset responses.
	//   The length of the data element being submitted.
	//   Where applicable, must comply with the recommended maximum lengths in the Data Asset Types table.
	Len int64 `json:"len,omitempty"`

	// Field:
	//   label
	// Scope:
	//   optional in 1.1, deprecated/removed in 1.2
	// Type:
	//   string
	// Description:
	//   The optional formatted string name of the data type to be displayed.
	Label string `json:"label,omitempty"`

	// Field:
	//   value
	// Scope:
	//   required
	// Type:
	//   string
	// Description:
	//   The formatted string of data to be displayed.
	//   Can contain a formatted value such as "5 stars" or "$10" or "3.4 stars out of 5".
	Value string `json:"value"`

	// Field:
	//   ext
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification
	Ext json.RawMessage `json:"ext,omitempty"`
}

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

type EventTracker struct {
	// Field:
	//   event
	// Scope:
	//   required
	// Type:
	//   integer
	// Description:
	//   Type of event to track.
	//   See Event Types table.
	Event native1.EventType `json:"event"`

	// Field:
	//   method
	// Scope:
	//   required
	// Type:
	//   integer
	// Description:
	//   Type of tracking requested
	//   See Event Tracking Methods table.
	Method native1.EventTrackingMethod `json:"method"`

	// Field:
	//   url
	// Scope:
	//   optional
	// Type:
	//   text
	// Description:
	//   The URL of the image or js.
	//   Required for image or js, optional for custom.
	URL string `json:"url,omitempty"`

	// Field:
	//   customdata
	// Scope:
	//   optional
	// Type:
	//   object containing key:value pairs
	// Description:
	//   To be agreed individually with the exchange, an array of key:value objects for custom tracking, for example the account number of the DSP with a tracking company.
	//   IE {“accountnumber”:”123”}
	// Dev note:
	//   - type is a key-value object (not specified if value is string-only)
	//   - descriptions says "an array of key:value objects" (???)
	CustomData json.RawMessage `json:"customdata,omitempty"`

	// Field:
	//   ext
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification
	Ext json.RawMessage `json:"ext,omitempty"`
}

5.8 Event Tracker Response Object

The event trackers response is an array of objects and specifies the types of events the bidder wishes to track and the URLs/information to track them. Bidder must only respond with methods indicated as available in the request. Note that most javascript trackers expect to be loaded at impression time, so it’s not generally recommended for the buyer to respond with javascript trackers on other events, but the appropriateness of this is up to each buyer.

type Image

type Image struct {
	// Field:
	//   type
	// Scope:
	//   optional
	// Type:
	//   integer
	// 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 native1.ImageAssetType `json:"type,omitempty"`

	// Field:
	//   url
	// Scope:
	//   required
	// Type:
	//   string
	// Description:
	//   URL of the image asset
	URL string `json:"url"`

	// Field:
	//   w
	// Scope:
	//   recommended
	// Type:
	//   int
	// Description:
	//   Width of the image in pixels.
	//   Recommended for embedded asset responses.
	//   Required for assetsurl/dcourlresponses if multiple assets of same type submitted.
	W int64 `json:"w,omitempty"`

	// Field:
	//   h
	// Scope:
	//   recommended
	// Type:
	//   int
	// Description:
	//   Height of the image in pixels.
	//   Recommended for embedded asset responses.
	//   Required for assetsurl/dcourl responses if multiple assets of same type submitted.
	H int64 `json:"h,omitempty"`

	// Field:
	//   ext
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification
	Ext json.RawMessage `json:"ext,omitempty"`
}

5.4 Object: Image

Corresponds to the Image Object in the request. The Image object to be used for all image elements of the Native ad such as Icons, Main Image, etc.

It is recommended that if assetsurl/dcourl is being used rather than embedded assets, that an image of each recommended aspect ratio (per the Image Types table) be provided forimage type 3.

type Link struct {
	// Field:
	//   url
	// Scope:
	//   required
	// Type:
	//   string
	// Description:
	//   Landing URL of the clickable link.
	URL string `json:"url"`

	// Field:
	//   clicktrackers
	// Scope:
	//   optional
	// Type:
	//   string array
	// Description:
	//   List of third-party tracker URLs to be fired on click of the URL.
	ClickTrackers []string `json:"clicktrackers,omitempty"`

	// Field:
	//   fallback
	// Scope:
	//   optional
	// Type:
	//   string
	// Description:
	//   Fallback URL for deeplink.
	//   To be used if the URL given in url is not supported by the device.
	Fallback string `json:"fallback,omitempty"`

	// Field:
	//   ext
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification
	Ext json.RawMessage `json:"ext,omitempty"`
}

5.7 Object: Link

Used for ‘call to action’ assets, or other links from the Native ad. This Object should be associated to its peer object in the parent Asset Object or as the master link in the top level Native Ad response object. When that peer object is activated (clicked) the action should take the user to the location of the link.

type Response

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

	// Field:
	//   assets
	// Scope:
	//   recommended
	// Type:
	//   object array
	// Description:
	//   List of native1 ad’s assets.
	//   Required if no assetsurl.
	//   Recommended as fallback even if assetsurl is provided.
	Assets []Asset `json:"assets,omitempty"`

	// Field:
	//   assetsurl
	// Scope:
	//   optional
	// Type:
	//   string
	// Description:
	//   URL of an alternate source for the assets object.
	//   The expected response is a JSON object mirroring the assets object in the bid response, subject to certain requirements as specified in the individual objects.
	//   Where present, overrides the asset object in the response.
	//   The provided “assetsurl” or “dcourl” should be expected to provide a valid response when called in any context, including importantly the brand name and example thumbnails and headlines (to use for reporting, blacklisting, etc), but it is understood the final actual call should come from the client device from which the ad will be rendered to give the buyer the benefit of the cookies and header data available in that context.
	AssetsURL string `json:"assetsurl,omitempty"`

	// Field:
	//   dcourl
	// Scope:
	//   optional
	// Type:
	//   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 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"`

	// Field:
	//   link
	// Scope:
	//   required
	// Type:
	//   object
	// Description:
	//   Destination Link.
	//   This is default link object for the ad.
	//   Individual assets can also have a link object which applies if the asset is activated(clicked).
	//   If the asset doesn’t have a link object, the parent link object applies.
	Link Link `json:"link"`

	// Field:
	//   imptrackers
	// Scope:
	//   optional
	// Type:
	//   string array
	// Description:
	//   Array of impression tracking URLs, expected to return a 1x1 image or 204 response - typically only passed when using 3rd party trackers.
	//   To be deprecated - replaced with eventtrackers.
	ImpTrackers []string `json:"imptrackers,omitempty"`

	// Field:
	//   jstracker
	// Scope:
	//   optional
	// Type:
	//   string
	// Description:
	//   Optional JavaScript impression tracker.
	//   This is a valid HTML, Javascript is already wrapped in <script> tags.
	//   It should be executed at impression time where it can be supported.
	//   To be deprecated - replaced with eventtrackers.
	JSTracker string `json:"jstracker,omitempty"`

	// Field:
	//   eventtrackers
	// Scope:
	//   optional
	// Type:
	//   Array of objects
	// Description:
	//   Array of tracking objects to run with the ad, in response to the declared supported methods in the request.
	//   Replaces imptrackers and jstracker, to be deprecated.
	EventTrackers []EventTracker `json:"eventtrackers,omitempty"`

	// Field:
	//   privacy
	// Scope:
	//   optional
	// Type:
	//   string
	// Description:
	//   If support was indicated in the request, URL of a page informing the user about the buyer’s targeting activity.
	Privacy string `json:"privacy,omitempty"`

	// Field:
	//   ext
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification
	Ext json.RawMessage `json:"ext,omitempty"`
}

5.1 Object: Response

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.

In the normal embedded response, certain attributes of the response are assumed based on matching the ID of the asset object in the response to the ID of the asset object in the request. Since the asset response will not be reading the asset request directly in this implementation, that information is added as option in the below object definitions and marked for that use case.

It is also recommended that where the standard specifies multiple options for an element, that all options be provided. IE all 4 supported thumbnail aspect ratios and all 3 supported title lengths.

The ID component of the asset responses can be omitted.

Note that this change to provide the metadata description of the asset in the response, rather than using the asset ID to implicitly specify that, may be reflected into the inline version of responses in a future version to align the two methods of replying. Making that change now would break backwards compatibility of the inline response mechanism.

type Title

type Title struct {
	// Field:
	//   text
	// Scope:
	//   required
	// Type:
	//   string
	// Description:
	//   The text associated with the text element.
	Text string `json:"text"`

	// Field:
	//   len
	// Scope:
	//   optional
	// Type:
	//   integer
	// Description:
	//   The length of the title being provided.
	//   Required if using assetsurl/dcourl representation, optional if using embedded asset representation.
	Len int64 `json:"len,omitempty"`

	// Field:
	//   ext
	// Scope:
	//   optional
	// Type:
	//   object
	// Description:
	//   This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification
	Ext json.RawMessage `json:"ext,omitempty"`
}

5.3 Object: Title

Corresponds to the Title Object in the request, with the value filled in.

If using assetsurl or dcourl response rather than embedded asset response, it is recommended that three title objects be provided, the length of each of which is less than or equal to the three recommended maximum title lengths (25,90,140).

type Video

type Video struct {
	// Field:
	//   vasttag
	// Scope:
	//   required
	// Type:
	//   string
	// Description:
	//   VAST XML
	VASTTag string `json:"vasttag"`
}

5.6 Object: Video

Corresponds to the Video Object in the request, yet containing a value of a conforming VAST tag as a value.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL