OpenWrap

OpenWrap In-App OTT

To support header bidding for OTT mobile apps, OpenWrap supports a REST API that fetches bids for a video ad slot and returns those bids as a set of targeting keys that you can pass to the ad server. The following steps describe how to configure this API and send the returned targeting keys to Google Ad Manager (GAM). Although the examples use GAM, the concepts demonstrated below will work with any ad server; only the details of passing the targeting keys differ between ads servers.

Step 1: Setup OpenWrap profile

Create an OpenWrap profile with OTT/CTV chosen as the Platform type. Then configure bidders, map ad units, and push the profile live. See OpenWrap Profile Management for details on how to create a profile and map ad units.

Step 2: Make a call to OpenWrap ahead of call to ad server to fetch bids

OpenWrap will return bid(s) for the video slot in the form of targeting keys.

Sample OpenWrap request URL:
https://ow.pubmatic.com/openrtb/2.5/video?pubId=156276&profId=1187&pwtmime=1&f=json&pwtm_iu=%2F40619304%2FOW_Video&pwtm_sz=640x480&pwtm_url=https%3A%2F%2Fwww.pubmatic.com.com%2F

All parameters for the OpenWrap video request are sent as URL parameters. Accurate and complete video parameters are essential to achieve good yield. Consult with your PubMatic customer success manager to ensure you're using the correct set of parameters. If there is no bid, OpenWrap server still returns a JSON response, but your code must still handle error cases such a no response at all or non-200 HTTP response codes. When making the call to OpenWrap, always set a timeout in your code in case a call doesn’t complete. While OpenWrap respects the timeout specified in the profile, the client call may not complete within the maximum allowed time due to network latency or other issues.

If you intend to send requests to GAM…

As GAM ad unit ids include the / character, be sure to URL encode these values.

In-app OTT parameters

Name

oRTB parameter

Parameter Type

Notes

pubId (Required)


integer

Your PubMatic account at Publisher ID, for example:

pubId=12345

profId (Required)
integer

OpenWrap profile ID, for example:

profId=1000

f


string

Format of response to return, for example:

f=json

Pass this parameter to specify response format.

If value of this parameter is JSON, the response returns JSON data containing only the targeting field.

Values other than JSON, get a response containing a redirect url unless debug is true.

pwtm_iu (Required)


string

Inventory ad unit as a URL encoded string, for example:

pwtm_iu=%2F40619304%2FOW_Video

This is the ad unit value OpenWrap uses for mapping to demand partner parameters.

pwtm_sz (Required)


string

Video player size in the format, WxH (Width x Height); for example:

pwtm_sz=640x480

Only one size is allowed.

pwtm_url (Required)


string

Encoded page URL, for example:

pwtm_url=https%3A%2F%2Fwww.pubmatic.com.com%2F

Applicable only to Desktop, Web, and Mobile Web setup.

pwtbidrprm


URL encoded JSON string

Bidder specific key-value for Xandr (formerly AppNexus) and PubMatic.

  1. Targeting support under PubMatic SSP today requires the dctr parameter (PMP targeting does not currently support the keywords param).
  2. To pass the same information to downstream DSPs like Xandr requires the keywords parameter.

Example unencoded/encoded JSON with key-values:

Unencoded JSON Payload URL Encoded JSON Payload
Bidder JSON
{
    "pubmatic":{
        "keywords":[
            {
                "key":"title",
                "value":[
                    "The Hunt"
                ]
            },
            {
                "key":"genre",
                "value":[
                    "animation",
                    "adventure"
                ]
            },
            {
                "key":"dctr",
                "value":[
                    "title%3DThe%20Hunt%7Cgenre%3Danimation%2Cadventure"
                ]
            }
        ]
    },
    "appnexus":{
        "keywords":[
            {
                "key":"title",
                "value":[
                    "The Hunt"
                ]
            },
            {
                "key":"genre",
                "value":[
                    "animation",
                    "adventure"
                ]
            }
        ]
    }
}
Bidder JSON (Contains <CR>s for readability.)
%7B%0A%20%20%20%20%22pubmatic%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%22keywords%22%3A%20%5B%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20
%22key%22%3A%20%22title%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22value%22%3A%20%5B%22The%20Hunt%22%5D%0A%20%20%20%20%20%20%20%20
%7D%2C%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%22key%22%3A%20%22genre%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22value%22%3A%20
%5B%22animation%22%2C%20%22adventure%22%5D%0A%20%20%20%20%20%20%20%20%7D%2C%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%22key%22%3A%20
%22dctr%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22value%22%3A%20%5B%22title%253DThe%2520Hunt%257Cgenre%253Danimation%252Cadventure%22
%5D%0A%20%20%20%20%20%20%20%20%7D%5D%0A%20%20%20%20%7D%2C%0A%20%20%20%20%22appnexus%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%22keywords%22%3A
%20%5B%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%22key%22%3A%20%22title%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%22value%22%3A%20%5B
%22The%20Hunt%22%5D%0A%20%20%20%20%20%20%20%20%7D%2C%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%22key%22%3A%20%22genre%22%2C%0A%20%20%20%20
%20%20%20%20%20%20%20%20%22value%22%3A%20%5B%22animation%22%2C%20%22adventure%22%5D%0A%20%20%20%20%20%20%20%20%7D%5D%0A%20%20%20%20%7D%0A%7D

pwtvapi

API

integer array

Use 7 to indicate OMID-1 (Open Measurement Support); for example:

pwtvapi=7

Use 2,7 for viewability in desktop setup. For example:

pwtvapi=2,7

pwtbatr

BAttr

integer array

Blocked creative attributes. For example:

pwtbatr=1,2

See oRTB 2.5 Spec, section 5.3 Creative Attributes , for the full list of values.

pwtbox

BoxingAllowed

boolean

Indicates whether to allow letter-boxing of 4:3 content into a 16:9 window; 0 = no, 1 = yes. For example:

pwtbox=1

pwtdvry

Delivery

integer array

Supported delivery methods (for example, streaming, progressive). If pwtdvry is left blank, PubMatic assumes all types are supported.

pwtdvry=1,2

See oRTB 2.5 Spec, section 5.15 Content Delivery Methods, for the full list values.

pwtmnbr

MinBitrate

integer

Minimum bit rate in Kbps. For example:

pwtmnbr=300

pwtmxbr

MaxBitrate

integer

Maximum bit rate in Kbps. For example:

pwtmxbr=1000

pwtmxex

MaxExtended

integer

Maximum extended ad duration if extension is allowed. Use the following values to determine extension permission:

  • 0 (or blank) = extension is not allowed.
  • -1 = extension allowed, with no imposed time limit.
  • >0 = number of seconds of extended play supported beyond the maxduration value.

For example:

pwtmxex=0

pwtmime

Mimes

integer array           

A comma-separated list of integer values representing HTML MIME types, for example:

pwtmime=1,2

The following table lists integer values that represent corresponding MIME types:

ID Value
0All
1video/mp4
2application/x-shockwave-flash
(VPAID - FLASH)
3video/wmv
4video/h264
5video/webm
6application/javascript
(VPAID - JS)
7video/ogg
8video/flv

pwtvplc

Placement

integer

Placement type for the impression. For example:

pwtvplc=1

See oRTB 2.5 Spec, section 5.9 Video Placement Types, for a full list of values.

pwtvpos

Pos

integer

Ad position on screen. For example:

pwtvpos=1

See oRTB 2.5 Spec, 5.4 Ad Position section, for the full list of values.

pwtprot

Protocol

integer

Deprecated. See pwtprots below.

pwtprots

Protocols

integer array

A comma-separated list of supported video protocols. For example:

pwtprots=1,2

See oRTB 2.5 Spec, 5.8 Protocols section, for the full list of values.

pwtseq

Sequence

integer

When a single bid request offers multiple ad impressions, the sequence number allows coordinated delivery of multiple creatives.

pwtseq=1

Defaults to 1 if parameter is not used.

pwtskp

Skip

boolean

Indicates whether the player allows the user to skip video; 0 = no, 1 = yes. For example, to allow users to skip the video:

pwtskp=1

pwtskmn

SkipMin

integer

When an ad is skippable (see pwtskp above), videos with a duration greater than this number of seconds allow users to skip, after the video plays longer than this value. For example, with the setting below, the video must play a minimum of 5 seconds before the user can skip:

pwtskmn=5

pwtskat

SkipAfter

integer

When an ad is skippable (see pwtskp above), this is the number of seconds a video must play before the user can skip. For example, the setting below limits skipping until after the video has played 10 seconds:

pwtskat=10

pwtvlin

Linearity integer

Indicates if the impression must be linear or nonlinear, where:

1 = Linear

2 = Non-linear

For example:

pwtvlin=1

pwtvmnd

Minduration integer

Minimum video ad duration in seconds. For example:

pwtvmnd=5

pwtvmxd

Maxdurationinteger

Maximum video ad duration in seconds. For example:

pwtvmnd=10

pwtplbk

PlaybackMethod integer array

Playback methods that may be in use. For example:

pwtplbk=1

See  OpenRTB Spec 2.5 >  Playback Method for the full list of values.

pwtdly

StartDelay integerIndicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. See  OpenRTB Spec 2.5 >  Start Delay for additional generic values.

User parameters

Name

oRTB parameter

Parameter type

Notes

pwtyob

User.yob

integer

User year of birth.

pwtgender

User.Gender

string

User gender.

Content parameters

Name

oRTB parameter

Parameter type

Notes

pwtgenre

Content.Genre

string

Content genre; for example, "science fiction."

pwttitle

Content.Title

string

Content title; for example, "Star Wars."

GDPR parameters

Name

oRTB parameter

Parameter type

Notes

pwtgdpr

regs.ext.gdpr

integer

Value indicating GDPR enabled or not

pwtcnst

user.ext.consent

string

Consent string

CCPA parameters

Name

oRTB parameter

Parameter type

Notes

pwtccpa

user.ext.us_privacy

string

CCPA string

Mobile parameters

Name
oRTB parameterParameter typeNotes

pwtapp

Appboolean

The following parameters apply only when the pwtapp parameter is set to 1 (true), which identifies the request as mobile. For example, pwtapp=1

Sample mobile request
http://ow.pubmatic.com/openrtb/2.5/video/?v=1&pubId=5890&iuId=Div1&profId=4415&
pwtvmxd=100&pwtvmnd=25&pwtmime=1&pwtplbk=1,2&pwtdly=-1&pwtm_description_url=
www.abc.com&pwtm_sz=640x480&pwtbatr=1,26

See oRTB 2.5 Spec, 3.2.14 Object: App section, for more details .

pwtappkwapp.keywordsstring

Comma separated list of keywords about the app. For example, keyword-a,keyword-b,keyword-c

pwtappid

App.Id

string

App ID registered with PubMatic.

pwtappname

App.Name

string

App name, typically as it appears on the platform app store (may be aliased at the publisher’s request).

pwtappbdl

App.Bundle

string

A platform-specific unique identifier for the app and independent of the PubMatic or any exchange. For Android, this should be a bundle or package name (for example, com.foo.mygame). On iOS, it is typically a numeric ID.

pwtappdom

App.Domain

string

Domain for the app. For example, mygame.foo.com

pwtappurl

App.StoreURL

string

App store URL for an installed app (IQG 2.1 compliant).

pwtappcat

App.Cat

string array

Comma-separated list of IAB content categories for the app. See oRTB 2.5 Spec, 5.1 Content Categories section, for the IAB category list .

pwtapppd

App.Paid

boolean

1 = app is a paid version or 0 = app is free.

pwtlmt

Device.Lmt

boolean

User chosen “Limit Ad Tracking” preference:

  • 0 (false) = tracking is unrestricted.
  • 1 (true) = tracking must be limited per platform guidelines.

pwtdnt

Device.Dnt

boolean

Standard “Do Not Track” flag set in the header by the browser:

  • 0 = tracking is unrestricted.
  • 1 = do not track.

pwtjs

Device.JS

integer

Support for JavaScript:

  • 0 = no.
  • 1 = yes.

pwtifa

Device.Ifa

string

ID sanctioned for advertiser use in the clear; that is, not hashed.

pwtdidsha1

Device.DidSha1

string

Hardware device ID (that is, IMEI); hashed via SHA1.

pwtdidmd5

Device.DidMd5

string

Hardware device ID (that is, IMEI); hashed via MD5.

pwtdpidsha1

Device.DpidSha1

string

Platform device ID (that is, Android ID); hashed via SHA1.

pwtdpidmd5

Device.DpidMd5

string

Platform device ID (that is, Android ID); hashed via MD5.

pwtmacsha1

Device.MacSha1

string

MAC address of the device; hashed via SHA1.

pwtmacmd5

Device.MacMd5

string

MAC address of the device; hashed via MD5.

pwtlat

Device.Geo.Lat

float

Latitude from -90.0 to +90.0 (negative is south).

pwtlon

Device.Geo.Lon

float

Longitude from -180.0 to +180.0, (negative is west).

pwtgtype

Device.Geo.Type

integer

Source of location data; recommended when passing lat/lon. See oRTB 2.5 Spec, 5.20 Location Type section, for the list.

pwtcntr

Device.Geo.Country

string

Country code using ISO-3166-1-alpha-3; for example, USA = United States of America.

pwtcity

Device.Geo.City

string

City using United Nations Code for Trade and Transport Locations. See oRTB 2.5 Spec, Appendix A, for a link to the locations .

pwtmet

Device.Geo.Metro

string

Google metro code; similar to but not exactly Nielsen DMAs. See oRTB 2.5 Spec, Appendix A, for a link to the codes.

pwtzip

Device.Geo.Zip

string

Zip or postal code.

pwtuto

Device.Geo.UtcOffset

integer

Local time as the number +/- of minutes from UTC.

pwtuid

User.ID

string

Exchange-specific ID for the user. At least one of id or buyeruid is recommended.

Step 3: Parse the response from OpenWrap

On successful bidding OpenWrap returns an HTTP 200 with a JSON response similar to the examples below. 

Sample response with 'pwtbuyid_pubmatic' key
{
    "targeting": {
        "pwtbst": "1",
        "pwtbst_appnexus": "1",
        "pwtbst_pubmatic": "1",
        "pwtbuyid_pubmatic": "115",
        "pwtcid": "f5956d0a-d465-448a-8ebe-552ca81e9cb1",
        "pwtcid_appnexus": "e62e0382-a3a7-4ba2-92ae-475ababbd07b",
        "pwtcid_pubmatic": "f5956d0a-d465-448a-8ebe-552ca81e9cb1",
        "pwtcpath": "/cache",
        "pwtcurl": "https://ow.pubmatic.com",
        "pwtdid": "PUBDEAL1",
        "pwtdid_pubmatic": "PUBDEAL1",
        "pwtecp": "15.00",
        "pwtecp_appnexus": "1.80",
        "pwtecp_pubmatic": "15.00",
        "pwtpid": "pubmatic",
        "pwtpid_appnexus": "appnexus",
        "pwtpid_pubmatic": "pubmatic",
        "pwtplt": "video",
        "pwtprofid": "15765",
        "pwtpubid": "5890",
        "pwtsid": "/15671365/DMDemo2",
        "pwtsid_appnexus": "/15671365/DMDemo2",
        "pwtsid_pubmatic": "/15671365/DMDemo2",
        "pwtsz": "0x0",
        "pwtsz_appnexus": "1x1",
        "pwtsz_pubmatic": "0x0",
        "pwtverid": "1"
    }
}


Sample response for “Send All Bids” scenario
{
    "targeting": {
        "pwtbst": "1",
        "pwtbst_appnexus": "1",
        "pwtbst_pubmatic": "1",
        "pwtcid": "dee9c1ee-3276-4689-958f-a125a6394c3b",
        "pwtcid_appnexus": "e680d9e9-ac9e-4e1d-9fb8-b0a91cbb02e2",
        "pwtcid_pubmatic": "dee9c1ee-3276-4689-958f-a125a6394c3b",
        "pwtcpath": "/cache",
        "pwtcurl": "https://ow.pubmatic.com",
        "pwtdid": "PUBDEAL1",
        "pwtdid_pubmatic": "PUBDEAL1",
        "pwtecp": "15.00",
        "pwtecp_appnexus": "0.18",
        "pwtecp_pubmatic": "15.00",
        "pwtpid": "pubmatic",
        "pwtpid_appnexus": "appnexus",
        "pwtpid_pubmatic": "pubmatic",
        "pwtplt": "video",
        "pwtprofid": "15765",
        "pwtpubid": "5890",
        "pwtsid": "/15671365/DMDemo2",
        "pwtsid_appnexus": "/15671365/DMDemo2",
        "pwtsid_pubmatic": "/15671365/DMDemo2",
        "pwtsz": "0x0",
        "pwtsz_appnexus": "1x1",
        "pwtsz_pubmatic": "0x0",
        "pwtverid": "1"
    }
}


Sample response for error scenario
{
    "targeting": {
        "pwterr": "1"
    }
}


The JSON's targeting property holds the targeting keys for OpenWrap’s video bid:

JSON response targeting property
{

    "targeting": {

        "pwtbst": "1",

        "pwtcid": "6ffb3535-4574-46e0-ae4d-6d1955e5a2b2",

        "pwtcpath": "/cache",

        "pwtcurl": "https://ow.pubmatic.com",

        "pwtecp": "3.00",

        "pwtpid": "pubmatic",

        "pwtplt": "video",

        "pwtprofid": "1187",

        "pwtpubid": "156276",

        "pwtsid": "/40619304/OW_Video",

        "pwtsz": "0x0"

    }

}

Error responses

Errors from the request return an error code in the pwterr key, as shown in the following table.

Error codeErrorDescription
1Invalid ConfigurationThis error comes in case of wrong wrapper publisher id/profile id/version id combination is being sent in the request for which no data exists in DB.
2Cache Error Cache Put operation failed. This error comes when there is some error in Cache Put call for creative.
3Timeout ErrorThis error is returned when prebid fails to respond in the given time. (No response from Prebid Server)
This error also comes in cases where server-side times out.
4Parameter validation failedParameter validation failed (This will occur if any validations on input parameters fails. For e.g. if PubID sent in the request is non numeric, its validation will fail.)
Reasons for pwterr=4: * Missing pubid/Invalid Pubid
  • Invalid Profile ID (like profId = jkaf0avjakj)
  • Missing slot key
  • Missing mime key (pwtmime)
  • Invalid mimes are passed in pwtmime
  • Invalid value for device dnt (pwtdnt)and lmt (pwtlmt) for app requests (pwtapp=1). Valid values are 0 and 1
  • Invalid gdpr (pwtgdpr). Only 0 and 1 are allowed
  • Invalid ccpa (pwtccpa). Only string of lenght 4 is allowed
5Unmapped Slot ErrorThis error is returned when a slot name (like adunit@size) is not mapped in the wrapper. In case of video, final slot name that we look for in the DB is slot_name@0x0
11All partners throttledThis error comes when all the partners configured for a profile are throttled at runtime
Sample error response
{
    "targeting": {
        "pwterr": "1"
    }
}

Step 4: Append targeting keys to your GAM (or other ad server) VAST URL 

This section uses GAM as the example, but the concepts are the same for any other ad server; only the details of passing the targeting keys differs between ads servers. 

Capture the targeting keys from the OpenWrap response JSON, then add them to the VAST ad tag URL that you will use to GAM.

Example GAM URL without targeting keys
https://pubads.g.doubleclick.net/gampad/ads?correlator=abcd&iu=/40619304/OW_Video&env=vp&gdfp_req=1&output=vast&sz=640x480&description_url=http%3A%2F%2Fwww.pubmatic.com%2F&tfcd=0&npa=0&vpmute=0&vpa=0&vad_format=linear&url=http%3A%2F%2Fwww.pubmatic.com%2F&vpos=preroll&unviewed_position_start=1

Pass targeting keys in the cust_params URL parameter. The cust_params parameter contains a copy of the URL keys encoded as a URL query string. Since cust_params is part of a url query string itself, you'll have a url query string within a url query string:

Example GAM URL containing targeting keys
https://pubads.g.doubleclick.net/gampad/ads?correlator=5764440571761895999&cust_params=pwtpid%3Dpubmatic%26pwtpubid%3D156276%26pwtsid%3D%2F40619304%2FOW_Video%26pwtcid%3D4b848aae-e63b-443d-b26e-8ba8d961579f%26pwtcurl%3Dhttps%3A%2F%2Fow.pubmatic.com%26pwtplt%3Dvideo%26pwtbst%3D1%26pwtsz%3D0x0%26pwtprofid%3D1187%26pwtverid%3D%26pwtcpath%3D%2Fcache%26pwtecp%3D3.00&description_url=http%3A%2F%2Fwww.pubmatic.com%2F&env=vp&gdfp_req=1&iu=%2F40619304%2FOW_Video&npa=0&output=vast&sz=640x480&tfcd=0&unviewed_position_start=1&url=http%3A%2F%2Fwww.pubmatic.com%2F&vad_format=linear&vpa=0&vpmute=0&vpos=preroll

Always URL encode the cust_params parameter. See Prebid.js for a good reference implementation to encode targeting values into cust_params.

If you are already passing custom targeting keys to GAM, you must combine your existing targeting keys and OpenWrap’s targeting keys in the cust_params field.

The VAST url augmented with targeting keys can now pass to the video ads SDK as normal. In many cases, the ads SDK will be IMA, but this approach work with other ads SDKs as well.Step 5: Pass augmented URL to Ads SDK.

Additional Requirements

  • For the ad server to utilize the targeting keys, you must set up line items on the target ad server. Contact your PubMatic customer success manager to arrange for line item set up.

Samples

The samples below demonstrate concepts described in this document using an Android sample app, an iOS sample app, and JavaScript in a sample web page:

User Sync for Desktop inventory

Use this method to add a video ad to your page when you want to sync with a user cookie on the client side. The cookie contains a JSON list of bidders ipassed from the URL query in the video ad iFrame:

User sync iFrame for video ads
<iframe title="User Sync" width=1 height=1
    sandbox="allow-same-origin allow-scripts"
    frameborder="0"
    src="https://ads.pubmatic.com/AdServer/js/pwtSync/load-cookie.html?pubid=5890&profid=2652&bidders=appnexus,audienceNetwork,pubmatic,rubicon,pulsepoint,indexexchange,districtm">
<iframe>

For desktop inventory, when the video player makes the XHR call to OpenWrap's endpoint (Step 2 in this document), the withCredentials property must be set to true in the XHR call so that cookies pass to the OpenWrap endpoint.

⇧ Top

Do you have feedback on this document? Let us know: email us.

Table of Contents

PRIVACY

OPT-OUT

TERMS OF SERVICE

PUBMATIC LEGAL POLICIES


Copyright © 2021 PubMatic, Inc. All Rights Reserved

This website uses cookies for analytics and personalization.  Click here  to learn more or change your cookie settings. By continuing to browse, you agree to our use of cookies.