Native Parameters

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Jun 15, 2017
Version 5Show Document
  • View in full screen mode

Note: For native ad request, ensure that you send all the parameters only in HTTP POST.

All the following parameters' values should be URI encoded.

           

Parameter
Mandatory
Description
native
Yes
Native object in JSON format

Native Markup Request Object

The Native object defines the native advertising opportunity available for bid via this bid request.

                                           

Parameter
Mandatory
Description
ver
No
Version of the Native Markup version in use.
Default value: 1
layout
No but recommended
Layout ID of the native ad unit. For more information, refer the Native Layout IDs table.
adunit
No but recommended
Ad unit ID of the native ad unit. This corresponds to one of IAB Core's native ad units. For more information, refer the Native Ad Unit IDs table.
plcmtcnt
No
The number of identical placements in this Format ID. If this optional parameter is present and greater than 1, then the implication is that the bidder is submitting bids to a Generalized Second Price auction where multiple identical placements are being offered in the same content feed or stream.
Default value: 1
seq
No
Sequence number of the native ad unit. For more information, refer the Native Layout IDs table.
0 for the first ad, 1 for the second ad, and so on. This is not the sequence number of the content in the stream.
Default value: 0
assets
Yes
An array of Asset Objects. Any bid must comply with the array of elements expressed by the Exchange.
ext
No
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

Asset Object

This is the main container object for each asset requested.

                                           

Parameter
Mandatory
Description
id
Yes
Unique asset ID, assigned by exchange. Typically a counter for the array.
required
No
Set to 1 if asset is required (exchange will not accept a bid without it)
Default value: 0
title
No
Title object for title assets. Refer to the Title Object definition.
img
No
Image object for image assets. Refer to the Image Object definition.
video
No
Video object for video assets. Refer to the Video request object definition.  Note that in-stream video ads are not part of Native. Native ads may contain a video as the ad creative itself.
data
No
Data object for ratings, prices etc.  Refer to the Data Object definition.
ext
No
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

Title Object

The Title object is to be used for the title element of the Native ad.

                

Parameter
Mandatory
Description
len
Yes
Maximum length of the text in the title element.
ext
No
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

Image Object

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

                                           

Parameter
Mandatory
Description
type
No
Type ID of the image element supported by the publisher. The publisher can display this information in an appropriate format. For more information, refer the Image Asset Types table.
w
No
Width of the image in pixels.
wmin
No but recommended
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 w is included it should be considered an exact requirement.
h
No
Height of the image in pixels.
hmin
No but recommended
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 hmin is included it should be considered an exact requirement.
mimes
No
Whitelist of content MIME types supported. Popular MIME types include, but are not limited to image/jpg & image/gif. Each implementing Exchange should have their own list of supported types in the integration docs.  Refer to the Wikipedia's MIME page for more information and links to all IETF RFCs. If blank, assume all types are allowed.
ext
No
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

Video Object

The video object is to be used for all the video elements supported in the Native Ad.

                               

Parameter
Mandatory
Description
mimes
Yes
Content MIME types supported. Popular MIME types include, but are not limited to "video/x-ms-wmv" for Windows Media, and "video/x-flv" for Flash Video.
minduration
Yes
Minimum video ad duration in seconds.
maxduration
Yes
Maximum video ad duration in seconds.
protocols
Yes
An array of video protocols the publisher can accept in the bid response.  Refer to the OpenRTB 2.3 Table 6.7 Video Bid Response Protocols for a list of possible values.
ext
No
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 Object

The Data Object is to be used for all non-core elements of the native unit such as Ratings, Review Count, Stars, Download count, descriptions etc.

                       

Parameter
Mandatory
Description
type
Yes
Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format.  For more information, refer the Data Asset Types table.
len
No
Maximum length of the text in the element's response.
ext
No
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

Native Ad Bid Response Markup

           

Parameter
Mandatory
Description
native
Yes
Native object in JSON format

Native Object

The response is a JSON string with the following attributes:

                                    

Parameter
Mandatory
Description
ver
No
Version of Native Markup being used.
Default value: 1
assets
Yes
List of native ad's assets.
link
Yes
Destination Link. Refer to the Link Object definition
imptrackers[]
No
Array of impression tracking URLs, expected to return a 1x1 image or 204 response - typically only passed when using 3rd party trackers.
jstracker
No
Optional JavaScript impression tracker. Contains <script> tags to be executed at impression time where it can be supported
ext
No
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

Asset Object

This object corresponds to the Asset Object in the request.

                                                

Parameter
Mandatory
Description
id
Yes
Unique asset ID, assigned by exchange, must match one of the asset IDs in request
req
No
Set to 1 if asset is required. (bidder requires it to be displayed).
Default value: 0
title
No
Title object for title assets. Refer to the Title Object definition.
img
No
Image object for image assets. Refer to the Image Object definition.
video
No
Video object for video assets. Refer to the Video object definition.  Note that in-stream video ads are not part of Native. Native ads may contain a video as the ad creative itself.
data
No
Value object for ratings, prices etc.
link
No
Link object for call to actions. This field is to be associated to the other populated field within the object.
ext
No
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

Title Object

This object corresponds to the Title Object in the request updated with the values.

                

Parameter
Mandatory
Description
text
Yes
The text associated with the text element.
ext
No
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

Image Object

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

                          

Parameter
Mandatory
Description
url
Yes
URL of the image asset.
w
No, but recommended
Width of the image in pixels.
h
No, but recommended
Height of the image in pixels.
ext
No
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 Object

This object corresponds to the Data Object in the request updated with the values. The Data Object is to be used for all miscellaneous elements of the native unit such as Ratings, Review Count, Stars, Downloads, Price count etc.

                       

Parameter
Mandatory
Description
label
No
The optional formatted string name of the data type to be displayed.
value
Yes
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."
ext
No
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

Video Object

This object corresponds to the Video Object in the request, containing a value of a conforming VAST tag as a value.

           

Parameter
Mandatory
Description
vasttag
Yes
VAST XML

Link Object

This object is 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. When that peer object is activated (clicked), the action should take the user to the location of the link.

                          

Parameter
Mandatory
Description
url
Yes
Landing URL of the clickable link.
clicktrackers[]
No
List of third-party tracker URLs to be fired on click of the URL.
fallback
No
Fallback URL for deeplink. To be (URL) used if the URL given in clk is not supported by the device.
ext
No
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

Attachments

    Outcomes