Conviva Xbox One/Windows 10: WinJS Sensor Integration

Conviva initialization is a one-time call that must occur at the earliest possibility in your application's initialization flow.

ConvivaUWP.WinClient.init( customerKey, winSettings ):

• customerKey: string to identify specific customer account. Different keys shall be used for development / debug versus production environment. Find your keys on the account info page in Pulse;

• winSettings: ConvivaUWP.WinSettings(); settings to enable debug.

No need to set gatewayUrl and LogLevel settings for your production release explicitly. The Conviva sensor has the right default value.

The allowed parameters are:

• winSettings.setGatewayUrl: once enabled, the data will appear in Pulse for performing self-validation of video sensor integration. For more information, see Self-validation using Touchstone.

• winSettings.setLogLevel: set to ConvivaUWP.LogLevel.debug for debug-level log verbosity.

Sample code illustrating initialization with/without debug:

//test or dev phase
var customerKey = TEST_CUSTOMER_KEY;
var winSettings = new ConvivaUWP.WinSettings();
winSettings.setGatewayURL(TOUCHSTONE_SERVICE_URL);
winSettings.setLogLevel(ConvivaUWP.LogLevel.debug);
ConvivaUWP.WinClient.init( customerKey, winSettings );

//production release
var customerKey = PRODUCTION_CUSTOMER_KEY;
var winSettings = new ConvivaUWP.WinSettings();
ConvivaUWP.WinClient.init( customerKey, winSettings );

IMPORTANT: No need to set GatewayUrl and LogLevel settings for your production release. The Conviva library provides the default values for production.

Expected Errors Due to Dual Stack IPv4/v6 Network Support

When the Conviva sensor is initialized with production settings, the SDK sends a single request to the endpoints below:

• [customer_key].ipv4.cws.conviva.com for IPv4 only

• [customer_key].ipv6.cws.conviva.com for IPv6 only

Sending both requests enables correlation of IPv4 and IPv6 addresses in dual-stack networks. If only IPv4 or IPv6 addressing is used (single-stack networking), it is expected that one request will fail. All the following requests will be sent to the endpoint below which supports both IPv4 and IPv6:

• [customer_key].cws.conviva.com

The main purpose of Conviva Integration is to measure the quality of experience by monitoring videos from the moment user initiates playback. Use the following method create session to monitor video playback:

• contentInfo: object carries on metadata associated with the video playback.

• jsNotifier: wrap the player with a monitoring proxy videoElementStreamerProxy.GetJSNotifier();

The keys / methods and expected values of the required metadata tags are defined in the Implement Metadata section below.

IMPORTANT: ConvivaUWP.WinClient.createSession() API returns session ID which shall be stored till session lifecycle and shall be used for session specific API's.

ConvivaUWPJS.VideoElementConvivaStreamerProxy is provided in the JS library to get important metrics from the

function playVideo() {

this.player = document.getElementById("video_player");

// WinContentInfo Metadata Creation Block
var contentInfo = new ConvivaUWP.WinContentInfo();

// required: unique value for every asset
if (assetName != null) {
contentInfo.setAssetName(assetName);

// Add the contentInfo as required
...


// Wrap the player with a monitoring proxy
this.videoElementStreamerProxy = new ConvivaUWPJS.VideoElementConvivaStreamerProxy( this.player );

var jsNotifier = this.videoElementStreamerProxy.GetJSNotifier();

// Create a monitoring session and keep a reference to its ID
// Attach the JsNotifier from proxy to the monitoring session
// WinClient.createSession() will return an integer 0 or greater
// this.player is also known as streamer
this.sessionId = ConvivaUWP.WinClient.createSession(contentInfo, jsNotifier);

// Finish player initialization for mp4
this.player.src = videoURL;

// If you use AdaptiveMediaSource for HLS/DASH, your code should be similar to the following:
//this.player.src = URL.createObjectURL(mediaSource, { oneTimeOnly: true });
// Also media source has to be notified to streamer proxy in order to monitor HLS bitrate and errors.
// this.videoElementStreamerProxy.setMediaSource(mediaSource);

// If you want to remove media source from streamer proxy do this:
//  this.videoElementStreamerProxy.cleanupMediaSource(mediaSource);

}

IMPORTANT: It's critical to make this API call correctly to monitor video experience - monitoring session created from this moment, and key metrics are captured based on this event. For example, if this call done late (say, when video starts rather than user clicks "play"), the Video Startup Time will be under-reported, Video Start Failures will be missed, etc.

Please note that each video should be monitored separately - call this method for each new video played.

IMPORTANT: If some of the content metadata tags aren't available at start, they can be set later or amended by ConvivaUWP.WinClient.updateContentInfo(this.sessionId, contentInfo); API - refer here for details. Please note, in most cases that it's required to set content metadata before the player reports "play" for the first time, to accurately attribute metadata to the video asset.

In certain scenarios, you create a video session but attach your player instance at a later stage, after checking for any errors that might occur after session creation but before streamer attachment. This is common when you use a DRM, when you create the player/streamer instance after a successful DRM validation. In such cases, you still create the monitoring session with its metadata as soon as the user has expressed intent to play the video (whether via auto-play or manually) but you attach your player/streamer instance via another method call, after manually reporting any errors that may have prevented successful playback. We count these errors with their corresponding messages - as Video Start Failures (VSFs).

If you are using AdaptiveMediaSource for HLS/DASH (like in Microsoft example), before setting it as src to the

Your code will look similar to:

function playVideo() {
// WinContentInfo Metadata Creation Block
var contentInfo = new ConvivaUWP.WinContentInfo();

// required: unique value for every asset
if (assetName != null) {
contentInfo.setAssetName(assetName);
}

// Add the contentInfo as required
...

// Wrap the null player with a monitoring proxy
this.videoElementStreamerProxy = new ConvivaUWPJS.VideoElementConvivaStreamerProxy(null);

var jsNotifier = this.videoElementStreamerProxy.GetJSNotifier();

// Create a monitoring session and keep a reference to its ID
// LivePass.createSession() will return an integer 0 or greater
// this.player is also known as streamer
this.sessionId = ConvivaUWP.WinClient.createSession( contentInfo, jsNotifier );

// Perform your extra logic (e.g., DRM check)
...

// If a fatal error preventing playback is encountered,
// report it manually and clean up the monitoring session
if ( fatalErrorEncountered ) {
ConvivaUWP.WinClient.reportError( this.sessionId, "Your error message", ConvivaUWP.WinErrorSeverity.fatal);
ConvivaUWP.WinClient.cleanupSession( this.sessionId );
return;
} else {
this.player = document.getElementById("video_player");

// Detach the JS Notifier with null player
ConvivaUWP.WinClient.detachJSNotifier( this.sessionId );

// Wrap the player with a monitoring proxy
this.videoElementStreamerProxy = new ConvivaUWPJS.VideoElementConvivaStreamerProxy(this.player);

var jsNotifier = this.videoElementStreamerProxy.GetJSNotifier();

// Attach the JsNotifier from proxy to the monitoring session
ConvivaUWP.WinClient.attachJSNotifier( this.sessionId, jsNotifier);

// Finish player initialization for mp4
this.player.src = videoURL;

// If you use AdaptiveMediaSource for HLS/DASH, your code should be similar to following
//this.player.src = URL.createObjectURL(mediaSource, { oneTimeOnly: true });
// Also media source has to be notified to the streamer proxy
//in order to monitor HLS/DASH bitrate and errors.
// this.videoElementStreamerProxy.setMediaSource(mediaSource);

// If you want to remove media source from the streamer proxy do this:
// this.videoElementStreamerProxy.cleanupMediaSource(mediaSource);
}
}

Report end of playback by using the method:

ConvivaUWP.WinClient.cleanupSession( sessionId );
sessionId = -1;
// Don’t forget to cleanup streamer proxy instance.
videoElementStreamerProxy.Cleanup();
videoElementStreamerProxy = null;