RTB Native Ad Request Spec 1.2

This page aims to get you (the Publisher) integrated onto our RTB Ad Request API using Native Ads.

What we offer!


We offer our publishers an RTB Native API version 1.2 so that integrating with Mobfox using native ads is a snap.

How should a Native Ad Request look like?


Native Ad Request is a part of the RTB Bid Request, included as a JSON-encoded string in the field imp[0].native.request .

For more info on how to send RTB Bid Requests please see RTB Ad Request API Spec

Example of RTB Native Bid Request

Bid Request for a Native Ad
{
  ...
  "imp": [
    {
      "native": {
        "request": "{\"ver\":\"1.2\",\"context\":2,\"contextsubtype\":20, ...}",
        "ver": "1.2",
        "api": [3, 5],
        "battr": [1, 2, 3, 17]
      },
      ...
    }
  ],
  ...
}
Native Request 1.2
{
  "ver": "1.2",
  "context": 2,
  "contextsubtype": 20,
  "plcmttype": 1,
  "plcmtcnt": 1,
  "seq": 0,
  "assets": [
    {
      "id": 123,
      "required": 1,
      "title": {
        "len": 140
      }
    },
    {
      "id": 128,
      "img": {
        "hmin": 627,
        "type": 3,
        "wmin": 836
      },
      "required": 0
    },
    {
      "id": 124,
      "img": {
        "hmin": 50,
        "type": 1,
        "wmin": 50
      },
      "required": 1
    },
    {
      "data": {
        "len": 25,
        "type": 1
      },
      "id": 126,
      "required": 1
    },
    {
      "data": {
        "len": 140,
        "type": 2
      },
      "id": 127,
      "required": 1
    }
  ],
  "eventtrackers": [
     {
        "event": 1,
        "methods": [1,2]
     }
  ]
}

Which Native Request parameters do we support on Native Ad Request 1.2?



Object/ParameterTypeDescriptionDefault ValueRequired?
NativeAdRequestobject


verstring

Version of the Native Markup version in use.

-yes
contextintegerThe context in which the ad appears. See the Table of Context IDs in the Native Ad Specification 1.2.-no

contextsubtype

integerA more detailed context in which the ad appears. See the Table of Context Subtype IDs in the Native Ad Specification 1.2.-no

plcmttype

integerThe design/format/layout of the ad unit being offered. See the Table of Placement Type IDs in the Native Ad Specification 1.2.-no

plcmtcnt

integerSupport only default value or empty, otherwise validation error. Multi placement bid requests are not supported.1no
seqintegerSupport only default value or empty, otherwise validation error. Multi placement bid requests are not supported.0no
assetsarray of objectsAn array of Asset Objects.-yes

aurlsupport

integerWhether the supply source / impression supports returning an assetsurl instead of an asset object. 0 or the absence of the field indicates no such support.0no
durlsupportintegerWhether the supply source / impression supports returning a dco url instead of an asset object. 0 or the absence of the field indicates no such support.0no

eventtrackers

array of objects

Specifies what type of event objects tracking is supported - described below
We require at least one image impression tracker (event=1 with methods=[1,...])
Note: a missing/empty object will indicate that all event tracker types are supported.

-no
privacyintegerSet to 1 when the native ad supports buyer-specific privacy notice. Set to 0 (or field absent) when the native ad doesn’t support custom privacy links or if support is unknown.0no
extobjectExtension-no
Asset Object
object


NOTE: 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 it can be used in the response to align items.
idintegerUnique asset ID. Typically a counter for the array.-yes
requiredinteger= 0 if asset is optional
= 1 if asset is required in the response
0no
titleobjectA Title Asset (described below)-no
imgobjectAn Image Asset (described below)-no
videoobjectA Video Asset (described below)-no
dataobjectA Data Asset (described below), for sponsored message, description, ratings, likes, etc.-no
extobjectExtension-no

Title Object

object


lenintegerMaximum length of the text in the title element.
Recommended values: 25, 90, or 140.
-yes
extobjectExtension-no
Image Object




typeintegerType ID of the image element supported by the publisher. The publisher can display this information in an appropriate format. See the Table Image Asset Types in the Native Ad Specification 1.2.-no
wintegerWidth of the image in pixels.-no
wminintegerThe minimum requested image width in pixels.-no
hintegerHeight of the image in pixels.-no
hminintegerThe minimum requested image height in pixels.-no
mimesarray of stringsWhitelist of mime types supported. 

Popular MIME types include, but are not limited to “image/jpg”, “image/gif”.

If blank then all types are allowed.

all types allowedno
extobjectExtension-no
Video Object
object


mimesarray of stringsList of supported content MIME types.-yes
mindurationintegerMinimum video ad duration in seconds.-yes
maxdurationintegerMaximum video ad duration in seconds.-yes
protocolsarray of integersSupported video protocols. Refer to List 5.8 in the OpenRTB documentation.-yes
extobjectExtension-no
Data Object
object


typeintegerType ID of the element supported by the publisher. For commonly used examples see the Data Asset Types table in the Native Ad Specification 1.2.-yes
lenintegerMaximum length of the text allowed.-no
extobjectExtension-no
Event Trackers Object
object


eventintegerType of event available for tracking. See Event Types table in the Native Ad Specification 1.2.-yes
methodsarray of integersArray of the types of tracking available for the given event. See Event Tracking Methods table in the Native Ad Specification 1.2.-yes
extobjectExtension-no

What known limitations exist?


  1. Multi placement bid requests are not supported

    See more info in table above.

How should a Native Ad Response look like?


Native Ad Response is a part of the RTB Bid Response, included as a JSON-encoded string in the field seatbid[0].bid[0].adm

Example of RTB Native Bid Response

RTB Native Bid Response
{
    "seatbid": [
        {
            "bid": [
                {
                    ...
                    "adm": "{\"assets\":[{\"id\":123,\"required\":1,\"title\":{\"text\":\"MobFox Test Ad\"}}, ... }"
                }
            ]
        }
    ],
    ...
}
Native Bid Response 1.2
{
   "assets": [
      {
         "id": 123,
         "required": 1,
         "title": {
            "text": "MobFox Test Ad"
         }
      },
      {
         "id": 128,
         "img": {
            "h": 627,
            "url": "https://creative1cdn.mobfox.com/mftext/1200x627/315C93/fff?text=MobFoxTestAd",
            "w": 1200
         },
         "required": 0
      },
      {
         "id": 124,
         "img": {
            "h": 50,
            "url": "https://creative1cdn.mobfox.com/mftext/80x80/315C93/fff?text=MobFoxTestAd",
            "w": 50
         },
         "required": 1
      },
      {
         "data": {
            "value": "MobFox test description"
         },
         "id": 126,
         "required": 1
      },
      {
         "data": {
            "value": "MobFox test ad description"
         },
         "id": 127,
         "required": 1
      },
      {
         "data": {
            "value": "Sponsored content"
         },
         "id": 129,
         "required": 0
      }
   ],
   "link": {
      "url": "http://some-url.com"
   },
   "eventtrackers": [
      {
         "event": 1,
         "method": 1,
         "url": "http://some-imp-tracker-url.com"
      }
   ]
}

Which parameters do we support on Native Ad Response 1.2 ?



Object/ParameterTypeDescriptionDefault ValueRequired?
NativeAdResponseobject


verstring

Version of the Native Markup version in use.

1.2no
assetsarray of objectsList of native ad assets.  Required if no assetsurl.-yes if asseturl is  empty

assetsurl

string

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.

-no

dcourl

stringURL where a dynamic creative specification may be found for populating this ad, per the Dynamic Content Ads Specification.-no
linkobject

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. See Link Object Definition

-yes
imptrackersarray of stringsArray 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 event trackers.
-no
jstrackerstringOptional 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 event trackers.
-no

eventtrackers

array of objectsArray 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. See definition.-no
extobjectExtension-no
Asset Objectobject


NOTE: 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 it can be used in the response validation.
idintegerUnique asset ID, must match one of the asset IDs in request.-yes
requiredintegerSet to 1 if asset is required. (bidder requires it to be displayed).0no
titleobjectTitle object for title assets. See TitleObject definition.-no
imgobjectImage object for image assets. See ImageObject definition.-no
videoobject

Video object for video assets. See Video response object definition.

-no
dataobject

Data object for ratings, prices etc. See Data Object definition.

-no
linkobject

Link object for call to actions. See Link Object definition.

-no
extobjectExtension-no
Title Asset
object


textstring

The text associated with the text element.

-yes
leninteger

The length of the title being provided. Required if using assetsurl/dcourl representation, optional if using embedded asset representation.

-no
extobjectExtension-no
Image Asset
object


typeintegerRequired for assetsurl or dcourl responses, not required for embedded asset responses. The type of image element being submitted from the Image Asset Types table in the Native Ad Specification 1.2.-no
urlstring

URL of the image asset.

-yes
winteger

Width of the image in pixels.

-no
hinteger

Height of the image in pixels.

-no
extobjectExtension-no
Video Asset
object


vasttagstringVAST xml-yes
Data Asset
object


typeintegerRequired for assetsurl/dcourl responses, not required for embedded asset responses. The type of data element being submitted from the Data Asset Types table in the Native Ad Specification 1.2.-no
leninteger

Required for assetsurl/dcourl responses, not required for embedded asset responses. The length of the data element being submitted.

-no
valuestring

The formatted string of data to be displayed.

-yes
extobjectExtension-no
Link Object
object


urlstring

Landing URL of the clickable link.

-yes
clicktrackersarray of strings

List of third-party tracker URLs to be fired on click of the URL.

-no

fallback

string

Fallback URL for deeplink. To be used if the URL given in url is not supported by the device.

-no

ext

objectExtension-no
Event Tracker Object
object


eventintegerType of event to track. See Event Types table in the Native Ad Specification 1.2.-yes
methodintegerType of tracking requested. See Event Tracking Methods table in the Native Ad Specification 1.2.-yes
urlstringThe URL of the image or js. Required for image or js, optional for custom.-yes
for image or js
customdataobject

To be agreed individually with the exchange, an array of key:value objects for custom tracking

-no
extobjectExtension-no

Related pages


Link to pages, which might also be interesting for you: