RTB Native Ad Request Spec 1.1 & 1.0

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.0 & 1.1 so that integrating with Mobfox using native ads is a snap.

We suggest that you integrate using our RTB native Ad Request Spec 1.2

How should a Native Ad Request look like?


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

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

Example of RTB Native Bid Requests

Bid Request for a Native Ad
{
  ...
  "imp": [
    {
      "native": {
        "request": "{\"ver\":\"1.1\",\"context\":2,\"contextsubtype\":20, ...}",
        "ver": "1.2",
        "api": [3, 5],
        "battr": [1, 2, 3, 17]
      },
      ...
    }
  ],
  ...
}
Native Request 1.1
{
  "ver": "1.1",
  "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
    }
  ]
}

Which Native Request parameters do we support on Native Ad Request 1.1 & 1.0?



Object/ParameterTypeDescriptionDefault ValueRequired?
NativeAdRequestobject


verstring

Version of the Native Markup version in use.

-yes
layoutintegerThe Layout ID of the native ad unit. See the Table of Layout IDs in the Native Ad Specification 1.1.-no
adunitintegerThe Ad unit ID of the native ad unit. See the Table of Ad Unit IDs in the Native Ad Specification 1.1.-no
contextintegerThe context in which the ad appears. See the Table of Context IDs in the Native Ad Specification 1.1.-no

contextsubtype

integerA more detailed context in which the ad appears. See the Table of Context Subtype IDs in the Native Ad Specification 1.1.-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.1.-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
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.1.-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.1.-yes
lenintegerMaximum length of the text allowed.-no
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 part of RTB Bid Response, field seatbid[0].bid[0].adm as JSON-encoded string.

Note that RTB Native Bid Response 1.0 has native root inside markup (adm) field.

Example of RTB Native Bid Responses

RTB Native Bid Response 1.0
{
  "seatbid": [
    {
      "bid": [
        {
          ...
          "adm": "{\"native\":{\"assets\":[{\"id\":123,\"required\":1,\"title\":{\"text\":\"MobFox Test Ad\"}}, ... }}"
        }
      ]
    }
  ],
  ...
}
RTB Native Bid Response 1.1
{
    "seatbid": [
        {
            "bid": [
                {
                    ...
                    "adm": "{\"assets\":[{\"id\":123,\"required\":1,\"title\":{\"text\":\"MobFox Test Ad\"}}, ... }"
                }
            ]
        }
    ],
    ...
}
Native Bid Response 1.1
{
   "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"
   }
}

Which parameters do we support on Native Ad Response 1.1 & 1.0?



Object/ParameterTypeDescriptionDefault ValueRequired?
NativeAdResponseobject


verstring

Version of the Native Markup version in use.

1.1yes
assetsarray of objectsList of native ad assets-yes
linkobjectDestination link. 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 LinkObject 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.-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.-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 Object
object


textstring

The text associated with the text element.

-yes
extobjectExtension-no
Image Object




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 Object
object


vasttagstringVAST xml-yes
Data Object




labelstringThe optional formatted string name of the data type to be displayed.-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

Related pages


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