Page tree



Introduction

The OpenRTB 2.3 PubMatic Extensions and related documentation describes the supported features and limitations of PubMatic's OpenRTB.  The latest OpenRTB 2.3 specifications are available at  http://www.iab.net/rtbproject . These documents are designed to be used in conjunction with the OpenRTB 2.3 specifications.

Version

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

Limitations.

Known Limitations

  • Ad Markup must be sent by the DSP directly within the bid response (nurl parameter will not be supported.).
  • 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.
  • PubMatic allows up to 5 bids in case multibids.
  • PubMatic currently supports only one element in the "domain" and "attr" parameter.

PubMatic Extensions

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

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

  1. Supported currencies: USD, JPY, EUR, GBP, CAD, AUD, SEK, CHF, CZK, DKK, BRL, NZD.
  2. 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 send "cat", "h", "w"parameters in the response.

Supported Objects/Parameters

                                                                                                                     

ObjectSupportedRecommended Parameters Not SupportedOptional Parameters Supported
Bid-RequestYes at, bcat, badv, regs
ImpressionYes tagid, secure, iframebuster, pmp
BannerYes pos, battr, topframe, expdir, api, wmax, wmin, hmax, hmin
VideoYes linearity, battr, minbitrate, maxbitrate, playbackmethod, companionad, api, pos
NativeYes  
SiteYes domain, pagecat, page, ref, mobile, publisher
AppYes name, bundle, domain, storeurl, cat, ver, paid, publisher
ContentNo  
PublisherYes ID
ProducerNo  
DeviceYeslmtdevicetype, make, model, os, osv, js, language, carrier, connectiontype, ifa, didsha1, didmd5, dpidsha1, dpidmd5, macsha1, macmd5
GeoYes lat, lon, type, country, region, metro, city, zip, utcoffset
UserYes yob, gender, keywords, geo
DataNo  
SegmentNo  
RegulationsYes coppa
PMPYes deals, private_auction
Direct DealsYes bidfloor, bidfloorcur, at, wseat


Extensions

Bid Guide Floor Parameter: bidguidefloor

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 Parameter: bidfloorcur

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"
    ......
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Device Extension Parameters: device.ext 

                                 

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


Example

...{
 "ext": {
 "xff": "166.147.67.62",
 "res":"1280x1024",
 "freq":1,
 "pf":1,
 }
}...‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

User Extension Parameters: user.ext                                 

Field

Scope

Type

Definition

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

consent

Optional

String

If the Regs.ext.gdpr flag is 1 then this string gives consent information of various vendors.

consented_providers_settings.consented_providers

Optional

Array of Integers

Set of IDs corresponding to providers for whom the publisher has told Google that its EEA (European Economic Area), users have consented to the use of their personal data for ad personalization.

Note: Specific to Google EB Integrations and applicable only when Regs.ext.gdpr=1


Example

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


GDPR-Specific Examples:

Example:

"user": { "ext": {"consent": "BONihAGONihAGABABAENAQ____AArABAAAA"}}‍‍‍‍


Example with Google EB Parameters for GDPR:

"user": { 
        "ext": { 
               "consented_providers_settings": {  
               "consented_providers": [123, 456] 
               }  
        } 
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Object: Regs.ext                                 

Field

Scope

Type

Definition

gdpr

Optional

Integer

Possible values: 0 or 1 to indicate whether or not the impression is GDPR-regulated. 


Example:

"regs": {"ext": {"gdpr": 1}‍‍‍‍


Win-Loss Notification

         Note: PubMatic recommends sending "nbr" parameter in the bid response for the DSPs using the Win-Loss Notification feature.
      

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

Scope

Type

Description

rId

optional

string

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

optional

string

Currency of the winning bid's value (wBid).

wBid

optional

float

Bid (First Price) that won the auction.

Note: This value is always sent whether the DSP has won or lost the auction.

csa

optional

integer

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.

bInfo

optional

Array of objects

Array of bid objects

bId

optional

string

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

optional

integer

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 later 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 }
      ]
    }
  ...
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Site Extension Paramater: site.ext

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

bsc

Optional

Object

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.3 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": {
      "bsc": {
        "adt": 1000,
        "alc": 1000,
        "dlm": 100
    }
    }
   }
  }
...‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


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.

                     

ParameterScopeTypeDescription
rmtOptionalString

Rich media technology of the creative.
For more details, refer the Rich Media Technologies table in the reference section. 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.1 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

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


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 to the Deal - No Bid Reason table in the reference section.
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
               }
          }
}]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


⇧ Top