Video VPAID Wrapper Implementation Guide
The video viewability offering using an IAS wrapped VAST/VPAID tag to be trafficked to publishers.
Overview
This document outlines the Integral Ad Science (IAS) video viewability offering using an IAS wrapped VAST/VPAID tag to be trafficked to publishers. You send an IAS original VAST file and any associated macros (unless you wish to fill them in yourself).
IAS now supports wrapper 3. The new Wrapper 3 brings several improvements including server-side processing of the original VAST that:
reduces latency by parsing and serving the original vast ourselves.
exposes more features of the original vast to the player (like companion banners).
Wrapper 3 uses ad parameters instead of query parameters, making it cacheable and with lower latency. You cannot directly call the wrapper with Wrapper 3.
Wrapper details
The following are the steps for generating Campaign Monitoring (CM) and Open Web wrapper tags:
You provide IAS with a VAST URL tag, along with any macros.
An IAS representative creates a VPAID wrapper tag using the VAST URL and all other inputs. An example VAST URL is http://www.samplevideoad.com/videoad1.xml
IAS returns a generated VPAID wrapped tag to the client for trafficking into video players.
CM Wrapper Tag
The CM Wrapper Structure:
http://vast.adsafeprotected.com?anId=[Client ID]&advId=[Advertiser ID]&campId=[Campaign ID]&pubId=[Publisher ID]&placementId=[Placement ID]&chanId=[Channel ID]&ias_xps=[Autoplayed or Not]&ias_xbp=[Break position]&ias_xar=[Autorefreshed or Not]&\originalVast=[VAST URL]&bidurl=[Sample bid URL]Note: the sample is formatted for readability; the sample must be on a single line.
Sample Tag
http://vast.adsafeprotected.com?anId=1111&advId=2222&campId=3333&pubId=4444&placementId=5555&ias_xps=autoplayed&ias_xbp=2&ias_xar=1&originalVast=http://www.samplevideoad.com/videoad1.xml&bidurl=http://www.samplebidurl.comNote: the sample is formatted for readability; the sample must be on a single line.
To understand the responses you will receive, you can refer to section 2.4.1 of the iab's VAST version 3.0 PDF guide here.
Attribution Specifications
The following table summarizes the values that you can populate using the macros available through the ad server. The UI labels all assigned macro names to the appropriate IAS / UI naming convention. If your taxonomy and syntax is different then you must make note of the mapping when referencing IAS Signal.
You can provide any attribution ID in their taxonomy required for UI Monitor reporting with one caveat: the ID cannot be a unique value (cookie, bid, user, or date/time ID). IAS supports up to 40 alphanumeric characters for all client provided ID attributes.
Note: Be certain to use the proper case for all IAS Named Parameters.
Information Type | IAS Named Parameter | Appears in UI as | IAS Specification |
Client ID | anId | Not Applicable (N/A) | Required. Integer, Provided by IAS |
VAST URL | originalVast | VAST URL Tag | Required. This must come last out of all the query parameters in the URL. URL pointing to the advertiser's VAST resource. If mediaUrl is used, the value for originalVast is not used and originalVast is not required. For example: &originalVast=http://www.samplevideoad.com/videoad1.xml |
Publisher ID | pubId | Primary Seller | Required. Alphanumeric, 40 character limit, Unique Value Limit = 5000 |
Autoplay Macro | ias_xps | Not in UI | Required. Possible values include: "autoplayed" or "clicktoplay" |
Break Position Macro | ias_xpb | Not in UI | Required. Possible values include: "1" - pre-roll, "2" - mid-roll, "3" - post-roll, "4" - stand-alone |
Autorefresh Macro | ias_xar | Not in UI | Required. Possible values include: "0" - false or "1" - true |
Campaign ID | campId | Campaign | Optional. Alphanumeric, 40 character limit, Unique Value Limit = 500 |
Advertiser ID | advId | Advertiser | Optional. Alphanumeric, 40 character limit, Unique Value Limit = 500 |
Channel ID | chanId | Secondary Seller | Optional. Alphanumeric, 40 character limit, Unique Value Limit = 5000 |
Placement ID | placementId | Ad Unit | Optional. Alphanumeric, 40 character limit, Unique Value Limit = 7500 |
Bid URL | bidurl | N/A | Optional Client can include a bid URL for post-bid delivery analysis |
Impression | ias_third_party | N/A | Optional. Allows for specifying a third party ad-tracking URI. |
<a name="Media_URL">Media URL | mediaUrl | N/A | Optional. Allows for specifying a video URL that will be played as the ad. Is disregarded when originalVast is passed. |
Click through URL | clickUrl | N/A | Optional. Allows for specifying a click-through URL. |
Firewall Server | fwServer | N/A | Used to set the domain and port of the server to the JSVID endpoint using the supplied value. "fwServer" is only for development and debugging and as such, only the anId and videoId are parameterized. For example: https://vast.adsafeprotected.com/vast?fwServer=staging-domain.com |
Include or exclude HTML5/JavaScript VPAID MediaFile node | includeHtml5 | N/A | Default = true, Includes the HTML5/JavaScript VPAID MediaFile node in the vast response when true. Removes the HTML5/JavaScript VPAID MediaFile node in the vast response when false. |
Include or exclude Flash VPAID MediaFile node | includeFlash | N/A | Default = false Includes the Flash/SWF VPAID MediaFile node in the vast response when true. Removes the Flash/SWF VPAID MediaFile node in the vast response when false. Note: Flash is deprecated. |
Wrapper 3 employs wrapping from Wrapper 2 | csw | N/A | Default = false When set to true, Wrapper 3 employs client-side wrapping from Wrapper 2. Client-side wrapping makes it possible for wrapped tags to support targeting based on users' IP or cookie data. Note: Enabling client-side wrapping will increase load times of the Wrapper 3 equivalent to load times of Wrapper 2. |
Separate options for VPAID wrapper | IAS_VID_OPTS | N/A | Pipe, |
Notes:
Client can assign any ID values up to 40 alphanumeric to these named value pairs. IAS recommends you pass publisher and campaign attributes.
You should remove empty parameters (get &).
Options for VPAID Wrapper
You can pass additional instructions (pipe, |, separated) through the IAS_VID_OPTS parameter for VPAID wrapper. For example:
http://...adsafeprotected.com/vast?IAS_VID_OPTS=frtimer|topleft&placementId=6&pubId=8&anId=7&advId=2&campId=3&chanId=5&ias_xps=autoplayed&ias_xbp=2&ias_xar=1&originalVast=https://www.abc.com/files/vastM.xmlNote: the sample is formatted for readability; the sample must be on a single line.
The full list of instruction options that can be sent via the IAS_VID_OPTS is as follows:
Parameter | Description |
continueonclick | When the user clicks-through, the ad continues playing (without pausing or stopping). |
hidecountdown | The counter and the ad message are hidden. |
frtimer | The counter and the ad message are in French. |
gertimer | The counter and the ad message are in German. |
topleftcount | The counter is positioned at the top-left corner of the video. |
topmiddlecount | The counter is positioned at the top, in the middle of the video. |
toprightcount | The counter is positioned at the top-right corner of the video. |
bottomleftcount | The counter is positioned at the bottom-left corner of the video. |
bottommiddlecount | The counter is positioned at the bottom, in the middle of the video (which corresponds to the default value of the counter). |
bottomrightcount | The counter is positioned at the bottom-right corner of the video. |
hideplaybutton | Hides the play button. |
Open Web Tag
The Open Web Tag Structure:
http://fw.adsafeprotected.com/vast/fwjsvid/st/[adv_entity_Id]/[pub_entity_Id]/skeleton.js?&ias_xps=[Autoplayed or Not]&ias_xbp=[Break position]&ias_xar=[Autorefreshed or Not]&originalVast=[VAST URL]Note: the sample is formatted for readability; the URL must be on a single line.
Sample Tag
http://vast.adsafeprotected.com?originalVast=http://www.samplevideoad.com/videoad1.xml&ias_xps=autoplayed&ias_xbp=2&ias_xar=1Note: the sample is formatted for readability; the URL must be on a single line.
To understand the responses you will receive, you can refer to section 2.4.1 of the iab's VAST version 3.0 PDF guide here.
Open Web Attribution Specifications
The following table summarizes the values that you can populate using the macros available through the ad server. The UI labels all assigned macro names to the appropriate IAS / UI naming convention. If your taxonomy and syntax is different then you must make note of the mapping when referencing IAS Signal.
Arguments | Type | Surfaced in IAS UI | Description |
advEntityId | String [Required] | Yes | Advertiser Entity ID provided to you by IAS |
pubEntityId | String [Required] | Yes | Publisher Entity ID provided to you by IAS |
ias_xps | String [Required] | No | Autoplay or click-to-play. Possible values include: "autoplayed" or "clicktoplay" |
ias_xpb | String [Required] | No | Break position (when in a video that ad played). Possible values include: "1" pre-roll, "2" - mid-roll, "3" - post-roll, "4" - stand-alone |
ias_xar | String [Required] | No | Autorefresh. Possible values include: "0" - false or "1" - true |
impId | String [Optional] | No | Unique impression ID for the ad session. Should be unique for each ad session across a campaign. Note: When diagnostic monitoring is enabled, the impId property is required for some monitoring at the ad session level. |
ias_dataSourceId | String [Optional] | No | Maps to the entity populating the macros; for example, the DSP or Creative Server. |
ias_advId | String [Optional] | No | Advertiser or Buyer ID. |
ias_campId | String [Optional] | No | Campaign associated to specific advertiser / buyer running multiple campaigns. |
ias_pubId | String [Optional] | No | Publisher or Seller ID. |
ias_placementId | String [Optional] | No | Ad unit or Placement or Creative ID. |
ias_chanId | String [Optional] | No | Secondary Seller or Channel ID. |
ias_creativeId | String [Optional] | No | Ad unit ID. |
ias_dealId | String [Optional] | No | The ID that is assigned to a Private Market place (PMP) deal upon its creation used to identify the deal between the buyers and sellers for both targeting and reporting. |
ias_bundleId | String [Optional] | No | Mobile application bundle ID (for mobile application impressions) |
ias_impId | String [Optional] | No | Unique event identifier assigned by client system. This information is suggested for all Segment API integrations, and optional for other integrations. |
ias_dataSourceId2 | String [Optional] | No | You can append a second set of data using the same macro names but with a "2" appended to the end of the ID. |
ias_advId2 | String [Optional] | No | |
ias_campId2 | String [Optional] | No | |
ias_pubId2 | String [Optional] | No | |
ias_placementId2 | String [Optional] | No | |
ias_chanId2 | String [Optional] | No | |
ias_creativeId2 | String [Optional] | No | |
ias_dealId2 | String [Optional] | No | |
ias_bundleId2 | String [Optional] | No | |
ias_impId2 | String [Optional] | No |
Metrics Collected
brand safety report
geographical analysis
ad fraud detection (Monitoring) report
contextual analysis
3MS viewability report
campaign viewability report
ad environment report
video viewability report (VPAID layered onto viewability)