Conviva JavaScript Quick Integration

Initialize the top level Conviva Analytics object:

Conviva.Analytics.init(/* string / customerKey, / object / callbackFunctions, / object */settings=):

Click the arrow to view the reference implementation:

var callbackFunctions = {};
 
callbackFunctions[Conviva.Constants.CallbackFunctions.CONSOLE_LOG] = function (message, logLevel) {
    if (typeof console === 'undefined') return;
    if (console.log && logLevel === Conviva.Constants.LogLevel.DEBUG ||
        logLevel === Conviva.Constants.LogLevel.INFO) {
        console.log(message);
    } else if (console.warn && logLevel === Conviva.Constants.LogLevel.WARNING) {
        console.warn(message);
    } else if (console.error && logLevel === Conviva.Constants.LogLevel.ERROR) {
        console.error(message);
    }
};
 
callbackFunctions[Conviva.Constants.CallbackFunctions.MAKE_REQUEST] = function (httpMethod, url, data, contentType, timeoutMs, callback) {
    var xmlHttpReq = new XMLHttpRequest();
 
    xmlHttpReq.open(httpMethod, url, true);
 
    if (contentType && xmlHttpReq.overrideMimeType) {
        xmlHttpReq.overrideMimeType = contentType;
    }
    if (contentType && xmlHttpReq.setRequestHeader) {
        xmlHttpReq.setRequestHeader('Content-Type', contentType);
    }
    if (timeoutMs > 0) {
        xmlHttpReq.timeout = timeoutMs;
        xmlHttpReq.ontimeout = function () {
            // Often this callback will be called after onreadystatechange.
            // The first callback called will cleanup the other to prevent duplicate responses.
            xmlHttpReq.ontimeout = xmlHttpReq.onreadystatechange = null;
            if (callback) callback(false, "timeout after " + timeoutMs + " ms");
        };
    }
 
    xmlHttpReq.onreadystatechange = function () {
        if (xmlHttpReq.readyState === 4) {
            xmlHttpReq.ontimeout = xmlHttpReq.onreadystatechange = null;
            if (xmlHttpReq.status == 200) {
                if (callback) callback(true, xmlHttpReq.responseText);
            } else {
                if (callback) callback(false, "http status " + xmlHttpReq.status);
            }
        }
    };
 
    xmlHttpReq.send(data);
};
 
callbackFunctions[Conviva.Constants.CallbackFunctions.SAVE_DATA] = function (storageSpace, storageKey, data, callback) {
    var localStorageKey = storageSpace + "." + storageKey;
    try {
        localStorage.setItem(localStorageKey, data);
        callback(true, null);
    } catch (e) {
        callback(false, e.toString());
    }
};
 
callbackFunctions[Conviva.Constants.CallbackFunctions.LOAD_DATA] = function (storageSpace, storageKey, callback) {
    var localStorageKey = storageSpace + "." + storageKey;
    try {
        var data = localStorage.getItem(localStorageKey);
        callback(true, data);
    } catch (e) {
        callback(false, e.toString());
    }
};
 
callbackFunctions[Conviva.Constants.CallbackFunctions.GET_EPOCH_TIME_IN_MS] = function () {
    var d = new Date();
    return d.getTime();
};
 
callbackFunctions[Conviva.Constants.CallbackFunctions.CREATE_TIMER] = function (timerAction, intervalMs) {
    var timerId = setInterval(timerAction, intervalMs);
    var cancelTimerFunc = (function () {
        if (timerId !== -1) {
            clearInterval(timerId);
            timerId = -1;
        }
    });
    return cancelTimerFunc;
};

Sample code illustrating initialization with/without debug:

if (DEBUG) {
   var settings = {};
   settings[Conviva.Constants.GATEWAY_URL] = "YOUR Touchstone Service URL";
   settings[Conviva.Constants.LOG_LEVEL] = Conviva.Constants.LogLevel.DEBUG;
   Conviva.Analytics.init(TEST_CUSTOMER_KEY, callbackFunctions, settings);
} else {
   // production release
   Conviva.Analytics.init(PRODUCTION_CUSTOMER_KEY, callbackFunctions);
}

IMPORTANT: No need to set GATEWAY_URL and LOG_LEVEL settings for your production release. The Conviva SDK provides the default values for production. Use conviva-core-sdk.js for the production release.

Create videoAnalytics object.

var videoAnalytics = Conviva.Analytics.buildVideoAnalytics();

Create adAnalytics object.

var adAnalytics = Conviva.Analytics.buildAdAnalytics(videoAnalytics);

Refer to this sample code to include the Conviva library and MSE open source:

Via HTML:

<script type="text/javascript" src="<PATH>/hasplayer.js"></script> // Smooth Streaming support
<script type="text/javascript" src="<PATH>/dash.all.min.js"></script> // Dash Support
<script type="text/javascript" src="<PATH>/hls.min.js"></script> // HLS Support
<script type="text/javascript" src="<PATH>/conviva-core-sdk.js"></script>
<script type="text/javascript" src="<PATH>/conviva-html5native-impl.js"></script>

Via import/require:

const Conviva = require('<path>/conviva-js-coresdk');
const ConvivaHtml5Module = require('<path>/ conviva-js-html5');

Conviva.Analytics.init(customerKey, null, settings);

videoAnalytics.setPlayer(HTMLVideoElement);

If Core SDK and html5 module are loaded in private scope instead of global scope, then pass the html5 module object as the second argument in the setPlayer API.

Important: The application sets the player reference immediately after the player instance is available.

var options = {};
options[Conviva.Constants.CONVIVA_MODULE] = ConvivaHtml5Module;
var videoAnalytics = Conviva.Analytics.buildVideoAnalytics();
videoAnalytics.setPlayer(HTMLVideoElement, options);

Report the device metadata of CATEGORY and TYPE explicitly by the application, as Conviva can autocollect the remaining metadata from the UAS. Refer to the code sample below:

var deviceMetadata = {};
// set the corresponding Conviva.Constants.DeviceType
deviceMetadata[Conviva.Constants.DeviceMetadata.TYPE] = Conviva.Constants.DeviceType.DESKTOP;
deviceMetadata[Conviva.Constants.DeviceMetadata.CATEGORY] = Conviva.Constants.DeviceCategory.WEB;
Conviva.Analytics.setDeviceMetadata(deviceMetadata);

To implement the rest of metadata, refer to the above sections of common pre-defined, pre-defined video, and custom metadata definitions for implementation details.

To report fatal playback error AND quit the session: videoAnalytics.reportPlaybackFailed(/* string / errorMessage, / object */ contentInfo=):

Example usage:

// report error and cleanup immediately. The contentInfo provides metadata for the failed video.
videoAnalytics.reportPlaybackFailed(errorMessage, contentInfo);

// report the error but keep the session open
videoAnalytics.reportPlaybackError(errorMessage, Conviva.Constants.ErrorSeverity.FATAL);

// report error and create session when playback starts to report it in the session.
videoAnalytics.reportPlaybackError(errorMessage, Conviva.Constants.ErrorSeverity.FATAL);
videoAnalytics.reportPlaybackRequested(contentInfo);

videoAnalytics.reportPlaybackMetric(/* Conviva.Constants.Playback / key, / string | integer | long | Conviva.Constants.PlayerState */ val..):

Example usage:

// integer parameter in kbps for this key Conviva.Constants.Playback.BITRATE
videoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.BITRATE, 3600);

NOTE: Since this API callback is called every 1 sec, it is recommended that no other metrics than the one specified be updated. It must not retain strong references to instances in outer scopes.

// Sample Code Snippet
videoAnalytics.setCallback(function() {
    videoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.BUFFER_LENGTH, bufferLength);
    videoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.PLAY_HEAD_TIME, playheadTimeMs);
    videoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.RENDERED_FRAMERATE, renderedFramerate);
});

For Custom Integration, Conviva SDK does not capture any metadata automatically.

To implement the rest of metadata, refer to the above sections of common pre-defined, pre-defined video, and custom metadata metadata definitions for implementation details.

Refer to the following sample code to load Video.js components first followed by Conviva modules:

Via HTML:

<script src="<PATH>/video.min.js"></script>
<script type="text/javascript" src="<PATH>/conviva-core-sdk.js"></script>
<script type="text/javascript" src="<PATH>/conviva-videojs-module.js"></script>

Via import/require:

import Conviva from '@convivainc/conviva-js-coresdk'
import ConvivaVideojsModule from'@convivainc/conviva-js-videojs'

const Conviva = require('<path>/conviva-js-coresdk');
const ConvivaVideojsModule = require('<path>/conviva-js-videojs');

Application doesn't need to implement the system utility functions of Time, Timer, HTTP, Storage Load/Save, Log as Conviva Video.js module uses Conviva's default ones.

Conviva.Analytics.init(customerKey, null, settings);

videoAnalytics.setPlayer(videojs);

If Core SDK and Video.js module are loaded in private scope instead of global scope, then pass the Video.js module object as the second argument in the setPlayer API.

var options = {};
options[Conviva.Constants.CONVIVA_MODULE] = ConvivaVideojsModule;
   
var videoAnalytics = Conviva.Analytics.buildVideoAnalytics();
videoAnalytics.setPlayer(videojs, options);

Report the device metadata of CATEGORY and TYPE explicitly by the application, as Conviva can autocollect the remaining metadata from the UAS. Refer to the code sample below:

var deviceMetadata = {};
// set the corresponding Conviva.Constants.DeviceType
deviceMetadata[Conviva.Constants.DeviceMetadata.TYPE] = Conviva.Constants.DeviceType.DESKTOP;
deviceMetadata[Conviva.Constants.DeviceMetadata.CATEGORY] = Conviva.Constants.DeviceCategory.WEB;
Conviva.Analytics.setDeviceMetadata(deviceMetadata);

To implement the rest of metadata, refer to the above sections of common pre-defined, pre-defined video, and custom metadata metadata definitions for implementation details.

Report end of playback when playback ends or when all the ads are completed, whichever occurs last. Conviva objects must be released when the webpage lifecycle ends. Refer to Conviva Cleanup for more details.

You can add the Conviva Chromecast v2 module dependency by choosing one of the following options:

• Install using the npm package manager
• Install using the yarn package manager
• Download and add the library explicitly from Conviva GitHub

From Chromecast v2 module version 4.0.8 onwards, Conviva supports installation through npm and yarn package managers.

To install using the npm package manager, use:

npm install @convivainc/conviva-js-chromecast-v2 --save

To install using the yarn package manager, use:

yarn add @convivainc/conviva-js-chromecast-v2

To download and add the library explicitly from Conviva GitHub, refer: https://github.com/Conviva/conviva-js-chromecast-v2

Refer to this sample code which includes the Chromecast v2 modules followed by Conviva modules:

<script type="text/javascript" src="//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
<script type="text/javascript" src="//www.gstatic.com/cast/sdk/libs/mediaplayer/1.0.0/media_player.js"></script>
 
<script type="text/javascript" src="<PATH>/conviva-core-sdk.js"></script>
<script type="text/javascript" src="<PATH>/conviva-chromecast-v2module.js"></script>

Application doesn't need to implement the system utility functions of Time, Timer, HTTP, Storage Load/Save, Log as Conviva Chromecast v2 module uses Conviva's default ones.

Conviva suggest that you initialize Conviva on LOAD_START event from PlayerManager Instance in Chromecast.

Conviva.Analytics.init(customerKey, null, settings);

var extraListeners = {};
extraListeners[Conviva.Constants.MEDIA_ELEMENT] = mediaElement;
 
videoAnalytics.setPlayer(castPlayerManager, extraListeners);

Since that moment, Conviva library will listen for all relevant events automatically.

Metrics monitored by Conviva Chromecast v2 module (if applicable):

Metadata monitored by Conviva Chromecast v2 module (if applicable):

To implement the rest of metadata, refer to the above sections of common pre-defined, pre-defined video, and custom metadata metadata definitions for implementation details.

Report end of playback where cast framework's MEDIA_FINISHED event is handled and Conviva objects should be released where window.onunload event is handled , refer to Conviva Cleanup for more details.

Refer to this sample code which includes the Chromecast CAF modules followed by Conviva modules.

Via HTML:

<script type="text/javascript" src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
 
<script type="text/javascript" src="<PATH>/conviva-core-sdk.js"></script>
<script type="text/javascript" src="<PATH>/conviva-chromecast-cafmodule.js"></script>

Via Import/Require:

import Conviva from '@convivainc/conviva-js-coresdk'
import ConvivaChromecastCafModule from'@convivainc/conviva-js-chromecast-caf '

const Conviva = require('<path>/conviva-js-coresdk');
const ConvivaChromecastCafModule = require('<path>/conviva-js-chromecast-caf ');

Conviva suggests that you initialize Conviva on LOAD_START event from PlayerManager Instance in Chromecast.

Conviva.Analytics.init(customerKey, null, settings);

The cafPlayerManager argument is the instance of PlayerManager which is common for generic or custom UI.

// Generic UI
<cast-media-player></cast-media-player>
 
// Custom UI
<video class="castMediaElement"></video>
var context = cast.framework.CastReceiverContext.getInstance();
var cafPlayerManager = context.getPlayerManager();
 
videoAnalytics.setPlayer(cafPlayerManager);

If Core SDK and ChromecastCaf module are loaded in private scope instead of global scope, then pass the ChromcastCaf module object as the second argument in the setPlayer API.

// Generic UI
<cast-media-player></cast-media-player>
 
// Custom UI
<video class="castMediaElement"></video>
var context = cast.framework.CastReceiverContext.getInstance();
var cafPlayerManager = context.getPlayerManager();

var options = {};
options[Conviva.Constants.CONVIVA_MODULE] = ConvivaChromecastCafModule;
   
var videoAnalytics = Conviva.Analytics.buildVideoAnalytics();
videoAnalytics.setPlayer(cafPlayerManager, options);

To implement the rest of metadata, refer to the above sections of common pre-defined, pre-defined video, and custom metadata metadata definitions for implementation details.

Report end of playback where cast framework's MEDIA_FINISHED event is handled and Conviva objects should be released where window.onunload event is handled. Refer to Conviva Cleanup for more details.

Add the below mentioned configurations in the config.xml file in the application to provide the required privileges and the background support:

<widget>
<content src="index.html"/>
<tizen:privilege name=
    "http://developer.samsung.com/privilege/avplay"/>
<tizen:privilege name=
    "http://developer.samsung.com/privilege/productinfo"/>
<tizen:privilege name=
    "http://developer.samsung.com/privilege/network.public"/>
<tizen:profile name="tv-samsung"/>
<tizen:setting background-support="enable"/>
</widget>

Refer to the sample code which loads the Tizen components first and then the Conviva libraries:

<script type="text/javascript" src="$WEBAPIS/webapis/webapis.js">
</script>
 
<script type="text/javascript"src="<PATH>/conviva-core-sdk.js">
</script>
<script type="text/javascript" src="<PATH>/conviva-tizen-module.js">
</script>

Application doesn't need to implement the system utility functions of Time, Timer, HTTP, Storage Load/Save, Log as Conviva Samsung TV Tizen module uses Conviva's default ones.

Conviva suggest that you initialize Conviva on window.onload() in Tizen.

Conviva.Analytics.init(customerKey, null, settings);

IMPORTANT: The application listener should be set prior to reporting of the setPlayer API.

// Sample code snippet
var listener = {
    onbufferingstart: function () {},
    onbufferingprogress: function (percent) {…},
    onbufferingcomplete: function () {…},
    oncurrentplaytime: function (currentTime) {…},
    onevent: function (eventType, eventData) {…},
    onsubtitlechange: function (duration, text, data3, data4) {…},
    ondrmevent: function (drmEvent, drmData) {…},
    onstreamcompleted: function () {
        convivaVideoAnalytics.reportPlaybackEnded();
    },
    onerror: function (eventType) {…}
};
webapis.avplay.setListener(listener);
convivaVideoAnalytics.setPlayer(listener);
convivaVideoAnalytics.reportPlaybackRequested();
 
try {
    webapis.avplay.open(url);
    webapis.avplay.prepareAsync(function () {
       try {
           webapis.avplay.play();
       } catch (e) {
            // error: play
            convivaVideoAnalytics.reportPlaybackFailed("error: play");
       }
    }, function () {
       // prepareAsync failure callback
        convivaVideoAnalytics.reportPlaybackFailed(
        "prepareAsync failure callback");
    });
} catch (e) {
    // error: open or prepareAsync
     convivaVideoAnalytics.reportPlaybackFailed(
     "error: open or prepareAsync");
}

// Register the key handler for seek, fast forward and rewind:
// seekStartFlag to prevent multiple clicks from sending multiple 
// pss events.
var seekStartFlag = true; 
 
/**
* Jump forward 3 seconds (3000 ms).
*/
fastforward: function () {
var seekToPos = 3000; //Value of the seek time in milliseconds
try {
    if(seekStartFlag) {
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_STARTED, 
        webapis.avplay.getCurrentTime() + seekToPos); ***
    }
    ffSuccess = function() {
        seekStartFlag = true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
    };
    ffError = function(e) {
        seekStartFlag = true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
    };
    webapis.avplay.jumpForward(seekToPos, ffSuccess, ffError);
} catch (e) {
}
},
 
/**
* Seek to 3 seconds (3000 ms).
*/
seek : function () {
var seekToPos = 3000; //Value of the seek time in milliseconds
try {
     if(seekStartFlag) {
        seekStartFlag = false;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_STARTED,
        seekToPos);
     }
     seekSucess = function() {
        seekStartFlag = true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
     };
     seekFail = function() {
        seekStartFlag = true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
     };
     webapis.avplay.seekTo(seekToPos, seekSucess , seekFail);
} catch (e) {
}
},
 
/**
* Rewind 3 seconds (3000 ms).
*/
rew: function () {
var seekToPos = 3000; //Value of the seek time in milliseconds
try {
    if(seekStartFlag) {
        seekStartFlag = false;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_STARTED, 
        webapis.avplay.getCurrentTime() - seekToPos);
    }
    rewSuccess = function() {
        seekStartFlag =true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
    };
    rewError = function(e) {
        seekStartFlag = true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
    };
    webapis.avplay.jumpBackward(seekToPos, rewSuccess, rewError);
} catch (e) {
}
}

// Register the key handler for seek, fast forward and rewind:
// seekStartFlag to prevent multiple clicks from sending multiple
// pss events.
var seekStartFlag = true;
 
/**
* Jump forward 3 seconds (3000 ms).
*/
fastforward: function () {
var seekToPos = 3000; //Value of the seek time in milliseconds
try {
    if(seekStartFlag) {
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_STARTED,
        webapis.avplay.getCurrentTime() + seekToPos); ***
    }
    ffSuccess = function() {
        seekStartFlag = true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
    };
    ffError = function(e) {
        seekStartFlag = true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
    };
    webapis.avplay.jumpForward(seekToPos, ffSuccess, ffError);
} catch (e) {
}
},
 
/**
* Seek to 3 seconds (3000 ms).
*/
seek : function () {
var seekToPos = 3000; //Value of the seek time in milliseconds
try {
     if(seekStartFlag) {
        seekStartFlag = false;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_STARTED,
        seekToPos);
     }
     seekSucess = function() {
        seekStartFlag = true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
     };
     seekFail = function() {
        seekStartFlag = true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
     };
     webapis.avplay.seekTo(seekToPos, seekSucess , seekFail);
} catch (e) {
}
},
 
/**
* Rewind 3 seconds (3000 ms).
*/
rew: function () {
var seekToPos = 3000; //Value of the seek time in milliseconds
try {
    if(seekStartFlag) {
        seekStartFlag = false;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_STARTED,
        webapis.avplay.getCurrentTime() - seekToPos);
    }
    rewSuccess = function() {
        seekStartFlag =true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
    };
    rewError = function(e) {
        seekStartFlag = true;
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_ENDED);
    };
    webapis.avplay.jumpBackward(seekToPos, rewSuccess, rewError);
} catch (e) {
}
}

Connection Type is autocollected by Tizen module using the webapis.network.getActiveConnectionType():

Metadata monitored by Conviva Samsung TV Tizen module (if applicable):

To implement the rest of metadata, refer to the above sections of common pre-defined, pre-defined video, and custom metadata metadata definitions for implementation details.

The cleanup should be invoked where Application's tizen.application.getCurrentApplication().exit() is handled, refer to Conviva Cleanup for more details.

You can add the Conviva PlayStation Trilithium module dependency by choosing one of the following options:

• Install using the npm package manager
• Install using the yarn package manager
• Download and add the library explicitly from Conviva GitHub

From PlayStation Trilithium module version 4.0.2 onwards, Conviva supports installation through npm and yarn package managers.

To install using the npm package manager, use:

npm install @convivainc/conviva-js-playstation-trilithium --save

To install using the yarn package manager, use:

yarn add @convivainc/conviva-js-playstation-trilithium

To download and add the library explicitly from Conviva GitHub, refer: https://github.com/Conviva/conviva-js-playstation-trilithium

Refer to this sample code which includes the Conviva modules:

include ('<PATH>/conviva-core-sdk.js');
include ('<PATH>/conviva-playstation-trilithium-module.js');

Application need to explicitly implement the system utility functions of Timer, HTTP, Storage Load/Save and Log, Time can be used of Conviva's default ones.

Click to view the reference implementation:

var callbackFunctions = {};
 
callbackFunctions[Conviva.Constants.CallbackFunctions.MAKE_REQUEST] = 
function (isPOST, url, data, contentType, timeout, callback)) {
    if (typeof(data) !== "string") {
        data = JSON.stringify(data);
    }
    var _s = this;
    if (!_s._httpClientObject) {
        _s._httpClientObject = engine.createHttpClient();
    }
 
    var httpRequestObject = 
    _s._httpClientObject.request((isPOST ? "POST" : "GET"), url);
    if (isPOST) {
        httpRequestObject.sendBody(data);
    }
    httpRequestObject.onError = 
    function (httpStatusCode, content, size) {
        callback(false, null);
    }
    httpRequestObject.onComplete = function (response) {
        callback(true, response);
    }
    httpRequestObject.start();
    return function () {
        httpRequestObject.cancel();
    };
};
 
callbackFunctions[Conviva.Constants.CallbackFunctions.SAVE_DATA] = 
function (storageSpace, storageKey, data, callback) {
    var localStorageKey = storageSpace + "." + storageKey;
    try {
        engine.storage.local[localStorageKey] = data;
        callback(true, null);
    } catch (e) {
        callback(false, e.toString());
    }
};
 
callbackFunctions[Conviva.Constants.CallbackFunctions.LOAD_DATA] = 
function (storageSpace, storageKey, callback) {
    var localStorageKey = storageSpace + "." + storageKey;
    try {
        var data = engine.storage.local[localStorageKey];
        callback(true, data);
    } catch (e) {
        callback(false, e.toString());
    }
};
 
callbackFunctions[Conviva.Constants.CallbackFunctions.CREATE_TIMER] = 
function (timerAction, intervalMs) {
    var timerId = setInterval(timerAction, intervalMs);
    var cancelTimerFunc = (function () {
        if (timerId !== -1) {
            clearInterval(timerId);
            timerId = -1;
        }
    });
    return cancelTimerFunc;
};
 
var intervals = {};
var intervalsCount = 0;
function setInterval(func, time) {
    var intervalId = 
    intervalsCount ? ++intervalsCount : intervalsCount = 1;
    intervals[intervalId] = function () {
        if (intervals[intervalId]) {
            if (intervals[intervalId].active) {
                func();
                setTimeout(intervals[intervalId], time);
            } else {
                delete intervals[intervalId];
            }
        }
    }
    intervals[intervalId].active = true;
    setTimeout(intervals[intervalId], time);
    return intervalId;
}
 
function clearInterval(intervalId) {
    intervals[intervalId].active = false;
}
 
Conviva.Analytics.init(customerKey, callbackFunctions);

videoAnalytics.setPlayer(videoPlayer); // created using engine.createVideo()

var seeking = false;
var seekStartTime;
var seekMultiple;
var seekStartOffset;
 
function SeekRight(video) {
    if (!video) {
        return;
    }
    if (!seeking) {
        seeking = true;
        seekStartTime = (+new Date) / 1000.0;
        seekMultiple = 0;
        seekStartOffset = video.currentTime;
    }
    seekMultiple = seekMultiple + 1;
    seek();
}
 
function SeekLeft(video) {
    if (!video) {
        return;
    }
    if (!seeking) {
        seeking = true;
        seekStartTime = (+new Date) / 1000.0;
        seekMultiple = 0;
        seekStartOffset = video.currentTime;
    }
    seekMultiple = seekMultiple - 1;
    seek();
}
 
function SeekToTime() {
    if (seeking) {
        var nowTime = (+new Date)/1000.0;
        var targetTime =  
        seekStartOffset + (nowTime - seekStartTime) * seekMultiple;
        if (targetTime < 0) {
            targetTime = 0;
        }
        return targetTime;
    } else {
        return -1;
    }
}
 
function seek() {
    if (seeking && SeektoTime() != -1) {
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.SEEK_STARTED, 
        Math.round(SeekToTime() * 1000));
        // Seeks the video to the set position
        video.currentTime = SeekToTime(); 
        seeking = false;
    }
}

Connection Type is autocollected by Trilithium module using the engine.stats.network.type

To implement the rest of metadata, refer to the above sections of common pre-defined, pre-defined video, and custom metadata metadata definitions for implementation details.

You can add the Conviva PlayStation WebMAF module dependency by choosing one of the following options:

• Install using the npm package manager
• Install using the yarn package manager
• Download and add the library explicitly from Conviva GitHub

From PlayStation WebMAF module version 4.0.2 onwards, Conviva supports installation through npm and yarn package managers.

To install using the npm package manager, use:

npm install @convivainc/conviva-js-playstation-webmaf --save

To install using the yarn package manager, use:

yarn add @convivainc/conviva-js-playstation-webmaf

To download and add the library explicitly from Conviva GitHub, refer: https://github.com/Conviva/conviva-js-playstation-webmaf

Refer to this sample code to include the Conviva modules:

<script type="text/javascript" src="<PATH>/conviva-core-sdk.js"></script>
<script type="text/javascript" src="<PATH>/conviva-webmaf-module.js"></script>

Application need to explicitly implement the system utility functions of Storage Load/Save and Timer, HTTP, Log, Time can be used of Conviva's default ones.

Click to view the reference implementation:

var callbackFunctions = {};

callbackFunctions[Conviva.Constants.CallbackFunctions.SAVE_DATA] = 
function (storageSpace, storageKey, data, callback) {
    var localStorageKey = storageSpace + "." + storageKey;
    try {
        var forever = new Date();
        forever.setTime(forever.getTime() + 10 * 365 * 24 * 3600 * 1000); // +10years
        document.cookie = 
        localStorageKey + "=" + data + "; expires=" + 
        forever.toGMTString() + "; path=/";
        callback(true, null);
    } catch (e) {
        callback(false, e.toString());
    }
};

callbackFunctions[Conviva.Constants.CallbackFunctions.LOAD_DATA] = 
function (storageSpace, storageKey, callback) {
    var localStorageKey = storageSpace + "." + storageKey;
    try {
        var cookies = document.cookie;
        var start = cookies.indexOf(" " + localStorageKey + "=");
        if (start == -1) {
            start = cookies.indexOf(localStorageKey + "=");
        }
        if (start != -1) {
            start = cookies.indexOf("=", start) + 1;
            var end = cookies.indexOf(";", start);
            if (end == -1) {
                end = cookies.length;
            }
            var data = cookies.substring(start, end);
            callback(true, data);
        }
    } catch (e) {
        callback(false, e.toString());
    }
};

Conviva.Analytics.init(customerKey, callbackFunctions);

videoAnalytics.setPlayer(videometrics);

Starting that moment, Conviva library will listen for all relevant events automatically.

Metrics monitored by Conviva PlayStation WebMAF module (if applicable):

To implement the rest of metadata, refer to the above sections of common pre-defined, pre-defined video, and custom metadata definitions for implementation details.

Conviva PlayStation WebMAF module autocollects the AppBackground and AppForeground events by monitoring applicationStatus on the applicationStatusChange event.

You can add the Conviva IMA module dependency by choosing one of the following options:

• Install using the npm package manager
• Install using the yarn package manager
• Download and add the library explicitly from Conviva GitHub

From Google IMA module version 4.0.3 onwards, Conviva supports installation through npm and yarn package managers.

To install using the npm package manager, use:

npm install @convivainc/conviva-js-imasdk --save

To install using the yarn package manager, use:

yarn add @convivainc/conviva-js-imasdk

To download and add the library explicitly from Conviva GitHub, refer: https://github.com/Conviva/conviva-js-imasdk

Refer to this sample code which includes the Google IMA components first followed by Conviva modules.

Via HTML:

<script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
 
<script type="text/javascript" src="<PATH>/conviva-core-sdk.js"></script>
<script type="text/javascript" src="<PATH>/conviva-googleima-module.js"></script>

Via Import/Require:

import Conviva from '@convivainc/conviva-js-coresdk'
import ConvivaGoogleimaModule from'@convivainc/conviva-js-imasdk'

const Conviva = require('<path>/conviva-js-coresdk');
const ConvivaGoogleimaModule = require('<path>/conviva-js-imasdk');

To enable Ad metric & metadata autocollection, pass the adsLoader instance of the IMA SDK along with videoPlayer instance, AD_TAG_URL and preload information to adAnalytics:

var info = {};
 
// if adTagurl is known prior
info[Conviva.Constants.AD_TAG_URL] = "adTagUrl";
 
// if preloading is enabled or disabled
info[Conviva.Constants.AD_PRELOAD_FEATURE] = true;

// if conviva admodule is used
info[Conviva.Constants.CONVIVA_MODULE] = ConvivaGoogleimaModule;
 
// Mandatory as IMA SDK requires videoPlayer object to fetch ad manager by module.
// Player object used to play content
info[Conviva.Constants.IMASDK_CONTENT_PLAYER] = videoPlayer;
 
// This API is used to initialise the IMA module and registers listeners for ad playback
adAnalytics.setAdListener(adsLoader, info);

Metrics monitored by Conviva Google IMA module (if applicable):

You can add the Conviva IMA DAI module dependency by choosing one of the following options:

• Install using the npm package manager
• Install using the yarn package manager
• Download and add the library explicitly from Conviva GitHub

From Google IMA DAI module version 4.1.0 onwards, Conviva supports installation through npm and yarn package managers.

To install using the npm package manager, use:

npm install @convivainc/conviva-js-daisdk --save

To install using the yarn package manager, use:

yarn add @convivainc/conviva-js-daisdk

To download and add the library explicitly from Conviva GitHub, refer: https://github.com/Conviva/conviva-js-daisdk

Refer to this sample code which includes the Google DAI components first followed by Conviva modules:

Via HTML:

<script type="text/javascript" src="https://imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
 
<script type="text/javascript" src="<PATH>/conviva-core-sdk.js"></script>
<script type="text/javascript" src="<PATH>/conviva-googledai-module.js"></script>

Via Import/Require:

import Conviva from '@convivainc/conviva-js-coresdk'
import ConvivaGoogledaiModule from'@convivainc/conviva-js-daisdk'

const Conviva = require('<path>/conviva-js-coresdk');
const ConvivaGoogledaiModule = require('<path>/conviva-js-daisdk');

To enable Ad metric and metadata autocollection, pass the StreamManager and HTMLVideoElement to adAnalytics:

IMPORTANT: Once the StreamManager is created, follow the below instructions for every content playback as the streamManager events are de-registered internally on playback end.

// Code snippet from the html listing the video tag
<div id="video-player">
    <video id="content"></video>
</div>
 
// Code snippet of stream manager initialisation
var videoPlayer = document.getElementById('content');
 
var streamManager = new google.ima.dai.api.StreamManager(videoPlayer);
 
var extraListeners = {};
// Mandatory: HTMLVideoElement to fetch player level events of player state, pht, buffer length and errors by module.
extraListeners[Conviva.Constants.IMASDK_CONTENT_PLAYER] = videoPlayer;

// if conviva admodule is used
extraListeners[Conviva.Constants.CONVIVA_MODULE] = ConvivaGoogledaiModule;
 
// This API is used to initialise the IMA DAI module and registers listeners for ad playback
adAnalytics.setAdListener(streamManager, extraListeners);
 
// Ensure to register the event listeners after the setAdListener() as the order is important for reporting metrics
streamManager.addEventListener([google.ima.dai.api.StreamEvent.Type.STARTED,
    google.ima.dai.api.StreamEvent.Type.FIRST_QUARTILE,
    google.ima.dai.api.StreamEvent.Type.MIDPOINT,
    google.ima.dai.api.StreamEvent.Type.THIRD_QUARTILE,
    google.ima.dai.api.StreamEvent.Type.COMPLETE], function(event) {
        }, false);

Metrics autocollected by Conviva Google IMA DAI module:

hls.on(Hls.Events.ERROR, function (event, data) {
    if (data.fatal) {
        if (isAdStarted) {
            adAnalytics.reportAdFailed(data.type + ': ' + data.details);
        }
        videoAnalytics.reportPlaybackFailed(
        data.type + ': ' + data.details);
    }
}

hls.on(Hls.Events.LEVEL_SWITCHING, function (event, data) {
        convivaVideoAnalytics.reportPlaybackMetric(
        Conviva.Constants.Playback.BITRATE, 
        parseInt(data.bitrate/1000), 
        10));
}

In case of Custom Ad integration, Conviva does not autocollect any ad metrics or events.

Implement the following ad events from your application to Conviva:

• adAnalytics.reportAdLoaded(/* object */ adInfo) // invoke on ad load complete

• adAnalytics.reportAdStarted(/* object */ adInfo) // invoke on ad playback start

• adAnalytics.reportAdFailed(/* string / errorMessage, / object */ adInfo) // invoke when ad fails to load/play

• adAnalytics.reportAdSkipped() // user skipped the ad

• adAnalytics.reportAdEnded() // ad playback completed

In the above methods, the parameter adInfo is a map containing the key - value pairs of metadata tags for ad content.

Implement it with respect to the requirements prescribed in the next step.

In case of Custom Ad integration, Conviva does not automatically collect ad metadata, except a few fields for common metadata pulled from the videoAnalytics object automatically. Implement the pre-defined common and ad metadata specified in the table below:

Pre-defined Common Metadata:

var adPlayerInfo = {};
adPlayerInfo[Conviva.Constants.FRAMEWORK_NAME] = "YOUR_FRAMEWORK_NAME";
adAnalytics.setAdPlayerInfo(adPlayerInfo);

var adPlayerInfo = {};
adPlayerInfo[Conviva.Constants.FRAMEWORK_VERSION] = "1.2.3";
adAnalytics.setAdPlayerInfo(adPlayerInfo);

Autocollected as the same value from videoAnalytics - no need to pass for adAnalytics.

Pre-defined Ad Metadata:

Report Ad-video metrics to adAnalytics by using adAnalytics.reportAdMetric(/* Conviva.Constants.Playback / key, / integer | string | long | Conviva.Constants.PlayerState */ value...):

• key: Conviva.Constants.Playback type.

• val: It accepts multiple/zero values for the second argument.

adAnalytics.reportAdMetric(Conviva.Constants.Playback.BITRATE, 1024);

Refer to the list of metric keys to be implememted in the table below:

var identifiers = {};
identifiers["androidId"] = "false";
Conviva.Analytics.setUserPreferenceForDataCollection(identifiers, false);

var identifiers = {};
identifiers["androidId"] = "true";
Conviva.Analytics.setUserPreferenceForDataCollection(identifiers);

// Sample code snippet illustrating event on explicit change of video quality in the player
var eventType = "fullscreen";
var attr = {};
attr["old_quality"] = "SD";
attr["new_quality"] = "HD";
attr["player"] = "WEB player";
videoAnalytics.reportPlaybackEvent(eventType, attr);

// Sample for "share-click" event with 3 attributes
var eventType = "share-click";
var attr = {};
attr["location"] =  "Toolbar";
attr["assetName"] = "Sample Video";
attr["shareService"] = "Facebook";
Conviva.Analytics.reportAppEvent(eventType, attr);