Web Video SDK Self-Serve Upgrade Instructions
Partners who want to use the Integral Ad Science (IAS) web video SDK must validate their integrations through a certification process which lessens the metric discrepancy rate.
Overview
Partners who want to use the Integral Ad Science (IAS) web video SDK must validate their integrations through a certification process which lessens the metric discrepancy rate. Since IAS wants to get your integration certified as quickly as possible, these web video SDK self-serve upgrade instructions allow you to test your previously certified integration with the latest web video SDK before formally starting the IAS certification process.
With these instructions, you can uncover and resolve issues on your own, thus lowering the iteration cycle of the 'submit to IAS, wait for the results, fix uncovered issues, resubmit until there aren't any issues'.
Process to release an integration before the web video SDK self-serve instructions:
Process to release an integration with the web video SDK self-serve instructions:
These instructions support testing your web video SDK integration for IAS Campaign Monitoring (CM) and Open Web Blocking tags. IAS allows you to test your integration either through code changes or the Charles Web Proxy Tool.
Whereas the code changes entail configuring your integration to use test servers, using Charles (and a supplied configuration file) overwrites your integration to use a test domain and doesn't require code changes.
Configuring with this specific domain allows the self-serve upgrade instructions to print log messages to a browser's developers console. The test is to play your normal ad for various test scenarios. When your test passes, the browser's developer tools console logs:
WEB VIDEO INSPECTOR: Test SESSION PASSED Congratulations! Your integration satisfies certification requirements in this test case.The self-serve upgrade instructions involves:
Test scenarios
Configuration
Dispatcher
Code (Non-interactive and interactive) or
Charles Non-interactive and interactive
Output review
Validation in various environments
Note: IAS must whitelist your IP addresses prior to when you perform the self-serve upgrade test. Therefore, tell your IAS Technical Solutions engineer the IP addresses running the tests.
See the web video SDK documentation for more information on using the API.
Test Scenarios
Test creatives should represent the full range of ad formats that the integration supports. Play your test creatives through the full ad cycle in multiple players, browsers, OS's, devices, and play behavior.
When you play the creative, all video events received by IAS's listener are logged to the browser's console. IAS expects you to execute test cases which validate the following scenarios for the various environments:
Scenario | Description |
Play | This scenario entails playing a video ad. |
Block | This scenario expects IAS to return a blocking recommendation to block the ad. |
Timeout | This scenario ensures a time out before receiving a blocking recommendation. In this scenario, the ad starts, however before IAS returns a blocking recommendation, your timeout expires and you play the ad. |
CM A scenario might have a non-interactive and an interactive mode. Interactive mode expects interaction events which are sent because a user interacted with the video ad. For example, a user clicks the pause button.
Scenario | Non-interactive | Interactive |
Play | Yes | Yes |
Block | Not applicable | Not applicable |
Timeout | Not applicable | Not applicable |
FW
Scenario | Non-interactive | Interactive |
Play | No | Yes |
Block | Yes | No |
Timeout | Yes | No |
Configurations
Follow the instructions to test your integration through either a code change or Charles configuration.
Dispatcher
IAS created a Dispatcher to ensure test sessions are sent successfully to IAS. You must use the Dispatcher when testing cross-domain iframe scenarios (such as tests in Google IMA player with VPAID mode enabled), or IAS will not be able to save your results. In order to use the Dispatcher, inject the Dispatcher into your page:
If you are testing on a test page you don't control, navigate to https://webvideoinspector.adsafeprotected.com/tools/injectionSnippet. Follow the instructions there to inject.
If you are testing on a test page you do control, copy and paste the following script tag into the header of your page:
<script type="text/javascript" src="https://webvideoinspector.adsafeprotected.com/tools/dispatcher"></script>Note: If you are testing on a mobile device, you can access the mobile browser's console on a desktop browser via remote debugging.
See that the console logs the following which signals the script loaded properly:
WEB VIDEO SDK INSPECTOR: IAS Web Video SDK Inspector v{version} has loaded and is ready to validate your integration.You can run your tests sessions as usual once the Inspector Dispatcher loads successfully.
Code
Before you perform the test scenarios, you must configure your integration. The code changes required for configuring your tests are confined to the section where you instantiate the web video SDK and initialize it in CM or Open Web mode for an ad session. Throughout this process, the part of your integration code where you call sendEvent() and provide events/event data to IAS should remain untouched. After passing your tests with the web video SDK self-serve upgrade instructions, please make sure you change back to the non-test (production) configuration and let an IAS representative smoke test your non-test implementation prior to proceeding to the beta/volume test stage.
Your integration needs to use the domain 'webvideoinspector.adsafeprotected.com' in the __IASVANS constructor to use the self-serve upgrade, as shown on the right.
var myVANSInstance = new __IASVANS('webvideoinspector.adsafeprotected.com');When initializing the config object for testing your implementation, you need to use these test specific properties:
expectedInteractions
vastUrl
player
logTestResults
Config property | Type | Description |
expectedInteractions | Array of strings | An array of string values for possible interactions events you expect the integration to support. See the section on Expected Interactions for more information. |
vastUrl | String | String value of the URL of the VAST or VPAID creative you are testing. This value is used so IAS can troubleshoot if needed. For example, 'https://hello.com/vast.xml' |
player | String | String value for the player used in the test. Options include: 'Google IMA Player', 'JW Player', or your own player. Consistently pass the same value for all tests executed in a given player. |
logTestResults | Boolean | Boolean value whether to send test results to IAS. |
The following properties are re-purposed for testing and therefore are used differently than as documented in the web video SDK documentation:
Config property | Type | Description |
advEntityId | String | String value re-purposed for Open Web testing which specifies the test scenario ID. The advEntityId sets the events the web video SDK self-serve upgrade instructions expect. You can set advEntityId to: 'blockAd', 'playAd', or 'timeout' |
pubEntityId | String | String value used if you are running a timeout scenario. The value, in milliseconds, of the delay you want before the blocking response is returned. Set pubEntityId to a value greater than the maximum timeout you wait for a blocking recommendation from IAS before playing the ad. |
Once the test configuration changes are done, you can validate your updated integration by generating test creatives containing the web video SDK integration and pass in arbitrary IDs (when your integration is in production, these IDs are values you supply to IAS in the configuration).
You can view the web video SDK output from your test creatives/player integration in your browser console. Before running the test scenarios, open the browser's developer tools and display the console to see the result of the test. Additionally, use the console logs which list the IAS events to aid with debugging.
Play
This test case is applicable for CM and Open Web integrations and involves playing the ad after you made the following code changes:
initialize (if FW) advEntityId to playAd
set expectedInteractions depending on the mode
set the vastUrl, player according to the tested environment
set logTestResults if you want this test session to count toward your certification
run the test
Initialization
When instantiating __IASVANS in a production environment, use 'new __IASVANS()'; while testing, use new __IASVANS('webvideoinspector.adsafeprotected.com');. The CM and Open Web constructors (config object) are unchanged from version 3.5.0.
CM initialization
// Instantiate VANS with the URL for the Web Video SDK Inspectorvar cmInstance = new __IASVANS('webvideoinspector.adsafeprotected.com');// Create a configuration for your test casevar config = { partner: 'YOUR-IAS-PROVIDED-PARTNER-CODE', anId: 'YOUR-IAS-PROVIDED-AD-NETWORK-ID', advId: 'SOME-ADVERTISER-ID', campId: 'SOME-CAMPAIGN-ID', expectedInteractions: [depends on mode], vastUrl : 'https://mydomain.com/testvasttag.xml', // the VAST URL of the creative (VAST or VPAID) you are testing player: 'Google IMA' // the player you are using to test the integration logTestResults: true //must be set to true for IAS to receive your test results};// Initialize VANS as CMcmInstance.initCM(config, adNode); // adNode should be a reference to thevideo element for your ad (or slot in the case of a VPAID)Open Web initialization
// Instantiate VANS with the URL for the Web Video SDK Inspectorvar fwInstance = new __IASVANS('webvideoinspector.adsafeprotected.com');// Create a configuration for your test casevar config = { partner: 'YOUR-IAS-PROVIDED-PARTNER-CODE', advEntityId: 'playAd', pubEntityId: 'SUPPY-SOME_ARBITRARY_PUB-ENTITY-ID', expectedInteractions: [must be interactive], // the VAST URL of the creative (VAST or VPAID) you are testing vastUrl: 'https://mydomain.com/testvasttag.xml', player: 'Google IMA' // the player you are using to test the integration logTestResults: true //must be set to true for IAS to receive your test results};// Initialize VANS as FW// adNode should be a reference to the video element for your ad (or slot in the case of a VPAID). block should be a blocking callback (no change needed for testing setup) - refer to the implementation guide for detailsfwInstance.initFW(config, adNode, block);Expected Interactions
Configure your integration for the non-interactive and interactive cases.
Mode | Non-Interactive | Interactive |
CM | Yes | Yes |
Open Web | No | Yes |
You need to test all interaction you expect your integration to measure. IAS supports the following 7 interactions:
'pause/play'
'skip'
'mute/unmute'
'click/pause/play' (to test clickthrough interactions in environments where clicking is followed by an automatic pausing of the video)
'click' (to test clickthrough interactions in environments where clicking isn't followed by an automatic pausing of the video)
'enter/exitfullscreen'
'volumechange'
Non-interactive mode
expectedInteractions=[],Interactive mode
This is for CM and FW. You need to customize depending on your integration and the device. For example, if ads automatically pause the ad when clicked, you need to test 'click/pause/resume'. See the section on Expected Interactions for more information.
expectedInteractions: ['click/pause/resume', 'enter/exitfullscreen', 'mute/unmute', 'skip'],Run the test
Open the browser's developer tools and display the console to see the result of the test. Then play the ad creative.
If you are testing interaction events:
Play the ad
pause the ad *
resume the ad *
enter into full screen *
return to normal size *
mute the volume *
unmute the volume *
change the volume *
click skip *
* Perform this step before the third quartile.
Look in the console whether the test passed or failed.
Repeat this test, changing the initialization and expected events depending on the environment and mode you are testing.
Block
This test case is applicable for Open Web integrations only and involves attempting to play a video with an ad but IAS returns a blocking recommendation to block the ad. Your integration then blocks playing the ad.
Mode | Non-Interactive | Interactive |
CM | Not applicable | Not applicable |
Open Web | Yes | No |
You need to make the following code changes:
initialize via Open Web using advEntityId set to blockAd
set expectedInteractions for non-interactive mode
set the vastUrl, player, and logTestResults according to the tested environment
run the test
Initialization
// Instantiate VANS with the URL for the Web Video SDK Inspectorvar fwInstance = new __IASVANS('webvideoinspector.adsafeprotected.com');// Create a configuration for your test casevar config = { partner: 'YOUR-IAS-PROVIDED-PARTNER-CODE', advEntityId: 'blockAd', pubEntityId: 'YOUR-IAS-PROVIDED-PUB-ENTITY-ID', expectedInteractions: [], // simply a vanilla playthrough; no user interactions expected because the ad is blocked. // the VAST URL of the creative (VAST or VPAID) you are testing vastUrl: 'https://mydomain.com/testvasttag.xml', player: 'Google IMA' // the player you are using to test the integration logTestResults: true //must be set to true for IAS to receive your test results};// Initialize VANS as FW// adNode should be a reference to the video element for your ad (or slot in the case of a VPAID). block should be a blocking callback (no change needed for testing setup) - refer to the implementation guide for detailsfwInstance.initFW(config, adNode, block);Run the test
Open the browser's developer tools and display the console to see the result of the test. Then play the ad creative and look in the console whether the test passed or failed. Repeat this test, changing the initialization depending on the environment and mode you are testing.
Timeout
This test case is applicable for Open Web integrations only and simulates a network delay causing a timeout before IAS's recommendation to block the ad returns.
Mode | Non-Interactive | Interactive |
CM | Not applicable | Not applicable |
Open Web | Yes | No |
You need to make the following code changes:
initialize via Open Web using advEntityId set to timeout and set pubEntityId to 5000 (a value in milliseconds great enough to time out your integration for a blocking response )
set expectedInteractions for non-interactive mode
set the vastUrl, player, and logTestResults according to the tested environment
run the test
Initialization
// Instantiate VANS with the URL for the Web Video SDK Inspectorvar fwInstance = new __IASVANS('webvideoinspector.adsafeprotected.com');// Create a configuration for your test casevar config = { partner: 'YOUR-IAS-PROVIDED-PARTNER-CODE', advEntityId: 'timeout', pubEntityId: '5000', expectedInteractions: [], // the VAST URL of the creative (VAST or VPAID) you are testing vastUrl: 'https://mydomain.com/testvasttag.xml', player: 'Google IMA' // the player you are using to test the integration logTestResults: true //must be set to true for IAS to receive your test results};// Initialize VANS as FW// adNode should be a reference to the video element for your ad (or slot in the case of a VPAID). block should be a blocking callback (no change needed for testing setup) - refer to the implementation guide for detailsfwInstance.initFW(config, adNode, block);Expected Interactions
Run this Open Web only test scenario in non-interactive mode:
expectedInteractions=[],Run the test
Open the browser's developer tools and display the console to see the result of the test. Then play the ad creative and look in the console whether the test passed or failed. Repeat this test, changing the initialization depending on the environment and mode you are testing.
Charles
Download the Charles Proxy Setup settings files at:
https://webvideoinspector.adsafeprotected.com/tools/charles-cm.xml
https://webvideoinspector.adsafeprotected.com/tools/charles-fw.xml
Contact your IAS Client Services representative if you have any problems accessing the Charles Proxy Setup settings file for non-interactive and interactive scenarios. Refer to your Charles Proxy instructions for detailed instructions to use Charles.
1) Import the Charles rules (Charles > Tools > Import/Export Settings... > then browse for the settings file.)
2) Confirm the settings file import worked. Select Tools > Map Remote ...:
3) Confirm your SSL Proxy Settings includes pixel.adsafeprotected.com in the Tools > SSL Proxying Settings...
4) To validate your configuration with Charles is correct, go to https://pixel.adsafeprotected.com/jsvid then in the browser's developer tools console, find 'token:':
Note: Be certain to accept the security certificate per browser.
Tip: ensure the Firefox preference is enabled to 'Use system proxy settings'.
Charles has Rewrite Settings which lets you select a test scenario and a player (either JW Player, IMA Player or a Custom Player). If you use a player other JW Player and IMA Player, select Custom Player and then modify the rule to supply the player's value.
Play
This test case is applicable for CM and Open Web integrations and involves playing the ad once you configured your Charles settings as follows.
In Charles, select the test case, whether for non-interactive or interactive mode. Once you select the appropriate configuration in Rewrite Settings, then you can play the ad.
Mode | Non-Interactive | Interactive |
CM | Yes | Yes |
Open Web | No | Yes |
Non-interactive mode
This mode is for CM test scenarios only; click Tools > Rewrite in Charles, then select the player and the test scenario:
Interactive mode
This mode is for CM and Open Web test scenarios.
CM
Click Tools > Rewrite in Charles, then select the player and the test scenario:
FW
Click Tools > Rewrite in Charles, then select the player and the test scenario:
Run the test
Open the browser's developer tools and display the console to see the result of the test. Then play the ad creative.
If you are testing interaction events (if you are not testing the following scenario, you need to create a customized Charles Tools > Rewrite file. See the section on Expected Interactions for more information.):
Play the ad
pause the ad *
resume the ad *
enter into full screen *
return to normal size *
mute the volume *
unmute the volume *
change the volume
click skip *
* Perform this step before the third quartile.
Look in the console whether the test passed or failed.
Repeat this test on all environments and change the Rewrite settings selection for either the non-interactive or interactive mode.
Block
This test case is applicable for Open Web integrations only and involves attempting to play a video with an ad but IAS returns a blocking recommendation to block the ad. Your integration then blocks playing the ad.
In Charles select the test case. Once you selected the Rewrite Settings, then you can play the ad.
Mode | Non-Interactive | Interactive |
CM | Not applicable | Not applicable |
Open Web | Yes | No |
Non-interactive mode
In Charles, click Tools > Rewrite, then select the player and the test scenario:
Run the test
Open the browser's developer tools and display the console to see the result of the test. Look in the console if the test passed or failed.
Then play the ad creative and look in the console whether the test passed or failed. Repeat this test on all environments.
Timeout
This test case is applicable for Open Web integrations only and simulates a network delay causing a timeout before IAS's recommendation to block the ad returns.
Mode | Non-Interactive | Interactive |
CM | Not applicable | Not applicable |
Open Web | Yes | No |
In Charles select the test case. Once you selected the Rewrite Settings, then you can play the ad.
Non-interactive mode
In Charles, click Tools > Rewrite, then select the player and the test scenario:
Run the test
Open the browser's developer tools and display the console to see the result of the test. Then play the ad creative and look in the console whether the test passed or failed. Repeat this test on all environments.
Outputs
Once the integration is configured to use the self-serve upgrade environment, you can see events sent to the web video SDK self-serve upgrade logged to the browser console. When your test passes, the browser's developer tools console logs:
` WEB VIDEO INSPECTOR: Test SESSION PASSED
Congratulations! Your integration satisfies certification requirements in this test case. `
The web video self-serve upgrade instructions sends IAS events to the browser console.
Environments
To ensure the integration works as intended prior to certification, test the integration on a range of environments which cover the following scenarios:
a combination of the latest players, operating systems, browsers, and devices
cross-domain and friendly iframes
measurement on the last ad in an ad break (to ensure all events are sent to the IAS listener before ad is unloaded)
When running tests, ensure:
disable ad blockers
enable JavaScript
allow pop-ups
accept certificates
Reminder, Google Chrome and Safari do not auto-play if the sound is not muted.
Players:
Google IMA (in secure and VPAID enabled mode)
JW Player
Mac OS (latest version of each browser):
Chrome
Firefox
Safari
Windows (latest version of each browser):
IE11
Firefox
Chrome
Edge
Mobile devices and browsers:
iOS - Mobile Safari
Android - Chrome Mobile
Modes:
Non-interactive
Interactive
Expected Interactions
Use the following table to customize your expected interactions.
Scenario name | When to include | VPAID events | Steps to execute |
'click/pause/resume'' | Ad supports click and automatically pauses video. Ad is resumed by user. | AdClickThru, AdPaused, AdPlaying | 1. Click on ad 2. Return to ad and resume |
'click' | Ad supports click but does not automatically pause video (mutually exclusive with 'click/pause/resume', depending on what your page supports). | AdClickThru | Click on the ad. |
'pause/play' | Player exposes a pause/resume control | AdPaused, AdPlaying | 1. Pause the ad 2. Resume the ad |
'volumechange' | Player exposes a pause/resume control. | AdVolumeChange | Adjust volume (without muting. Also click to the desired volume, as sliding could trigger many duplicate volume change events) |
'mute/unmute' | Player exposes a pause/resume control. | AdVolumeChange | 1. Toggle mute 2. Untoggle mute |
'enter/exitfullscreen' | Player enables you to expand the ad to fullscreen and collapse back to normal view mode. | resizeAd (Web Video SDK-specific event) | 1. Toggle fullscreen expansion 2. Toggle collapse back to normal view mode |
'skip' | VPAID ad is skippable. | AdSkipped | Skip the ad. |
Frequently Asked Questions:
Q: Does using the self-serve upgrade instructions to move the integration into production (without certification) still mean that the reporting/data is MRC accredited?
Yes, after successfully performing the self-serve upgrade instructions, but without IAS Certification, IAS reporting is still MRC accredited.
When instantiating the web video SDK without the self-serve domain (webvideoinspector.adsafeprotected.com), does IAS expect an empty string: new __IASVANS(''");?
No, use new __IASVANS();
Has the Campaign Monitoring (CM) config object changed from v3.5.0?
No
Should you run a full regression on each code change?
You need to run a full regression for major code changes on your side. For example, a change within the player API, a new video product like live streaming or a new ad unit like skippable mid-roll.
What should you troubleshoot when the SDK inspector isn't loading when using Charles?
Make sure you navigated to the web video inspector URL and accept all security cert overrides.
What is an interaction event?
An interaction event is an event sent because a user interacted with the video. For example, if you click on the 'Skip Ad' banner, you get the AdSkipped interaction event.