The body of Triplelift Native request/responses follows the standard OpenRTB Dynamic Native Ads API Spec v1.2 syntax. For more information on this OpenRTB syntax, please refer to the following specification:
OpenRTB Native Ads 1.2 Specification
Any elements of the syntax that may be unique to Triplelift however will be documented below.
Native 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.
| Field | Scope | Type | Description |
|---|---|---|---|
| ver | optional | string | Version of the Native Markup in use. |
| context | recommended | integer | The context in which the ad appears. |
| plcmttype | recommended | integer | The design/format/layout of the ad unit being offered. |
| plcmtcnt | optional | integer | The number of identical placements in this Layout. |
| assets | required | array of objects | An array of Asset Objects |
| aurlsupport | optional | int | Whether the supply source / impression supports returning an assetsurl instead of an asset object. 0 or the absence of the field indicates no such support. |
| eventtrackers | recommended | array of objects | Specifies what type of event tracking is supported. |
Asset Request Objct
The main container object for each asset requested or supported by Exchange on behalf of the rendering client. Any object that is required is to be flagged as such. Only one of the {title,img,video,data} objects should be present in each object. All others should be null/absent. The id is to be unique within the AssetObject array so that the response can be aligned.\ To be more explicit, it is the ID of each asset object that maps the response to the request. So if a request for a title object is sent with id 1, then the response containing the title should have an id of 1.
| Field | Scope | Type | Description |
|---|---|---|---|
| id | required | int | Unique asset ID, assigned by exchange. Typically a counter for the array. |
| required | optional | int | Set to 1 if asset is required. |
| title | recommended | object | Title object for title assets. See TitleObject definition. |
| img | recommended | object | Image object for image assets. See ImageObject definition. |
| video | optional | object | Video object for video assets. See the Video request object definition. Note that in-stream (ie preroll, etc) video ads are not part of Native. Native ads may contain a video as the ad creative itself. |
| data | recommended | object | Data object for brand name, description, ratings, prices etc. See DataObject definition |
Title Request Object
The Title object is to be used for title element of the Native ad.
| Field | Scope | Type | Description |
|---|---|---|---|
| len | required | int | Maximum length of the text in the title element. |
Image Request Object
The Image Request object is to be used for title element of the Native ad.
| Field | Scope | Type | Description |
|---|---|---|---|
| type | required | int | 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. |
| w | optional | integer | Width of the image in pixels. |
| wmin | recommended | integer | The minimum requested width of the image in pixels. This option should be used for any rescaling of images by the client. Either w or wmin should be transmitted. If only w is included, it should be considered an exact requirement |
| h | optional | integer | Height of the image in pixels. |
| hmin | recommended | integer | The minimum requested height of the image in pixels. This option should be used for any rescaling of images by the client. Either h or hmin should be transmitted. If only h is included, it should be considered an exact requirement. |
| mimes | optional | array of strings | Allowlist of content MIME types supported. Popular MIME types include, but are not limited to “image/jpg” “image/gif”. |
Video Request Object
The video object to be used for all video elements supported in the Native Ad. This corresponds to the Video object of OpenRTB.
| Field | Scope | Type | Description |
|---|---|---|---|
| mimes | required | array of strings | 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. |
| minduration | required | integer | Minimum video ad duration in seconds. |
| maxdurations | required | integer | Maximum video ad duration in seconds. |
| protocols | required | array of integers | 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. |
| ext | optional | object | 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 |
Data Request Object
The Data Object is to be used for all non-core elements of the native unit such as Brand Name, Ratings, Review Count, Stars, Download count, descriptions etc. It is also generic for future native elements not contemplated at the time of the writing of this document. In some cases, additional recommendations are also included in the Data Asset Types table.
| Field | Scope | Type | Description |
|---|---|---|---|
| type | required | integer | Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format. See 7.4 Data Asset Types table in the OpenRTB spec for commonly used examples. |
| len | optional | integer | Maximum length of the text in the element’s response. |
Event Trackers Request Object
The event trackers object specifies the types of events the bidder can request to be tracked in the bid response, and which types of tracking are available for each event type, and is included as an array in the request.
| Field | Scope | Type | Description |
|---|---|---|---|
| event | required | integer | Type of event available for tracking. See Event Types table below. |
| methods | required | array of integers | Array of the types of tracking available for the given event. See Event Tracking Methods table below. |
Event Types
| Type ID | Name | Description |
|---|---|---|
| 1 | impression | Impression |
| 2 | viewable-mrc50 | Visible impression using MRC definition at 50% in view for 1 second |
| 3 | viewable-mrc100 | 100% in view for 1 second |
| 4 | viewable-video50 | Visible impression for video using MRC definition at 50% in view for 2 seconds |
| 500+ | exchange-specific |
Event Tracking Methods
| Type ID | Name | Description |
|---|---|---|
| 1 | img | Image-pixel tracking - URL provided will be inserted as a 1x1 pixel at the time of the event. |
| 2 | js | Javascript-based tracking - URL provided will be inserted as a js tag at the time of the event. |
| 500+ | exchange-specific |