OpenRTB 2.3 PubMatic Extensions

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

OpenRTB 2.3 Documentation 

OpenRTB 2.3 Introduction 

OpenRTB 2.3 Integration Plan 

OpenRTB Bid Request Objects and Parameters 

OpenRTB Bid Response Objects and Parameters 

OpenRTB 2.3 PubMatic Extensions 

Open RTB 2.3 Examples 

OpenRTB Ad Server API Cookie Sync 

OpenRTB 2.3 Click Tracking 

OpenRTB 2.3 Win/Loss Notification 

OpenRTB 2.3 API Performance 

OpenRTB 2.3 Known Limitations & Reference 

PubMatic Extensions

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

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

AdTruth Parameter: device.ext.adtruth

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)
}
...
}

 

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

 

Example

...
{
"ext": {
"ethn":"1",
"inc":"$12000",
"cuid":"Mik0NTM4Nzc4AEyi4kV6/Gv226rbxgIP+BRX7x+fknJqPTBx5yj1w0da",
"cuidtype":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.

                     

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.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 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