Overview
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.
The structure and contents of the Bid Response are the same as in the OpenRTB standard. The difference is in how the ad creative is returned. The native creative shall be returned as a JSON encoded string in the adm field of the Bid Object.
The native object is the top level JSON object which identifies a native response. The native object has following attributes:
| Attribute | Triplelift Required | Type | Description |
|---|---|---|---|
| ver | no; recommended | string | Version of the Native Markup version in use. Default is "1.2" |
| assets | yes | array of objects | List of native ad's assets. Required if no assetsurl |
| assetsurl | no | string | URL of an alternate source for the assets object. The expected response is a JSON object mirroring the assets object in the bis response, subject to certain requirements as specified in the individual objects |
| dcourl | no | string | URL where a dynamic creative specification may be found for populating this ad |
| link | yes | object | Destination link. This is the default link object for the ad. Individual assets can also have a link object which applies if the asset is activated (clicked) |
| imptrackers | no | array of strings | Array of impression tracking URLs, expected to return a 1x1 image or 204 response - typically only passed when using 3rd party trackers |
| jstracker | no | string | Optional JavaScript impression tracker. This is a valid HTML, JavaScript is already wrapped in <script>} |
| eventtrackers | no | array of objects | Array of tracking objects to run with the ad, in response to the declared supported methods in the request |
| privacy | no | string | If support was indicated in the request, URL of a page informing the user about the buyer's targeting activity |
| ext | no | object | Placeholder that may contain custom extension to OpenRTB |
Asset Response Object
This object corresponds to the Asset Request Object in the request. The main container object for each asset requested or supported by the Exchange on behalf of the rendering client. Only one of the title, img, video, data objects should be present in each object. The id is to be unique within the Asset Object array so that the response can be aligned.
| Attribute | Triplelift Required | Type | Description |
|---|---|---|---|
| id | no | integer | Optional if assetsurl/dcourl is being used; required if the embedded asset is being used |
| required | no | integer | Set to 1 if asset is required |
| title | no | object | Title object for title assets |
| img | no | object | Image object for image assets |
| video | no | object | Video object for video assets. Note that instream video ads are not part of Native |
| data | no | object | Data object for ratings, prices, etc. |
| link | no | object | Link object for call to actions. The link object applies if the asset item is activated (clicked) |
| ext | no | object | This object is a placeholder that may contain custom JSON extensions to OpenRTB |
Title Response Object
This object corresponds to the Title Request Object in the request. 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.
| Attribute | Triplelift Required | Type | Description |
|---|---|---|---|
| text | yes | string | The text associated with the text element |
| len | no | integer | The length of the title being provided. Required if using assetsurl/dcourl representation, optional if using embedded asset representation |
| ext | no | object | Placeholder for custom JSON extensions to OpenRTB |
Image Response Object
Corresponds to the Image Request Object in the request. The Image object to be used for all image elements of the Native ad (Icons, Main Image, etc.).
| Attribute | Triplelift Required | Type | Description |
|---|---|---|---|
| type | no | integer | Required for assetsurl or dcourl responses, not required for embedded asset responses |
| url | yes | string | URL of the image asset |
| w | no; recommended | integer | Width of the image pixels. Recommended for embedded asset responses |
| h | no; recommended | integer | Height of the image in pixels |
| ext | no | object | Placeholder for custom JSON extensions to OpenRTB |
Data Response Object
Corresponds to the Video Request Object in the request, yet containing a value of a conforming VAST tag as a value.
| Attribute | Triplelift Required | Type | Description |
|---|---|---|---|
| vasttag | yes | string | vast XML |
Video Response Object
Corresponds to the Video Request Object in the request, yet containing a value of a conforming VAST tag as a value.
| Attribute | Triplelift Required | Type | Description |
|---|---|---|---|
| vasttag | yes | string | vast XML |
Link Response Object
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.
| Attribute | Triplelift Required | Type | Description |
|---|---|---|---|
| url | yes | string | Landing URL of the clickable link |
| clicktrackers | no | array of strings | List of third-party tracker URLs to be fired on click of the URL |
| fallback | no | string | Fallback URL for deeplink. To be used if the URL given in url is not supported by the device |
| ext | no | object | Placeholder for custom JSON extensions to OpenRTB |
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.
| Attribute | Triplelift Required | Type | Description |
|---|---|---|---|
| event | yes | integer | Type of event to track |
| method | yes | integer | Type of tracking requested |
| url | no | text | The URL of the image or js |
| customdata | no | object | To be agreed individually with the exchange, an array of key value objects for custom tracking |
| ext | no | object | Placeholder for custom JSON extensions to OpenRTB |