OpenRTB 2.1 - PubMatic Extensions

Document created by pubmatic-archivist on Mar 27, 2017Last modified by pubmatic-archivist on Sep 16, 2017
Version 11Show Document
  • View in full screen mode

Introduction

This document describes what features of the OpenRTB PubMatic supports and limitations. The latest OpenRTB 2.1 specifications are available at http://www.iab.net/rtbproject. This document is designed to be used in conjunction with the OpenRTB 2.1 specifications.

Version

PubMatic supports the OpenRTB version 2.1 subject to the following limitations explicitly mentioned below.

Limitations

1.Win notification will not be supported.

2.Ad Markup must be sent by the DSP directly within the bid response.

Note: None of the above missing features/attributes are mandatory or recommended.

Other Details

1. bid.tmax, that is, the maximum time for response will be 100 ms. This will not be sent in the bid request (for saving bandwidth).

2. Regarding the user.geo object, the information will be filled only if it is passed by the Publisher.

3. Demand partners must send the following parameters in the bid response; otherwise such a bid will not be included in the auction:

  • adomain containing the advertiser's domain
  • cid containing the campaign ID in the DSP's system
  • crid containing the creative ID in the DSP's system used for reporting content issues or defects
  • seat containing the ID of the bidder seat on whose behalf this bid is made
  • iurl containing the sample image URL (without cache busting) for content checking.
  • attr containing the array of creative attributes

4. Supported currencies: USD, JPY, EUR, GBP, CAD, AUD, SEK, CHF, CZK, DKK, BRL, NZD.

5. To target the tablet-specific impressions, demand partners should check for the devicetype parameter with value as 5 and then fall-back to devicetype parameter with value as 1

Note: PubMatic recommends to use "bcat", 'bdav', "battr" and "bidfloor" parameter whenever sent in a bid request.

Extensions

Device ID Parameter:  device.ext 

Type and value of visitor's device's unique ID. Possible options are:

Note: Only one of the following IDs will be present in the ext object.

Device ID Hash Type Parameter: device.ext.hash parameter

Type of algorithm used for hashing the device identifier provided in the above-mentioned parameter. Possible values are:

  • 0 - Unknown
  • 1 - Raw
  • 2 - SHA1
  • 3 - MD5

AdTruth Parameter: device.ext.adtruth parameter

PubMatic supports the AdTruth device recognition technology which provides a privacy-safe cookie alternative across desktop, mobile web and mobile apps.

This parameter packages the multiple attributes that demand partners will require to utilize the AdTruth DeviceInsight identifier.  The attributes included in the json package are:

  • tdl_millis - Time Difference Linking, which allows for differentiation between similarly-configured devices that might share a DeviceInsight identifier.
  • RECIPE VERSION_x: [DeviceInsightId] - The specific AdTruth device identification recipe version and the corresponding DeviceInsight identifier. There might be multiple AdTruth recipe versions. Currently we support two recipes ‰ŰŇ ‰ŰĎWEB_APP_BRIDGE_4_0‰Űť and ‰ŰĎUNIVERSAL_4_6_1‰Űť.

AdTruth parameter will not get passed/shared with the DSP if the user has opted out of the PubMatic system.

Maximum length in bytes:- 256 bytes

 

Example:


Content-Type: application/json
Content-Length: <length>
{
  ...
  "adtruth": {
    "tdl_millis": <TDL>,
    "<RECIPE VERSION_ENUM1>": "<DeviceInsightId1>",
    "<RECIPE VERSION_ENUM2>": "<DeviceInsightId2>" (Optional)
    ...
    "<RECIPE VERSION_ENUMn>": "<DeviceInsightIdn>" (Optional)
  }
  ...
}

 

Device Extension Parameters: device.ext parameters

                                                   

Field
Scope
Type
Definition
xff
Optional
Array of Strings
X-Forwarded-For HTTP header as received by PubMatic.
Example:
  • "xff": "unknown, 10.4.5.50, 4.4.4.4"
  • "xff": "10.4.5.50, 4.4.4.4"
  • "xff": "4.4.4.4, 156.34.37.9"
res
Optional
String
Resolution of the user screen.
Represented as widthxheight. Limited to 10 bytes.
Example: "1024x768"
Note: "-1x-1" indicates unknown resolution.
freq
Optional
Integer
Number of times the user was delivered an ad from the Demand Partner in the last 24 hours, starting from the time when the user first saw the ad from this Demand Partner. This would be passed only if there is a frequency cap set. Limited to 4 bytes.
Example: 2
pf
Optional
Integer
Type of platform on which the impression will be displayed. This parameter indicates the primary platform of the property. Possible values are:
  • 1 - Web
  • 2 - Mobile Web
  • 4 - Mobile App iOS
  • 5 - Mobile App Android
cat
Optional
Array of Integers
Categories of the location in which the user is present. For the list of values, refer to the xAd documentation.
For example, "cat":[1,2]
brand
Optional
Array of Integers
Brands available in the location in which the user is present. For the list of values, refer to the xAd documentation.
For example, "brand":[4,5]
loccatsrc
Optional
Integer
Source from which the above-mentioned location categories and brands are obtained. For the list of values, refer to the xAd documentation.
For example, "loccatsrc":1

 

Example:   

  {
      "ext": {
            "xff": "166.147.67.62",
            "res":"1280x1024",    
            "freq":1,
            "pf":1,
            "cat": [
                1,
                2
            ],
            "brand": [
                4,
                5
            ],
            "loccatsrc": 1
            }
      }

 

User Extension Parameters: user.ext parameters

                                       

Field
Scope
Type
Definition
tmz
Optional
String
Local time zone of the user browsing the page. Time zone is represented in hourly offset relative to GMT. Limited to 6 bytes.
Example: "5.5" (represents  IST)
Example: "8"(represents PST)
ethn
Optional
String
Ethnicity of the user (Example: ‰ŰĎ0‰Űť). Possible options are:
  • 0 - Hispanic
  • 1 - African-American
  • 2 - Caucasian
  • 3 - Asian-American
  • 4 - Other
inc
Optional
String
Income of the user.
cuid
Optional
String
Carrier-specific user's ID
cuidtype
Optional
Integer
Type of carrier-specific user's ID. Currently, only the following value is supported:
  • 1 - Verizon

 

Example:

 {
    "ext": {
      "tmz":"5.5",
      "ethn":"1",
      "inc":"$12000",
      "cuid":"Mik0NTM4Nzc4AEyi4kV6/Gv226rbxgIP+BRX7x+fknJqPTBx5yj1w0da",
      "cuidtype":1
    }
  }

 

Banner Extension Parameter: banner.ext

 

Attribute
Type
Description
wmax
integer
Maximum width of the impression in pixels. If included along with a "w" value then "w" should be interpreted as a recommended or preferred width.
hmax
integer
Maximum height of the impression in pixels. If included along with a "h" value then "h" should be interpreted as a recommended or preferred height.
wmin
integer
Minimum width of the impression in pixels. If included along with a "w" value then "w" should be interpreted as a recommended or preferred width.
hmin
integer
Minimum height of the impression in pixels. If included along with a "h" value then "h" should be interpreted as a recommended or preferred height.

 

Example:

"ext": {
    "wmin": 990,
    "hmin": 210,
    "wmax": 990,
    "hmax": 210
}

App Extension Parameter: app.ext parameter

                

Field
Scope
Type
Definition
pmid
mandatory
String
PubMatic assigned unique identifier for given App.

 

Example:

 

{
    "app": {
        "publisher": {
           "id": "70819"
        },
       "ext": {
            "pmid": "70821"
       }
    }
  }

 

Site Extension Parameter: site.ext parameter

Note: The "bsc" and "pagecat" parameters mentioned below are passed only if they are enabled for your account. To enable these parameters, contact your PubMatic Account Manager.

                     

Field
Scope
Type
Definition
sec
Optional
Integer
If the page from which ad request originates is ‰ŰĎhttps‰Űť, then the value is 1. It is expected that the partners will respond with an ‰ŰĎhttps‰Űť creative URL.  The bid will not be considered for auction if creativeURL in RTB response is ‰ŰĎhttp‰Űť and secure flag is 1.
bsc
Optional
Array of String
List of Brand Safety Scores for various brand safety categories associated with the Web page‰ŰŞs context.
This parameter includes the following brand safety categories:
  • adt - Adult
  • hat - Hate
  • off - Offensive
  • dlm - Illegal Downloads
  • alc - Alcohol
  • drg - Illegal Drugs
 
The score is classified in the following divisions:
  • 1 to 250 - Very high risk
  • 251 to 500 - High risk
  • 501 to 750 - Moderate risk
  • 751 to 1000 - Low risk

 

Note: In addition to the "bsc" parameter, the "pagecat" parameter included in the Open RTB 2.1 specifications is also used for providing contextual information about the Web page. This parameter lists the IAB categories (Tier 1 and Tier 2) applicable for the Web page. For more information about these categories, refer the IAB Categories List table in the Reference section.

Example:

{
    "site": {
      "pagecat": [
        "IAB52",
        "IAB14"
      ],
      "ext": {
        "sec":1
        "bsc": {
          "adt": 1000,
          "alc": 1000,
          "dlm": 100
        }
      }
    }
  }

Private Marketplace Extension Object: ext.pmp object

The "pmp"object contains a parent object for usage within the context of private marketplaces and the use of the RTB protocol to execute Direct Deals.

                           

Field
Scope
Type
Definition
private_auction
Optional
Boolean
Flag indicating that this impression is for a private auction and eligible only to seats named in the Direct Deals object below.
deals
Optional
Object
A collection of ‰ŰĎdeal‰Űť objects encapsulating a list of direct deals eligible for this impression.
ext
Optional
Object
This object is a placeholder that may contain a custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in the OpenRTB specification.

 

Deals object:

A "deal" object constitutes a deal previously struck between a buyer and a seller and indicates that this impression is available under the terms of that deal.

                                       

Field
Scope
Type
Definition
id
Required
String
A unique identifier for the direct deal.
bidfloor
Optional
Float
Bid floor for this impression (in CPM of bidfloorcur). Default value: 0
wseat
Optional
array of string
Array of buyer seats allowed to bid on this Direct Deal. Seats are an optional feature of exchange. For example, ["4","34","82","45"] indicates that only advertisers using these exchange seats are allowed to bid on the impressions in this auction.
at
Optional
Integer
Auction type. Possible values are:
  • 1 - First price auction, that is, the bid's eCPM will be used in the auction irrespective of the deal's eCPM if the bid's eCPM >= deal's eCPM and if it wins, bid's eCPM will be considered for the revenue calculation.
  • 2 - Second price auction, that is, the bid's eCPM will be used in the auction irrespective of the deal's eCPM and if it wins, the second price computation will be performed for the revenue calculation.
  • 3 - Fixed price auction, that is, the deal's eCPM will be used in the auction if the bid's eCPM >= deal's eCPM and if it wins, the deal's eCPM will be considered for the revenue calculation.
Additional auction types can be defined as per the exchange's business rules.
ext
Optional
Object
This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in the OpenRTB specification.

 

Example

Following is a sample of the ext object with the PMP details:

{
    "id": "92899110-7580-4534-884A-B7B9BC1D5EAF",
    ...
    "ext": {
          "pmp": {
             "private_auction": 0,
             "deals": [
                { "id": "3333", "bidfloor": 15, "wseat": [ "6", "15" ],     "at": 2 }
                ,
                { "id": "Deal_12345", "bidfloor": 5, "wseat": [ "100216" ], "at": 2 }
                ]
          }
    }
}

 

Note: If the Demand Partner includes the Deal ID in the bid response and bids below the Deal ID floor, PubMatic will reject the bid.

 

Demand Partner can choose to send an open bid, even if the RTB request contains an array of deals. The open bids are accepted on the system, however are subject to the publisher constraints set within the system.

 

Demand partners will have to respond back with "dealid" parameter in the"ext"object of the '"id"object as follows.


{
    "id": "1219C9B1-E1D1-41CB-AA4D-69F2BDAF4514",
    "seatbid": [
       {
         "bid": [
            {
               "id": "1",
               "impid": "1",
               "price": 14,
               "adm": "ADMARKUP",
               "adomain": [
                  "advertiserdomain.com"
                  ],
               "ext":
                  { "dealid": "3333" }
             }
          ],
          "seat": "511"
          }
       ],
    "bidid": "abc123",
    "customdata": "openrtb1"
}

 

                              

Deal ID Setting

Result

dealid  is not available

If deal ID is not available in response, then it will be considered as open bid.

dealid  is available

dealid = <dealid> set with floor


 

If the demand partner bids for a deal with a bid value (say $3) less than the floor value (say $4) of that deal, then PubMatic rejects such a bid.

dealid = <dealid> set with floor and auction type = first price

For a first price deal, if the bid value (say $5) is more than the floor value (say $4), then PubMatic uses the bid value as the winning price.

dealid = <dealid> set with floor and auction type = second price

For a second price deal, if the bid value (say $6) is more than the floor value (say $4) and the second highest bid value (say $3) is less than the floor value, and then PubMatic uses the floor value as the winning price. However, if the second highest bid value (say $5) is more than the floor value, then PubMatic uses the second highest bid value as the winning price.

dealid = <dealid> set with floor and auction type = fixed price

For a fixed price deal, if the bid value (say $6) is more than the floor value (say $4) then the closing price will be equal to floor price (say $4).

 

Note: While integrating with PubMatic, Demand Partners should ensure that the buyer or seat ID they provide for deals is a numeric string.

 

In addition, Demand Partners should always send numeric string values in the "seat"parameter mentioned above, and not alphanumeric string values; otherwise this may result in an error.

Native Markup Request Object

The Native object defines the native advertising opportunity available for bid via this bid request. It must be included directly in the impression object if the impression offered for auction is a native ad format.

                                                   

Field
Scope
Type
Definition
ver
Optional
String
Version of the Native Markup version in use.
Default value: 1
layout
Optional but recommended
Integer
Layout ID of the native ad unit. For more information, refer the Native Layout IDs table.
adunit
Optional but recommended
Integer
Ad unit ID of the native ad unit. This corresponds to one of IAB native ad units. For more information, refer the Native Ad Unit IDs table.
plcmtcnt
Optional
Integer
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
Optional
Integer
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
Required
Array of
objects
An array of Asset Objects. Any bid must comply with the array of elements expressed by the Exchange.
ext
Optional
Object
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

The main container object for each asset requested or supported by Exchange on behalf of the rendering client. Any object that is required is to be flagged as such. 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 Asset Object array so that the response can be aligned.

Note: The Asset object may contain only one of title, img, data or video mentioned below.

                                                   

Field
Scope
Type
Definition
id
Required
Integer
Unique asset ID, assigned by exchange. Typically a counter for the array.
required
Optional
Integer
Set to 1 if asset is required (exchange will not accept a bid without it)
Default value: 0
title
Optional
Object
Title object for title assets. For more information, refer the Title Object definition.
img
Optional
Object
Image object for image assets. For more information, refer the Image Object definition.
video
Optional
Object
Video object for video assets. For more information, refer 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
Optional
Object
Data object for ratings, prices etc.  For more information, refer the Data Object definition.
ext
Optional
Object
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.

                   

Field
Scope
Type
Definition
len
Required
Integer
Maximum length of the text in the title element.
ext
Optional
Object
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.

                                                   

Field
Scope
Type
Definition
type
Optional
Integer
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
Optional
Integer
Width of the image in pixels.
wmin
Optional but recommended
Integer
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
Optional
Integer
Height of the image in pixels.
hmin
Optional but recommended
Integer
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
Optional
Array of
strings
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 the Wikipedia's MIME page for more information and links to all IETF RFCs. If blank, assume all types are allowed.
ext
Optional
Object
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. This corresponds to the Video object of OpenRTB 2.3. Exchange implementors can impose their own specific restrictions. Here are the required attributes of the Video Object. For optional attributes, please refer to OpenRTB 2.3.

                                       

Field
Scope
Type
Definition
mimes
Required
Array of
strings
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
Required
Integer
Minimum video ad duration in seconds.
maxduration
Required
Integer
Maximum video ad duration in seconds.
protocols
Required
Array of
integers
An array of video protocols the publisher can accept in the bid response.  Refer the OpenRTB 2.3 Table 6.7 Video Bid Response Protocols for a list of possible values.
ext
Optional
Object
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. It is also generic for future of Native elements not contemplated at the time of the writing of this document.

                         

Field
Scope
Type
Definition
type
Required
Integer
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
Optional
Integer
Maximum length of the text in the element‰ŰŞs response.
ext
Optional
Object
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

The native creative is returned as a JSON-encoded string in the adm field of the Bid Object, or in response to calling the URL given in the nurl field of the Bid Object.

             

Field
Scope
Type
Definition
native
Required
Object
Native object in JSON format

 

Native Object

The JSON returned in adm or in response to nurl is a JSON string with the following attributes:

                                             

Field
Scope
Type
Definition
ver
Optional
Integer
Version of Native Markup being used.
Default value: 1
assets
Required
Array of objects
List of native ad's assets.
link
Required
Object
Destination Link. For more information, refer the Link Object definition.
imptrackers
[ ]
Optional
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
Optional
String
Optional JavaScript impression tracker. Contains <script> tags to be executed at impression time where it can be supported
ext
Optional
Object
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. The main container object for each asset requested or supported by Exchange on behalf of the rendering client. Any object that is required is to be flagged as such. 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 Asset Object array so that the response can be aligned.

                                                         

Field
Scope
Type
Definition
id
Required
Integer
Unique asset ID, assigned by exchange, must match one of the asset IDs in request
required
Optional
Integer
Set to 1 if asset is required. (bidder requires it to be displayed).
Default value: 0
title
Optional
Object
Title object for title assets. For more information, refer the Title Object definition.
img
Optional
Object
Image object for image assets. For more information, refer the Image Object definition.
video
Optional
Object
Video object for video assets. For more information, refer 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
Optional
Object
Value object for ratings, prices etc.
link
Optional
Object
Link object for call to actions. This link is to associated to the other populated field within the object.
ext
Optional
Object
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
Note: Bidders are encouraged not to use "asset.ext" for exchanging text assets. Instead, they should use "data.ext" with custom type.

 

Title Object

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

                   

Field
Scope
Type
Definition
text
Required
String
The text associated with the text element.
ext
Optional
Object
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.

                                 

Field
Scope
Type
Definition
url
Required
String
URL of the image asset.
w
Optional, but recommended
Integer
Width of the image in pixels.
h
Optional, but recommended
Integer
Height of the image in pixels.
ext
Optional
Object
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. It is also generic for the future of the Native elements not contemplated at the time of the writing of this document.

                           

Field
Scope
Type
Definition
label
Optional
String
The optional formatted string name of the data type to be displayed.
value
Required
String
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
Optional
Object
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.

             

Field
Scope
Type
Definition
vasttag
Required
String
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.

                               

Field
Scope
Type
Definition
url
Required
String
Landing URL of the clickable link.
clicktrackers[]
Optional
Array of strings
List of third-party tracker URLs to be fired on click of the URL.
fallback
Optional
String (URL)
Fallback URL for deeplink. To be (URL) used if the URL given in clk is not supported by the device.
ext
Optional
Object
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

 

Sample Request

{
  "id": "870DDB1A-6866-45F6-83A7-6D52F432063E",
  "at": 1,
  "imp": [
    {
      "id": "1",
      "tagid": "78257",
      "banner": {
        "w": 0,
        "h": 0
      },
      "ext": {
        "native": {
          "ver": 1,
          "assets": [
            {
              "id": 1,
               "required": 1,
              "title": {
                "len": 30
              }
            },
            {
              "id": 2,
              "required": 0,
              "data": {
                "type": 3,
                "len": 5
              }
            },
            {
              "id": 3,
              "required": 1,
              "img": {
                "type": 1,
                "w": 64,
                "h": 64,
                "mimes": [
                  "image/png"
                ]
              }
            },
            {
              "id": 4,
              "required": 0,
              "data": {
                "type": 2,
                "len": 10
              }
            }
          ]
        }
      }
    }
  ],
  "site": {
    "id": "32504",
    "domain": "http://test.com",
    "page": "http://testurl.com",
    "publisher": {
      "id": "31400"
    }
  },
  "device": {
    "ip": "123.123.123.123",
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 6_0_1 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Version/6.0 Mobile/10A523 Safari/8536.25",
    "carrier": "AT&T",
    "language": "en-US,en;q=0.5",
    "make": "Apple",
    "model": "iPhone",
    "os": "iOS",
    "Osv": "6",
    "devicetype": 1,
    "geo": {
      "country": "GB",
      "lat": 42.0619965,
      "lon": -72.4989014,
      "type": 2
    },
    "ext": {
      "otherdeviceid": "7679f2f945cae76177ee028c9cdc7bf9613f805e",
      "hash": 2,
      "xff": "123.123.123.123",
      "res": "320x480",
      "pf": 2
    }
  }
}

Sample Response

    "id": "1",
    "bidid": "abc123",
    "cur": "USD",
    "customdata": "openrtb1",
    "seatbid": [
        {
            "seat": "511",
            "bid": [
                {
                    "id": "1",
                    "impid": "1",
                    "price": 3.1,
                    "adm": "{\"native\":{\"ver\":1,\"link\":{\"url\":\"deeplink://deeplink/url/into/app\",\"fallback\":\"http://i.am.a/URL\",\"clktrck\":[\"http://a.com/a\",\"http://b.com/b\"]},\"imptrackers\":[\"http://a.com/a\",\"http://b.com/b\"],\"assets\":[{\"id\":1,\"title\":{\"text\":\"InstallXYZApp\"},\"link\":{\"url\":\"http://i.am.a/URL\"}},{\"id\":2,\"data\":{\"value\":5}},{\"id\":3,\"img\":{\"url\":\"http://cdn.testad.com/ad.png\",\"w\":64,\"h\":64}},{\"id\":4,\"data\":{\"value\":\"Install\"},\"link\":{\"url\":\"http://i.am.a/URL\"}}]}}",
                    "adomain": [
                        "advertiserdomain.com"
                    ],
                    "nurl": "http://localhost",
                    "cid": "campaign111",
                    "crid": "campaign111",
                    "ext": {
                        "dealid": 0
                    }
                }
            ]
        }
    ]
}

COPPA Compliance                  

This section provides information about the parameter introduced for COPPA compliance.

         

Parameter

Description

coppa

This parameter allows you to pass a flag in RTB requests (coppa=1) to DSPs if an impression is coming from COPPA sites or if the incoming ad request indicates that it has to be COPPA compliant.

 

In addition to passing coppa=1 in the bid requests, we would also set DNT=1 so that the partner is aware that it shouldn't track the user.

 

The United States Federal Trade Commission has changed the compliance rules for the Children's Online Privacy Protection Act ("COPPA"), effective July 1, 2013. The proposal effects websites and applications that have been identified as: (1) directed to users under 13 years of age; or (2) collecting information from users actually known to be under 13 (collectively "Children's Sites").

 

Note: The FTC has written a comprehensive FAQ on complying with COPPA at http://business.ftc.gov/documents/Complying-with-COPPA-Frequently-Asked-Questions.

 

The DSPs/partners must read and use the signal as part of COPPA compliance.

 

Example

Following is a sample of the ext object integrated with COPPA compliance:


{
  "device" : {
    "dnt" : 1,
    "ext": {
      "openudid": "9822637373",
      "adtruth": {
        "tdl_millis": 5334707361,
        "WEB_APP_BRIDGE_4_0": "1B6FC3C36C18C86B8E5DE602701808E5E0199395"
    }
  }
  "ext": {
    "regs": {
      "coppa":1
    }
  }
}

 

The "bidguidefloor" parameter provides bidding guidance and is only available upon request and opt-in of the demand partner. This parameter provides a suggested value for the impression as determined by the publisher's settings. The request parameter "bidfloorcur" indicates the currency of this floor's value.

 

Example:

{
  "id": "3A901F9E-040A-4C6A-8B8E-8CC10DB3E634",
  "imp": [
    ...
    }
  ],
  "site": {
    ...
  },
  "device": {
    ...
  },
  "user": {
    "id": "412C10A4-C2E4-437B-9141-C1740DA949CD"
  },
  "ext": {
    "bidguidefloor": 0.620000
  }
}

 

Bid Floor Currency

 

The "bidfloorcur" object indicates the currency of all the floor values (like "bidfloor" in the deals object, "bidguidefloor", etc.) being passed in the RTB request.

               

Field
Scope
Type
Definition
bidfloorcur
Optional
String
If "bidfloor" or "bidguidefloor" is specified and multiple currencies are supported per bid request, then the currency should be specified here using ISO - 4217 alphabetic codes. Note that this may be different from the bid currency returned by the bidder, if this is allowed on an exchange. Default value: USD

Example:

{
  "id": "412C10A4-C2E4-437B-9141-C1740DA949CD",
  ......
  "ext": {
    "bidguidefloor": 512.663,
    "bidfloorcur": "JPY"
    ......
  }
}

 

User Location

Note: The "lat", "lon" and "type" parameters for the user device's location are provided by the publisher.

                                 

Location source
Targeted object
".type" value
Description
Unknown
user.geo.lat
user.geo.lon
"geo.type" variable will not be present
"geo.type" is sent only when the "lat' and "lon" information is provided by the publisher when the location source is GPS/Location Service, IP Address or User Registration.
 
Refer the Open RTB API 2.1 specifications for more information about the "geo.type" variable.
GPS/Location Service
device.geo.lat
device.geo.lon
      And
*user.geo.lat
*user.geo.lon
geo.type=1
Except the"device.geo.lat"
"device.geo.lon" and "Ďgeo.type" parameters, the remaining geo-specific parameters (such as country, city, zip, etc.) in the "device" object are populated by PubMatic using the IP address.
 
* For backward compatibility, the location information is also currently populated in the "user.geo.lat" and "user.geo.lon" parameters for geo.type=1 till a specific date which will be notified later to the DSPs.
 
This is being provisioned for DSPs which are consuming the publisher-passed "lat" and "lon" values currently from the "user.geo" object and are expected to migrate to  the "device" object for "geo.type=1".
After this date, PubMatic will pass the "lat" and the "lon" values in the "user.geo" object only when location source = 0/3.
IP Address
device.geo.lat
device.geo.lon
geo.type=2
Except the"device.geo.lat"
"device.geo.lon"and "geo.type" parameters, the remaining geo-specific parameters (such as country, city, zip, etc.) in the "device" object are populated by PubMatic using the IP address.
User Registration
user.geo.lat
user.geo.lon
geo.type=3
The  "user.geo.lat"
"user.geo.lon" and "geo.type" parameters are populated by the publisher based on the user registration data.

 

Win-Loss Notification

If opted, DSP will receive win-loss reason of any of its recent bids in RTB bid request itself in post data. The post data will contain an object “wli” having following parameters.

                                             
Parameter
Mandatory
Multi-Valued
Description
rId
No
No
Unique request ID generated by PubMatic which is used to map the Bid-Request and Bid-Response. This will help to correlate the Bid-Notification with the specific Bid-Response. Limited to 40 bytes.
For example: 993DCB9F-9203-488C-818A-79FF231C921B
bCur
No
No
Currency of the winning bid value (wBid).
wBid
No
No
Bid (First Price) that won the auction.
Note: This value is always sent whether the DSP has won or lost the auction.
Csa
No
No
A value indicating whether a publisher is running an auction in their system for the given impression or not.  Possible values are:
  • 0 - The publisher is not running an auction for the impression.
  • 1 - The publisher is running an auction for the impression.
Note: Its default value is 0.
bId
No
No
Bid-ID string generated by the DSP and received in the bid response.
Note:
* The maximum length of this parameter’s value is 128 bytes.
* In case of a timeout, this parameter’s value will be empty.
st
No
No
Number denoting the status of the bid as follows.
  • 0 - The bid has won the auction.

    All the values other than zero denote that the bid has lost the auction and this value denotes the reason for the loss. For example,
  • 1 - Timeout on bid response,
  • 2 - Incomplete response, and so on.
The complete list of reasons why a bid will lose is given in the Win/Loss Notification Status table in the Reference section.
Note: Notifications will not be sent for zero price bids.

Note: Win loss notification is also supported for multi-bid.

 

Example for Win Notification:

 

A) In case of single bid

 

{
  ...
  "wli": {
    "rId": "371D32A4-F165-46DF-8845-20671EF134D0",
    "bCur": "JPY",
    "wBid": 20,
    "csa": 0,
    "bInfo": [
      { "bId": "abc123", "st": 0 }
    ]
  }
  ...
}

 

B) In case of multi-bid

{
  ...
  "wli": {
    "rId": "371D32A4-F165-46DF-8845-20671EF134D0",
    "bCur": "JPY",
    "wBid": 20,
    "csa": 1,
    "bInfo": [
      { "bId": "abc123", "st": 0 },
      { "bId": "abc123", "st": 5 },
      { "bId": "abc123", "st": 4 }
      ]
    }
  ...
}

 

Video Parameters

 

Parameter

Scope

Type

Description

h

optional

integer

Height of the video player measured from JavaScript.

Note: This parameter is present in the video object.

w

optional

integer

Width of the video player measured from JavaScript.

Note: This parameter is present in the video object.

Note: The following parameters are present in the video.ext object.

wndh

optional

integer

Minimum height of any window that was traversed in attempting to reach the top window.

wndw

optional

integer

Minimum width of any window that was traversed in attempting to reach the top window.

adh

optional

integer

Height of the area that the ad will have to actually render.

adw

optional

integer

Width of the area that the ad will have to actually render.

depth

optional

integer

Indicates the depth of the player in a set of windows/iframes from different domains, after traversing up any friendly iframes. Possible options are:

  • 0 - Player is not in an iframe (window == top), or you are able to traverse up friendly/same-domain iframes to the top window.
  • 1 - Player is in a single iframe, that is, the parent is the top window (window.parent == top).
  • 2 - Player is in at least two iframes of different domains, that is, (window != top and window.parent != top).  It is understood that it is not possible to know exactly the number of nested cross-domain iframes in which the current window is present. So this really indicates a depth of 2 or greater.

wndurl

optional

string

URL (document.location.href) of the highest window that can be accessed.

wndref

optional

string

Referrer URL (document.referrer) of the highest window that can be accessed.

ploc

optional

string

Distance of the player element relative to the left and top of the offset Parent node.

For example, y X x

ar

optional

string

Ratio of width to height of the display frame for the video, that is, the aspect ratio. Typically, this ratio is either 16:9 (widescreen) or 4:3 (full screen).

sm

optional

string

Mode which the player will use to resize the images and video to fit the display. Possible options are:

  • 0 - Cannot be determined
  • 1 - Uniform (Fits the player's dimensions while maintaining the original aspect ratio (black bars))
  • 2 - Exact fit (Fits the dimensions without maintaining the aspect ratio)
  • 3 - Fill (Stretches and zooms the video to fill the dimensions, while maintaining the aspect ratio)
  • 4 - None (Displays the actual size of the video file (black borders))

Note: Obtaining this value from the player depends upon the player's API.

Default value: 0

vcln

optional

string

Language used for player control or user interaction. Values will be passed using the alpha-2/ISO 639-1 standard.

Note: Obtaining this value from the player depends upon the player's API.

skip

Optional

Integer

Indicates whether the video ad can be skipped or not. Possible options are:

  • 0 - Ads cannot be skipped
  • 1 - Ads can be skipped

Default value: 0

skipdelay

Optional

Integer

Duration (in seconds) after which the user can skip the video ad, in case the ad can be skipped. After the skip-delay (also known as skip-offset) duration, a skip button will appear allowing the user to skip the ad. Possible value is any positive integer.

Default value: 0 (indicates that the ad can be immediately skipped)

noskipadlen

Optional

Integer

Length of the video ad for which the skip functionality will not be applicable. If the video ads can be skipped, ads shorter than this length are rendered without a skip button, that is, the skip option is available only on ads longer than this duration

Default value: 0

Note: This parameter can be used by the publisher to give some flexibility to the advertisers to play a non-skippable video ad in skippable ad inventory; (trade-off between video ad and publisher content)

audio

Optional

Integer

Indicates that the bid request is for Audio through VAST;

All other parameters should be considered in the context of Audio impression through VAST

 

Possible options are:

  • 0 _ă_ Bid request is Not for Audio
  • 1 _ă_ Bid request is for Audio

Default value: 0

fullscreenexpandableOptionalInteger

Placed inside the ext object of the video object.

Possible values:

0 = Not Expandable

1 = Is Expandable

2 = Unknown

 

Example:

 

{
    ...
    "video": {
      ...
       "h": 300,
       "w": 420,
       "ext": {
         "skip": 1,
         "skipdelay": 5,
         "noskipadlen": 15,
         "wndh": 600,
         "wndw": 840,
         "adh": 300,
         "adw": 420,
         "depth": 1,
         "wndurl": "http://youtube.com",
         "wndref": "http://google.com",
         "ploc": "400X500",
         "ar": "4:3",
         "sm": 1,
         "vcln": "en"
         "audio": 1
        }
    }
    ...
}

 

Rich Media Technology in Response

 

If the creative to be served is rich media, then it is mandatory to send this parameter in the response.

                     

Parameter
Scope
Type
Description
rmt
Optional
String
Rich media technology of the creative. For more details, refer the Rich Media Technologies table in the reference section of this document. Example: pr
crtypeOptionalInteger
Indicates the type of creative. Example: vast (VAST 1.0, VAST 2.0, VAST 3.0), MRAID (MRAID 1.0, MRAID 2.0), Image Ad, HTML5, JS, and FLASH.
Note: For more details, refer to the Creative Type Attributes table.

Note: If the creative to be served is rich media, then it is mandatory to send the "attr" parameter as mentioned in the OpenRTB 2.3 specification in the response. Note that even though the "attr" parameter is an array of integers, PubMatic will currently parse only the first element in the array.

 

Example 1:

{
  ...
  "seatbid": [
    {
      "bid": [
        {
          ...
          "ext": {
            "rmt": "pr",
              "crtype": 1
          }
        }
      ],
      ...
    }
  ],
  ...
}

 

Example 2:

 

{
    "id": "1",
    "seatbid": [
        {
            "bid": [
                {
                    "id": "1",
                    "impid": "1",
                    "price": 123.4567,
                    "iurl": "http://localhost",
                    "adm": "<!DOCTYPE html PUBLIC \\\"-\n//W3C//DTD XHTML 1.0 Transitional//EN\\\" \\\"htt\np://www.w3.org/TR/xhtml1/DTD/xhtml1-\ntransitional.dtd\\\"><html xmlns=\\\"http://www.w3.org/1\n999/xhtml\\\" xml:lang=\\\"en\\\" lang=\\\"en\\\"\n>MY OPEN RTB CAMPAIGN WON ID:${AUCTION_ID} BID_ID:${AUCTION_BID_ID} IMP_ID:${AUCTION_IMP_ID} SEAT_ID:${AUCTION_SEAT_ID}\nAD_ID:${AUCTION_AD_ID} PRICE:${AUCTION_PRICE} CUR:${AUCTION_CURRENCY} </html>",
                    "attr": [],
                    "adomain": [
                        "www.advdomain.com?"
                    ]
                    "cid": "campaign111",
                    "crid": "creative111",
                    "ext": {
                        "dealid": "0",
                        "rmt": "pj",
                        "crtype": 1
                    }
                }
            ],
            "seat": "511"
        }
    ],
    "bidid": "abc123",
    "cur": "USD",
    "customdata": "openrtb1",
    "ext": {
        "dnbr": 3
    }
}

 

 

Deal-No Bid Reason in Response

If a demand partner does not want to bid for an impression associated with its Private Marketplace deal, then it is recommended to send its reason in the response with the following parameter.

               

Parameter
Scope
Type
Description
dnbr
Optional
Integer
Reason for not bidding on a Private Marketplace deal's impression. In such cases, Demand Partners are requested to send this value in the response.
For more details, refer the Deal - No Bid Reason table in the reference section of this document.
Example: 5

 

Example:

 

{
  "id": "1",
  "seatbid": [
    {
     ...
   }
  ],
  ...
  "ext": {
    "dnbr": 3
  }
}

 

Impression Extension Parameter

This flag indicates whether the winning bid from PubMatic will participate in another auction with the publisher. Client side header bidding tags would take winning bid from PubMatic typically and let it compete with other exchanges or other demand partners in their ad server. Some publishers would send request to PubMatic through the Server-to-Server (S2S) API and let PubMatic’s winning bid participate in a server side auction at their end with other demand sources they have. In either case, a value of 1 indicates that winning bid from PubMatic participates in another decisioning cycle with the publisher.

 

This information can be used by DSPs in many ways including doing analytics on such impressions, bidding differently, consolidating traffic from different exchanges etc. This flag is set at tag id level.

NameScopeType
headerbidding.presentOptionalInteger

 

Example

"imp": [{
          "id": "1",
          "tagid": "1059931",
          "video": {
               "mimes": ["video/mp4", "application/x-shockwave-flash", "video/x-ms-wmv", "video/h264", "video/webm", "application/javascript", "video/ogg"],
               "minduration": 1,
               "maxduration": 180,
               "protocols": [2, 5],
               "startdelay": 0,
               "battr": [8, 9, 10, 14, 44],
               "h": 480,
               "w": 640
          },
          "ext": {
               "headerbidding": {
                    "present": 1
               }
          }
}]

Attachments

    Outcomes