Namespace: VideoAnalytics

VideoAnalytics

Class provides the API's for the customer application to report Video Analytics.

Methods

configureExistingSession(sessionKey)

Required. To configure Content Session Key created from the Legacy EI integration for Simplified AI integration. This API should be used only after Analytics#configureExistingClient
Parameters:
Name Type Description
sessionKey int Content Session ID created by createSession()
Example
var client = new Conviva.Client(clientSettings);
var sessionKey = Conviva.Client.createSession();
Conviva.Analytics.configureExistingClient(client);
convivaVideoAnalytics.configureExistingSession(sessionKey);

release()

Required. Release the VideoAnalytics Module related information by cleaning up applicable Content and Ad monitor. None of the VideoAnalytics API's works as desired after release API, need to build new VideoAnalytics instance after invoking this method
Example
convivaVideoAnalytics.release();

reportAdBreakEnded()

Optional - Internal. Report Ad Break End if the application needs Ad Break Insights. Should be invoked only after reportAdBreakStarted
Example
convivaVideoAnalytics.reportAdBreakEnded();

reportAdBreakEnded()

Required. Report Ad Break End if the application needs Ad Break Insights. Should be invoked only after reportAdBreakStarted
Example
convivaVideoAnalytics.reportAdBreakEnded();

reportAdBreakStarted(adType, adPlayer, adBreakInfoopt)

Optional - Internal. Report Ad Break Start in case of application needs Ad Break Insights.
Parameters:
Name Type Attributes Description
adType Constants.AdType Ad Type to differentiate Client Side and Server Side Ads.
adPlayer Constants.AdPlayer Ad Player to differentiate whether same or different player instances are used for content and ad playbacks.
adBreakInfo Object <optional>
 AdBreakInfo with break duration, ad position and pod index.
Examples
// Client Side ads with different player instance used wrt video
var adType = Conviva.Constants.AdType.CLIENT_SIDE;
var adPlayer = Conviva.Constants.AdPlayer.SEPARATE;
var adBreakInfo = {};
adBreakInfo[Conviva.Constants.POD_DURATION] = "60";
adBreakInfo[Conviva.Constants.POD_POSITION] = Conviva.Constants.AdPosition.PREROLL;
adBreakInfo[Conviva.Constants.POD_INDEX] = "1";
convivaVideoAnalytics.reportAdBreakStarted(adType, adPlayer, adBreakInfo);
// Client Side ads with same player instance used wrt video
var adType = Constants.AdType.CLIENT_SIDE;
var adPlayer = Constants.AdPlayer.CONTENT;
var adBreakInfo = {};
adBreakInfo[Conviva.Constants.POD_DURATION] = "60";
adBreakInfo[Conviva.Constants.POD_POSITION] = Conviva.Constants.AdPosition.PREROLL;
adBreakInfo[Conviva.Constants.POD_INDEX] = "1";
convivaVideoAnalytics.reportAdBreakStarted(adType, adPlayer, adBreakInfo);
// Server Side ads with same player instance used wrt video
var adType = Constants.AdType.SERVER_SIDE;
var adPlayer = Constants.AdPlayer.CONTENT;
var adBreakInfo = {};
adBreakInfo[Conviva.Constants.POD_DURATION] = "60";
adBreakInfo[Conviva.Constants.POD_POSITION] = Conviva.Constants.AdPosition.PREROLL;
adBreakInfo[Conviva.Constants.POD_INDEX] = "1";
convivaVideoAnalytics.reportAdBreakStarted(adType, adPlayer, adBreakInfo);
// Server Side ads with different player instance used wrt videe is not a real world use and will be ignored

reportAdBreakStarted(adType, adPlayer, adBreakInfoopt)

Required. Report Ad Break Start in case of application needs Ad Break Insights.
Parameters:
Name Type Attributes Description
adType Constants.AdType Ad Type to differentiate Client Side and Server Side Ads.
adPlayer Constants.AdPlayer Ad Player to differentiate whether same or different player instances are used for content and ad playbacks.
adBreakInfo Object <optional>
 AdBreakInfo with break duration, ad position and pod index.
Examples
// Client Side ads with different player instance used wrt video
var adType = Conviva.Constants.AdType.CLIENT_SIDE;
var adPlayer = Conviva.Constants.AdPlayer.SEPARATE;
var adBreakInfo = {};
adBreakInfo[Conviva.Constants.POD_DURATION] = "60";
adBreakInfo[Conviva.Constants.POD_POSITION] = Conviva.Constants.AdPosition.PREROLL;
adBreakInfo[Conviva.Constants.POD_INDEX] = "1";
convivaVideoAnalytics.reportAdBreakStarted(adType, adPlayer, adBreakInfo);
// Client Side ads with same player instance used wrt video
var adType = Constants.AdType.CLIENT_SIDE;
var adPlayer = Constants.AdPlayer.CONTENT;
var adBreakInfo = {};
adBreakInfo[Conviva.Constants.POD_DURATION] = "60";
adBreakInfo[Conviva.Constants.POD_POSITION] = Conviva.Constants.AdPosition.PREROLL;
adBreakInfo[Conviva.Constants.POD_INDEX] = "1";
convivaVideoAnalytics.reportAdBreakStarted(adType, adPlayer, adBreakInfo);
// Server Side ads with same player instance used wrt video
var adType = Constants.AdType.SERVER_SIDE;
var adPlayer = Constants.AdPlayer.CONTENT;
var adBreakInfo = {};
adBreakInfo[Conviva.Constants.POD_DURATION] = "60";
adBreakInfo[Conviva.Constants.POD_POSITION] = Conviva.Constants.AdPosition.PREROLL;
adBreakInfo[Conviva.Constants.POD_INDEX] = "1";
convivaVideoAnalytics.reportAdBreakStarted(adType, adPlayer, adBreakInfo);
// Server Side ads with different player instance used wrt videe is not a real world use and will be ignored

reportPlaybackEnded()

Required. Report the playback ended initiated by the application to end the Conviva monitoring which is started with reportPlaybackRequested.
Example
convivaVideoAnalytics.reportPlaybackEnded();

reportPlaybackError(errorMessage, errorSeverity)

Required. To report Player Error for Main Video Content.
Parameters:
Name Type Description
errorMessage String Error Message of the video playback failure which needs to be a valid String.
errorSeverity Constants.ErrorSeverity Error Severity of the video playback failure.

reportPlaybackEvent(eventType, eventDetailopt)

Required. To report Custom Player Event for Main Video Content. This method is also used to set Conviva SDK to Not Monitoring state for the Main Video Content. During this period Conviva SDK moves to NOT_MONITORED state omitting Video Restart Time(VRT), Video Startup Time(VRT) and playback other metrics and is used to resume Conviva SDK Monitoring
Parameters:
Name Type Attributes Description
eventType String Event Type of the video player event which needs to be a valid String.
eventDetail Object <optional>
 Event Details of the video player event if avaialble.
Examples
var eventType = Conviva.Constants.Events.POD_STARTED;
var eventDetail = {};
eventDetail[Conviva.Constants.POD_DURATION] = "60";
eventDetail[Conviva.Constants.POD_POSITION] = Conviva.Constants.AdPosition.PREROLL;
eventDetail[Conviva.Constants.POD_INDEX] = "1";
convivaVideoAnalytics.reportPlaybackEvent(eventType, eventDetail);
convivaVideoAnalytics.reportPlaybackEvent(Conviva.Constants.Events.POD_END);
// When popup comes on top video playback
convivaVideoAnalytics.reportPlaybackEvent(Conviva.Constants.Events.USER_WAIT_STARTED);
// When popup closes and the video playback resumes
convivaVideoAnalytics.reportPlaybackEvent(Conviva.Constants.Events.USER_WAIT_ENDED);
// When logo video playback starts
convivaVideoAnalytics.reportPlaybackEvent(Conviva.Constants.Events.BUMPER_VIDEO_STARTED);
// When logo video playback ends and the video playback resumes
convivaVideoAnalytics.reportPlaybackEvent(Conviva.Constants.Events.BUMPER_VIDEO_ENDED);

reportPlaybackFailed(errorMessage, contentInfoopt)

Required. Report the main video content player init failed by the application to start and end the Conviva monitoring with fatal error. This function is equivalent to invoking the API's in sequence reportPlaybackRequested, reportPlaybackError and reportPlaybackEnded This API can be used after the invoking after playback request to report fatal error and end of playback.
Parameters:
Name Type Attributes Description
errorMessage String Error Message to be used for reporting FATAL error.
contentInfo Object <optional>
 Conviva Content Info Object for setting the metadata.
Examples
// Can report initialisation failed without content Info
var errorMessage = "403: Forbidden Error";
convivaVideoAnalytics.reportPlaybackFailed(errorMessage);
// Can report initialisation failed with content Info
var errorMessage = "403: Forbidden Error";
var contentInfo = {};
var contentInfo[Conviva.Constants.ASSET_NAME] = "BugsBunny Episode 1";
convivaVideoAnalytics.reportPlaybackFailed(errorMessage, contentInfo);
// Can report initialisation failed with content Info after playback request as well
convivaVideoAnalytics.reportPlaybackRequested();
var errorMessage = "403: Forbidden Error";
var contentInfo = {};
var contentInfo[Conviva.Constants.ASSET_NAME] = "BugsBunny Episode 1";
convivaVideoAnalytics.reportPlaybackFailed(errorMessage, contentInfo);

reportPlaybackMetric(metricKey, metricValuesopt)

Required. To report Playback Metrics to Conviva SDK for Main Video Content.
Parameters:
Name Type Attributes Description
metricKey Constants.Playback Used for setting the Conviva Playback Metrics.
metricValues integer | Constants.PlayerState | string <optional>
 Used for setting the metric value. Not required in case of few metrics such as Seek End and two arguments needs to be passed in case of Resolution.
Example
// Reporting Playback Metric For Content Monitoring
// Playheadtime in ms
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.PLAY_HEAD_TIME, 10000);

// Bufferlength in ms
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.BUFFER_LENGTH, 1000);

// Rendered framerate in fps
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.RENDERED_FRAMERATE, 23);

// Peak Bitrate in kbps
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.BITRATE, 3000);

// Average Bitrate in kbps
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.AVG_BITRATE, 3000);

// Player State can be PAUSED/BUFFERING/STOPPED/UNKNOWN
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.PLAYER_STATE, Conviva.Constants.PlayerState.PLAYING);

// Width and Height in pixel
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.RESOLUTION, 1080, 720);

// Seek To Pos in ms, seekToPos is optional
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.SEEK_STARTED, 60000);

// Seek End
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.SEEK_ENDED);

// IP Address can be IPv4 or IPv6 – "684D:1111:222:3333:4444:5555:6:77"
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.CDN_IP, "19.117.63.253");

// Dropped frames total (Cumulative)
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.DROPPED_FRAMES_TOTAL, 35);

// Dropped frames count (non-cumulative)
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.DROPPED_FRAMES_COUNT, 3);

// Audio Language change 
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.AUDIO_LANGUAGE, "en");

// Subtitle Language change 
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.SUBTITLES_LANGUAGE, "eng");

// CC Language change 
convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.CLOSED_CAPTIONS_LANGUAGE, "eng");

reportPlaybackRequested(contentInfoopt)

Required. Report the playback request initiated by the application to create Conviva monitoring.
Parameters:
Name Type Attributes Description
contentInfo Object <optional>
 Conviva Content Info Object for setting the metadata.
Examples
// Can report playback request without content Info
convivaVideoAnalytics.reportPlaybackRequested();
// Can set content info prior to reporting of playback request
var contentInfo = {};
contentInfo[Conviva.Constants.ASSET_NAME] = assetName;
convivaVideoAnalytics.setContentInfo(contentInfo);
convivaVideoAnalytics.reportPlaybackRequested();
// Can report playback request with content info
var contentInfo = {};
contentInfo[Conviva.Constants.ASSET_NAME] = assetName;
convivaVideoAnalytics.reportPlaybackRequested(contentInfo);

setAdAnalytics(adAnalytics)

Required. To set the Ad Analytics Object to delegate the Metrics from the Video Analytics to Ad Analytics in case SSAI contents.
Parameters:
Name Type Description
adAnalytics AdAnalytics adAnalytics Object to be delegated
Example
var videoAnalytics = new Conviva.Analytics.buildVideoAnalytics();
var adAnalytics1 = new Conviva.Analytics.buildAdAnalytics(videoAnalytics); // Ad Analytics for SSAI
var adAnalytics2 = new Conviva.Analytics.buildAdAnalytics(videoAnalytics);
videoAnalytics.setAdAnalytics(adAnalytics1);
videoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.BITRATE, 3000); // reports to both Ad and Content Sessions
adAnalytics1.reportAdMetric(Conviva.Constants.Playback.BITRATE, 3000); // reports to both Ad and Content Sessions
videoAnalytics.setAdAnalytics(null); // to stop delegating the metrics
videoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.BITRATE, 3000); // reports to Content Session
adAnalytics1.reportAdMetric(Conviva.Constants.Playback.BITRATE, 3000); // reports to Ad Session

setCallback()

Required. Callback function invoked at a frequency of 1s to report the Conviva metrics for VideoAnalytics.
Examples
// To register the callback
convivaVideoAnalytics.setCallback(function() {
    convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.BUFFER_LENGTH, 3200);
    convivaVideoAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.PLAY_HEAD_TIME, 10000);
});
// To de register the callback
convivaVideoAnalytics.setCallback(null);

setContentInfo(contentInfo)

Required. API to Set Conviva Content Info metadata. Content Info can be set even prior to reportPlaybackRequested to report Conviva about Metadata updates.
Parameters:
Name Type Description
contentInfo Object Conviva Content Info Object for setting the metadata and the length of the ContentInfo should be grater than 0.
Example
var contentInfo = {};
contentInfo[Conviva.Constants.ASSET_NAME] = assetName;
contentInfo[Conviva.Constants.STREAM_URL] = url;
contentInfo[Conviva.Constants.IS_LIVE] = Conviva.Constants.StreamType.LIVE;
contentInfo[Conviva.Constants.PLAYER_NAME] = playerName;
contentInfo[Conviva.Constants.VIEWER_ID] = viewerId;
contentInfo[Conviva.Constants.DURATION] = duration;
contentInfo[Conviva.Constants.ENCODED_FRAMERATE] = encodedFps;
contentInfo[Conviva.Constants.DEFAULT_RESOURCE] = defaultResource;
contentInfo[ANY_TAG_KEY1] = "VALUE1";
contentInfo[ANY_TAG_KEY2] = "VALUE2";
convivaVideoAnalytics.setContentInfo(contentInfo);

setPlayer(playerInstance)

Required. To set player object associated to initialize the player module.
Parameters:
Name Type Description
playerInstance Object Player instance of the video playback to initialize the player module.
If set to null, releases the prior set player module.
If set with new player instance, it replaces the older instance set.
Examples
// To register the player instance with Conviva prior to reportPlaybackRequested
convivaVideoAnalytics.setPlayer(videoElement);
convivaVideoAnalytics.reportPlaybackRequested();
// To register the player instance with Conviva after the reportPlaybackRequested
convivaVideoAnalytics.reportPlaybackRequested();
convivaVideoAnalytics.setPlayer(videoElement);

// To deregister the player instance with Conviva prior to reportPlaybackEnded
convivaVideoAnalytics.setPlayer(null);
convivaVideoAnalytics.reportPlaybackEnded();
// To deregister the player instance with Conviva after the reportPlaybackEnded
convivaVideoAnalytics.reportPlaybackEnded();
convivaVideoAnalytics.setPlayer(null);
// To change the player instance during the cource of playbacck
convivaVideoAnalytics.setPlayer(videoElement1);
convivaVideoAnalytics.setPlayer(videoElement2);

setPlayerInfo(playerInfo)

Required. API to set Conviva Player Info metadata. Content Info can be set even prior to reportPlaybackRequested to report Conviva about Metadata updates.
Parameters:
Name Type Description
playerInfo Object Conviva Player Info Object for setting the metadata and the length of the PlayerInfo should be grater than 0.
Example
var playerInfo = {};
playerInfo[Conviva.Constants.FRAMEWORK_NAME] = "videojs";
playerInfo[Conviva.Constants.FRAMEWORK_VERSION] = "7.11.0";
convivaVideoAnalytics.setPlayerInfo(playerInfo);