The Ad-serving API will return a json text payload to the user formatted using the open native RTB 1.2 spec. The structure of the response will have the placements array list at the highest level, and will contain all placements that have valid ads within the array list.
Note that the url used in the request must have an entry in the Nativo system and there can be multiple placements each with there own ad. See the below sample response from the Ad Serving API:
JSON
{ "placements": [ { "id": 1010101, "ad": { "id": 110101, "assets": [ { "id": 0, "required": 1, "title": { "text": "Clickout Ad - External" } }, { "id": 3, "required": 1, "img": { "url": "http://ntvcld-a.akamaihd.net/image/upload/w_300,h_187,c_fill,f_auto,fl_lossy,e_sharpen:70/assets/428B520D26664719B37C7A9065D696EB.png", "w": 300, "h": 187, "type": 3 } }, { "id": 2, "required": 0, "img": { "url": "http://ntvassets-a.akamaihd.net/AFAC092FB95A4FE3ADCB4E9F66ECBAC8.png", "w": 0, "h": 0, "type": 2 } }, { "id": 6, "required": 1, "data": { "value": "This redirects to an external page, should open in a new tab! clickout icon must be added.", "type": 2, "len": 90 } }, { "id": 4, "required": 0, "data": { "value": "Nativo - Ad Server QA", "type": 1, "len": 21 } }, { "id": 8, "required": 0, "link": { "url": "http://www.nativo.com", "clicktrackers": [] } } ], "eventtrackers": [ { "event": 1, "method": 1, "url": "http://jadserve.postrelease.com/trk.gif?ntv_at=46&ntv_ui=76cb631a-c296-4f83-a5d5-741e826bacbd&ntv_a=LGwCApf4JAm9wPA&ntv_fl=4Uhuz_34AJG_8FAzLMjiGP7nuYBnq5dAzdRjIxwMVhPX42SQ-aIgTLEHuBlnQn3UClAOqdiFO4AJKi1zSp2koSFoUfJBIlfNlBawVrGeGLgfABiqIS9BcCqO0tBwW8E13KD3tSOqf606jW9-TJ0aJ5D7Xrtk88MYLJr15sN3hV0EsSI4p0X7q5-vUYVCnox65c-LGiMWNJCkkbt9GDySH5MPOp614pzrXOWwzjLFpkvxR0HoVoz3ZE7Y37-qnMCLKcxHrnWvkl5Kg-qGbYmP-WBTvnMTD9soouPVzKKj_gE=&ord=882163188&ntv_ht=dN51YwA" }, { "event": 2, "method": 1, "url": "http://jadserve.postrelease.com/trk.gif?ntv_at=47&ntv_ui=76cb631a-c296-4f83-a5d5-741e826bacbd&ntv_a=LGwCApf4JAm9wPA&ntv_fl=4Uhuz_34AJG_8FAzLMjiGP7nuYBnq5dAzdRjIxwMVhPX42SQ-aIgTLEHuBlnQn3UClAOqdiFO4AJKi1zSp2koSFoUfJBIlfNlBawVrGeGLgfABiqIS9BcCqO0tBwW8E13KD3tSOqf606jW9-TJ0aJ5D7Xrtk88MYLJr15sN3hV0EsSI4p0X7q5-vUYVCnox65c-LGiMWNJCkkbt9GDySH5MPOp614pzrXOWwzjLFpkvxR0HoVoz3ZE7Y37-qnMCLKcxHrnWvkl5Kg-qGbYmP-WBTvnMTD9soouPVzKKj_gE=&ord=-207713685&ntv_ht=dN51YwA" }, { "event": 2, "method": 1, "url": "http://jadserve.postrelease.com/trk.gif?ntv_at=28&ntv_ui=76cb631a-c296-4f83-a5d5-741e826bacbd&ntv_a=LGwCApf4JAm9wPA&ntv_fl=4Uhuz_34AJG_8FAzLMjiGP7nuYBnq5dAzdRjIxwMVhPX42SQ-aIgTLEHuBlnQn3UClAOqdiFO4AJKi1zSp2koSFoUfJBIlfNlBawVrGeGLgfABiqIS9BcCqO0tBwW8E13KD3tSOqf606jW9-TJ0aJ5D7Xrtk88MYLJr15sN3hV0EsSI4p0X7q5-vUYVCnox65c-LGiMWNJCkkbt9GDySH5MPOp614pzrXOWwzjLFpkvxR0HoVoz3ZE7Y37-qnMCLKcxHrnWvkl5Kg-qGbYmP-WBTvnMTD9soouPVzKKj_gE=&ord=-838526188&ntv_ht=dN51YwA" } ] } } ], "user": { "id": "5e0e1bb1-9609-4b14-ade5-1879ecfd5a4f" } }Primary Json Objects
Name | Description | Format |
Placements | Describes the placement(s) on the page given the url in the request | Array |
Ad | Describes an ad on from within a placement | Object |
Assets | Describes the individual parts of ad used in the rendering of the ad | Object |
EventTrackers | Defines trackers and tracking method for an ad | Array |
User | Defines a users data this include the visitor id | Object |
Assets are objects which define a single piece of an ad. for Example the following code snippet describes a Title for a display ad.
JSON
{ "id": 0, "required": 1, "title": { "text": "Clickout Ad - External" } }Asset Object
Name | Description | Format | Example |
Id | Defines the data type of the asset object | Integer | Title: 0 |
required | Defines if the object is required for rendering | Boolean |
|
img | Defines an object which contains the details of an image. This includes a url to the image, height, width and an image asset type. | Object |
|
link | Used for call to action assets as a part of an ad. | Object |
|
data | This object contains miscellaneous elements of a native ad unit such as rating, like and description. | Object |
|
Image Object
Field | Type | Description |
url | String | the image url |
w | Integer | the width size of the image in pixels |
h | Integer | The Height size of the image in pixels |
type | Integer | the image asset type |
Image Asset types
Type ID | Name | Description | Example |
1 | Advertiser Logo | Advertiser Logo add to brand recognition and improve the aesthetics on ad units. |
|
3 | Preview | Image use for previewing the ad |
|
Event Tracker Object
Field | Type | Description |
event | integer | Type of event |
method | Integer | Method of firing tracking event |
url | String | contains either a url defining a tracking pixel or a java script tag which will be used for tracking an event |
Event Tracking types
Type ID | Name | Description |
1 | Impression | Records a standard impression when the unit is rendered |
2 | viewable-mrc50 | Visible impression where the ad unit is 50% in view for 1 second |
3 | viewable-mrc100 | Ad unit must be 100% view for 1 second |
📘
Event Tracking
Note: Two event trackers can share the same event, this means that the trackers are fired at the same time for that event type. for Example looking at the above json you can see that under the EventTrackers object two trackers have the same event, event 2 viewable-mrc50 this mean that once the ad unit has been scrolled to 50% in view for 1 second the trackers both trackers which contain the event 2 should fire.
Event tracking method types
Type ID | Type | Description |
1 | img | Image pixel tracking url is fired as 1x1 image pixel at the time of the event. |
2 | js | Javascript based tracker url is fired as a part of a javascript tag at the time of the event. |
📘
Methods of Firing Trackers
There are two common method of firing tracking in HTML
Image pixel to fire an image pixel from an HTML context you normally create a 1x1 image in an HTML document and set the image source with a url request to your tracking server and finally append the image to the page body.
JavaScript uses a pre written javascript statement to firing tracking this can take the form of a javascript file wrapped in a javascript tag or a direct javascript statement.
Link Object
Field | Type | Description |
url | String | Landing page url of the clickable link |
clicktrackers | Array of Strings | A list of third party tracker URLs |
Data Object
Field | Type | Description |
type | Integer | The type of data define in object |
len | Integer | The length of the data |
value | String | Formatted string of data to be show to the user. |
User Object
Field | Type | Description |
id | String | id defines the users cookie id and is use to identify the user. If the parameter visitor_id is used in the the request the API will respect the value of the data enter and return that value as the id. If no value is entered a value will automatically be generated and return in this field. |