OpenWrap for Video

OpenWrap simplifies the process of creating video ads by letting you define your ads using parameters added to your ad tag instead of creating a large block of HTML code. The data-flow for video ads in OpenWrap is nearly identical to that of standard ads, but has the addition of a cache server:

Currently, OpenWrap video ad tags work only with the GAM AdServer. To learn more about configuring OpenWrap with GAM, see the OpenWrap User Guide.

The process of defining a video ad in OpenWrap is to generate an ad tag as you normally would in GAM, and then append video-specific parameters to the tag. Your result might be similar to this:

OpenWrap Video API

The sections below provide details about the parameters and usage notes for building OpenWrap video ad tags in GAM AdServer.

DFP is now called, Google Ad Manager (GAM)…

When you see DFP mentioned in this guide, remember that it is referring to GAM.

GAM vs. OpenWrap Query Parameters

You will find that the table below also contains oRTB Video parameters for use in the GAM parameter list. You can send OpenWrap parameters to override the GAM value. For example, if you include only sz=300x250 in the GAM URL, that size populates the W and H parameters in the oRTB Video request. But if you also include pwtsz=<some other size>, then OpenWrap uses the size value from pwtsz.

oRTB Video Request parameterGAM parameterOpenWrap ParameterParameter TypeNotes
API
pwtvapi

BAttr
pwtbatr

BoxingAllowed
pwtbox

Delivery
pwtdvry

Hszpwtvsz
W and H would be provideed in pwtvsz or sz in the format: WxH
Linearityvad_typepwtvlin
linear=1,nar=2
MinBitrate
pwtmnbr

MaxBitrate
pwtmxbr

MinDurationmin_ad_durationpwtvmnd

MaxDurationmax_ad_durationpwtvmxd

MaxExtended
pwtmxex

Mimes
pwtmime

List of Integers; for example, pwtmime=1,2

Possible Integer values for pwtmime and their corresponding meaning:

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

PlaybackMethodvpmute, vpapwtplbk
  1. Vpmute=1 & vpa=0, ortb playback=2,6
  2. Vpmute=0 & vpa=1, ortb playback=1,2
  3. Vpmute=1 & vpa=1, ortb playback=2
  4. Vpmute=0 & vpa=0, ortb playback=<none selected>
Pos
pwtvpos

Protocol
pwtprot

Protocols
pwtprots

Sequence
pwtseq

Skip
pwtskp

SkipMin
pwtskmn

SkipAfter
pwtskat

StartDelayvpospwtdly
  • preroll=0
  • midroll=-1
  • postroll=-2
Wszpwtvsz
W and H would be provided in pwtvsz or sz in the format: WxH

User parameters supported

oRTB User request parameter

Type

OW parameter

User.yobintegerpwtyob
User.Genderstringpwtgender

Content parameters supported

oRTB Content request parameter

Type

OW parameter

Parameter type

Content.Genrestringpwtgenrestring
Content.Titlestringpwttitlestring

GDPR parameters supported

oRTB GDPR request parameter

Type

OW parameter

Notes

regs.ext.gdprInteger

pwtgdpr

Value indicating GDPR enabled or not
user.ext.consentstring

pwtcnst

Consent string

CCPA parameters supported

oRTB Content request parameter

Type

OW parameter

Notes

user.ext.us_privacystring

pwtccpa

ccpa string

In-App OTT header bidding

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 can be passed to the ad server. The following steps describe how to call this API and send the returned targeting keys to GAM. 

Step 1: Setup OpenWrap Profile

Create an OpenWrap profile with Video (VAST) 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&adserver=DFP&pwtplt=video&pwtmime=1&f=json&pwtm_iu=%2F40619304%2FOW_Video&pwtm_sz=640x480&pwtm_url=https%3A%2F%2Fwww.pubmatic.com.com%2F

The parameters for the OpenWrap video request are all sent as URL parameters. Accurate and complete video parameters are essential for achieving good yield. Please work with your PubMatic customer success manager to make sure you have the correct set of parameters.

If there is no bid the OpenWrap server will return still return a JSON document but your code should 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 the call doesn’t complete.  While OpenWrap will respect the timeout specified in the profile, the call from the client may not complete in the maximum time due network or other issues. 

 In addition to these in-app OTT parameters, you can refer to the GAM vs. OpenWrap Query Parameters parameters above.

These four parameters must be added manually. They are not added when the URL is generated the in the PubMatic OpenWrap UI.

In-app OTT parameter name

Type

Description

Example Value

f

String

Format of response to return.  

f=json

Note:

Pass this parameter to specify response format.

If value of this parameter is 'json' then response would be returned in JSON format containing only 'targeting' field.

For any value other than 'JSON', redirect response will be sent with redirect url, unless debug is true.

If value of this parameter is 'json' then 'owredirect' param is optional. If 'owredirect' parameter has not been passed then following additional parameters need to be passed:
'pwtm_iu' specifying inventory unit value
'pwtm_sz' specifying size value
'pwtm_url' specifying url value

These parameters are used for macro replacement and override values in owredirect if present.
If 'owredirect' & above parameters are passed then 'iu' value in 'owredirect' gets preference over 'pwtm_iu' value.
Other values (like 'pwtm_sz', 'pwtm_url' etc.) override corresponding parameter values in 'owredirect' and gets preference over them.

pwtm_iu


Inventory unit (ad unit)

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

As GAM ad unit ids have ‘/’, it’s important to correctly URL encode this value

pwtm_iu=%2F40619304%2FOW_Video

pwtm_sz


Video player size

pwtm_sz=640x480

pwtm_url


Page URL

 

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

pwtbidrprm Encoded JSON stringBidder specific key-value for AppNexus amn PubMatic.

Sample JSON with key-values:

Bidder JSON
{
	"pubmatic": {
		"keywords": [{
			"key": "dctr",
			"value": ["val1", "val2"]
		}]
	},
	"appnexus": {
		"keywords": [{
				"key": "key1",
				"value": ["val1", "val2"]
			},
			{
				"key": "key2",
				"value": ["val1"]
			}
		]
	}

}
pwtvapi
Use 7 to indicate OMID-1 (Open Measurement Support)pwtvapi=7

Step 3: Parse the response from OpenWrap

When bidding is successful, OpenWrap will return an HTTP 200 with JSON document.

The targeting keys for OpenWrap’s video bid are located under the targeting field in the returned JSON document.

Sample JSON:

{

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

    }

}

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

These instructions cover GAM. The concepts are the same for any other ad server, but the details of passing the targeting keys will differ for other ads servers. 

You'll need to take the targeting keys we get from OpenWrap and add them to the VAST ad tag URL that GAM will be called with.

Here’s an 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

Targeting keys are passed in the cust_params URL parameter.  cust_params contain the URL keys encoded as a url query string.  Since cust_params is part of a url query string itself, we have a url query string within a url query string.

Here’s an example GAM URL with 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

You'll notice the value of cust_params is %26; this value separates the different targeting keys. The %26 is a url encoded version of '&.

Because the value of cust_params requires two levels of url encoding, we recommend using a url code library to construct the url.

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

A good reference implementation for encoding targeting values into cust_params is Prebid.js

 Step 5: Pass augmented URL to Ads SDK 

The VAST url augmented with targeting keys is now passed to the video ads SDK as normal. In many cases, the ads SDK will be IMA, but this approach will work with other ads SDKs.

Additional Requirements:

For the ad server to utilize the targeting keys, line items need to be setup in the ad server.  Contact your PubMatic customer success manager to arrange for line item set up.

Mobile parameters support

The following parameters would be considered only when "pwtapp" query parameter is set to 1 , which indicates this is a mobile request (i.e. &pwtapp=1)

oRTB Video request parameterOW parameterParameter typeNotes

App.Id

pwtappid

String

App.Name

pwtappnameString

App.Bundle

pwtappbdlString
App.DomainpwtappdomString

App.StoreURL

pwtappurlString

App.Cat

pwtappcatArray of String

App.Paid

pwtapppdInteger
Device.LmtpwtlmtIntegerCan be either 1 or 0
Device.DntpwtdntIntegerCan be either 1 or 0

Device.JS

pwtjsInteger

Device.Ifa

pwtifaString

Device.DidSha1

pwtdidsha1String

Device.DidMd5

pwtdidmd5String

Device.DpidSha1

pwtdpidsha1String

Device.DpidMd5

pwtdpidmd5String

Device.MacSha1

pwtmacsha1String

Device.MacMd5

pwtmacmd5String

Device.Geo.Lat

pwtlatFloat

Device.Geo.Lon

pwtlonFloat

Device.Geo.Type

pwtgtypeInteger

Device.Geo.Country

pwtcntrString

Device.Geo.City

pwtcityString

Device.Geo.Metro

pwtmetString

Device.Geo.Zip

pwtzip

String

Device.Geo.UtcOffset

pwtutoInteger

User.ID

pwtuid

String

Sample 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&owredirect=https%3A%2F%2F
pubads.g.doubleclick.net%2Fgampad%2Fads%3Fiu%3D%2F15671365%2FVideohbHack
%26description_url%3Dhttp%253A%252F%252Ftimesofindia.com%3Fpwtv%3D1%26env%
3Dvp%26impl%3Ds%26correlator%3D%26tfcd%3D0%26npa%3D0%26gdfp_req%3D1%26output
%3Dvast%26sz%3D300x250%26max_ad_duration%3D%26url%3Dhttp%253A%252F%
252Ftimesofindia.com%26unviewed_position_start%3D1%26vpos%3Dpreroll%
26vad_type%3Dnar%26vpmute%3D1%26vpa%3D1

Macro Support

You can also send macros for GAM parameters as query parameters to the video endpoint. For example, sending pwtm_description_url=www.test.com would replace the description_url value in the GAM url, then use the same in constructing the oRTB Video object, and also update the GAM redirect URL with these values.

To send a macro for a given GAM parameter, use query parameter key, pwtm_<exact GAM parameter name>. For example,

http://ow.pubmatic.com/openrtb/2.5/video/?v=1&pwtm_description_url=www.abc.com ....

Debug Support

When a request is made to OpenWrap Video endpoint, it responds with a 302 redirect to the GAM URL. But sometimes, you may want to debug a particular request. You may enable debugging for an OpenWrap video request which would return a JSON response containing debug information. However, an important point to note here is: when debugging is enabled, the usual flow of redirection to GAM URL would NOT work and creative would not be rendered.

To enable debugging, you may follow these steps:
1. Use macro to set pwtm_url query parameter in the Video endpoint dynamically.
2. Add logic to always set page URL in pwtm_url macro before making a call to Video endpoint. This way any query parameters added to the page URL would be set in pwtm_url value.
3. When you want to enable debugging, add query parameter pwtvc=1 in the page URL. This would be replaced in the pwtm_url macro with the above logic and Video endpoint would respond with debug response.

Sample Video endpoint call with pwtm_url macro along with macros for a few other GAM parameters like sz, vpos, vtype:

http://ow.pubmatic.com/openrtb/2.5/video/?v=1&pubId=5890&profId=1294&
pwtmime=1&owredirect=https://pubads.g.doubleclick.net/gampad/ads?
correlator=19812761&iu=/15671365/MG_VideoAdUnit&env=vp&gdfp_req=1&
output=vast&sz=640x480&description_url=http%3A%2F%2Fwww.test.com?
pwtv=1&tfcd=0&npa=0&vpmute=0&vpa=0&vtype=linear&url=http%3A%2F%2F
www.test.com&vpos=preroll&unviewed_position_start=1&pwtm_url=%%URL%
%&pwtm_sz=%%SIZE%%&pwtm_vtype=%%VTYPE%%&pwtm_vpos=%%VPOS%%

Here is a sample code snippet that replaces pwtm_url macro dynamically with the page URL.

Example Debug Support
< script type = "text/javascript" >

    function makeRequest() {

        var url = document.getElementById("tag").value;
        var size = document.getElementById("size").value;
        var vtype = document.getElementById("vtype").value;
        var vpos = document.getElementById("vpos").value;

        var pageURL = window.location.toString();

        url = url.replace("%%URL%%", pageURL);
        url = url.replace("%%SIZE%%", size);
        url = url.replace("%%VTYPE%%", vtype);
        url = url.replace("%%VPOS%%", vpos);

        var xhttp = new XMLHttpRequest();

        xhttp.onreadystatechange = function() {
            if (this.readyState == 4 && this.status == 200) {
                document.getElementById("op").innerHTML = this.responseText;
            }
        };

        xhttp.open("GET", url, true);
        xhttp.send();
    }

< /script>

User Sync

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 will contain a list of bidders in JSON format passed from the URL query in the video ad iFrame:

OpenWrap Video iFrame With User Cookie Sync
<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>

Sample HTML

Your full page implementation might look something like this:

Video Ad Page With User Cookie Sync
<!DOCTYPE html>
<html>
  <head>
    <link rel="icon" type="image/png" href="/favicon.png">
    <!-- This page is an example of prebid and JWPlayer integration with
    a JWPlayer playAd call once the player is ready for playback -->
    <meta charset="utf-8" />
    <title>OpenWrap S2S Video -- JW V8 Player</title>
    <script type="text/javascript" src="http://ssl.p.jwpcdn.com/player/v/8.0.5/jwplayer.js"></script>
    <script type="text/javascript">
        jwplayer.key="F4+phNkFZ4+I3UhfSN6h8JPbxdnsto3caVMq+A==";
    </script>
</head>
<body>
  <h1>OpenWrap S2S Video - JW Player 8</h1>
  <br>
  <div id="playerContainerJW" style='width:640px; height:480px; border:1px solid black;'></div>
  <script>
      var jwPlayerInstance = jwplayer("playerContainerJW");
    jwPlayerInstance.setup({
        "file": "//content.jwplatform.com/videos/1g8jjku3-cIp6U8lV.mp4",
        "image": "//content.jwplatform.com/thumbs/1g8jjku3-720.jpg",
        "primary": "html5",
        "advertising": {
            // Replace AdServer url with OpenWrap url
            "tag": "http://172.16.4.192:8787/openrtb/2.5/video/?v=1&pubId=64195&profId=2327&pwtmime=1&pwtgdpr=1&pwtcnst=testconsentstring&owredirect=https%3A%2F%2Fpubads.g.doubleclick.net%2Fgampad%2Fads%3Fcorrelator%3D19812761%26iu%3D%2F15671365%2FMG_VideoAdUnit%26env%3Dvp%26gdfp_req%3D1%26output%3Dvast%26sz%3D640x480%26description_url%3Dhttp%253A%252F%252Fwww.test.com%3Fpwtv%3D1%26tfcd%3D0%26npa%3D0%26vpmute%3D0%26vpa%3D0%26vad_format%3Dlinear%26url%3Dhttp%253A%252F%252Fwww.test.com%3Fpwtv%3D1%26vpos%3Dpreroll%26unviewed_position_start%3D1",
            //"tag":"//support-static.jwplayer.com/content/advertising/vpaid-2-test.xml",
            "client": "googima",
            "vpaidmode": "disabled"
        },
        "autostart": true
    });
  </script>
   <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>
</body>
</html>

Limitations

OpenWrap for Video Ads does not currently support Companion Ads.