Namespace: AdAnalytics

AdAnalytics

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

Methods

release()

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

reportAdEnded()

Required. Report end of Ad Playback. This API shuold be used only after invocation of reportAdLoaded or reportAdEnded or both
Example
convivaAdAnalytics.reportAdEnded();

reportAdError(errorMessage, errorSeverity)

Required. Report Ad Player Error.
Parameters:
Name Type Description
errorMessage String Error Message to be used for reporting FATAL error.
errorSeverity Constants.ErrorSeverity Error severity of the ad playback failure.
Examples
var errorMessage = "403: Forbidden Error";
var errorSeverity = Conviva.Constants.ErrorSeverity.FATAL;
convivaAdAnalytics.reportAdError(errorMessage, errorSeverity);
var errorMessage = "Subtitle not Found";
var errorSeverity = Conviva.Constants.ErrorSeverity.WARNING;
convivaAdAnalytics.reportAdError(errorMessage, errorSeverity);

reportAdFailed(errorMessage, adInfoopt)

Required. Report the ad 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 reportAdLoaded or reportAdStarted, reportAdError and reportAdEnded This API can be used after the invoking after ad loaded/started to report fatal error and ad end.
Parameters:
Name Type Attributes Description
errorMessage String Error Message to be used for reporting FATAL error.
adInfo Object <optional>
 Conviva Ad Info Object for setting the metadata.
Examples
// Can report initialisation failed without content Info
var errorMessage = "403: Forbidden Error";
convivaAdAnalytics.reportAdFailed(errorMessage);
// Can report initialisation failed with content Info
var errorMessage = "403: Forbidden Error";
var adInfo = {};
var adInfo[Conviva.Constants.ASSET_NAME] = adAssetName;
convivaAdAnalytics.reportAdFailed(errorMessage, adInfo);

reportAdLoaded(adInfoopt)

Required. Report Conviva SDK on Ad Loaded event.
Parameters:
Name Type Attributes Description
adInfo Object <optional>
 Ad Info for Coniva Ad Metadata.
Examples
// Can report ad loaded without ad Info
convivaAdAnalytics.reportAdLoaded();
// Can set ad info prior to reporting of ad loaded
var adInfo = {};
adInfo[Conviva.Constants.ASSET_NAME] = adAssetName;
convivaAdAnalytics.setAdInfo(adInfo);
convivaAdAnalytics.reportAdLoaded();
// Can report ad loaded with ad info
var adInfo = {};
adInfo[Conviva.Constants.ASSET_NAME] = adAssetName;
convivaAdAnalytics.reportAdLoaded(adInfo);

reportAdMetric(metricKey, metricValuesopt)

Required. To report Playback Metrics to Conviva SDK for Ad 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.
Examples
// Reporting Playback Metric For Ad Monitoring
// Playheadtime in ms
convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.PLAY_HEAD_TIME, 10000);

// Bufferlength in ms
convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.BUFFER_LENGTH, 1000);

// Rendered framerate in fps
convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.RENDERED_FRAMERATE, 23);

// Bitrate in kbps
convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.BITRATE, 3000);

 // Average Bitrate in kbps
convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.AVG_BITRATE, 3000);

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

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

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

// Seek End
convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.SEEK_ENDED);

// IP Address can be IPv4 or IPv6 – "684D:1111:222:3333:4444:5555:6:77"
convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.CDN_IP, "19.117.63.253");
// For Client Side Ads with Ad Player Instance is different wrt Content Player Instance
// Both Metric API's need to be explicilty invoked For Content and Ad Sessions
convivaAdAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.BUFFER_LENGTH, 10000);
convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.BUFFER_LENGTH, 2000);
// For Client Side Ads with Ad Player Instance is same as Content Player Instance
// Reporting Playback Metric For Content session will not have an impact and only Ad Sessions will be impacted
convivaAdAnalytics.reportPlaybackMetric(Conviva.Constants.Playback.BUFFER_LENGTH, 10000); // ignores
convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.BUFFER_LENGTH, 10000); // reports
// For Server Side Ads with Ad Player Instance is same as Content Player Instance
// Single API is suffucient for Reporting Playback Metric For Content and Ad Sessions
convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.BUFFER_LENGTH, 10000); // reports both sessions

reportAdPlayerEvent(eventType, eventDetailopt)

Required. To report custom Player Event for Ads.
Parameters:
Name Type Attributes Description
eventType String eventType of the ad player event which should be a valid string.
eventDetail Object <optional>
 eventDetail of the ad player event.
Examples
var eventType = Conviva.Constants.Events.AD_REQUESTED;
var eventDetail = {};
eventDetail["adFrameworkName"] = "FreeWheel";
eventDetail["adFrameworkVersion"] = "1.2.3";
convivaAdAnalytics.reportAdPlayerEvent(eventType, eventDetail);
var eventType = "AdClicked";
Conviva.Analytics.reportAdPlayerEvent(eventType);

reportAdSkipped()

Required. To report Ad Skipped to end the monitoring by sending Ad Skipped custom event. This API should be invoked only after invocation of reportAdLoaded or reportAdStarted or both
Example
convivaAdAnalytics.reportAdLoaded();
convivaAdAnalytics.reportAdSkipped();

reportAdStarted(adInfoopt)

Required. Report Conviva SDK on Ad Started event.
Parameters:
Name Type Attributes Description
adInfo Object <optional>
 Ad Info for Conviva Ad Metadata.
Examples
// Can report ad started without ad Info
convivaAdAnalytics.reportAdStarted();
// Can set content info prior to reporting of ad started
var adInfo = {};
adInfo[Conviva.Constants.ASSET_NAME] = adAssetName;
convivaAdAnalytics.setAdInfo(adInfo);
convivaAdAnalytics.reportAdStarted();
// Can report ad started with ad info
var adInfo = {};
adInfo[Conviva.Constants.ASSET_NAME] = adAssetName;
convivaAdAnalytics.reportAdStarted(adInfo);

setAdInfo(adInfo)

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

setAdListener(adListener, info)

Optional. Enables Conviva to auto-collect and integrate ad analytics automatically. This API internally invokes the attached ad manager module. Supported ad manager SDKs - Google IMA
Parameters:
Name Type Description
adListener Object Ad Manager SDK instance that allows Conviva to subscribe for events
info Object Contains additional information pertaining to the ad manager like pre-loading setting, adUrl etc.
Example
GoogleIMA: convivaAdAnalytics.setAdListener(adsLoader, { Conviva.Constants.AD_PRELOAD_FEATURE : "true"});

setAdPlayerInfo(adPlayerInfo)

Required. API to set Conviva Ad Player Info metadata. Ad Player Info can be set even prior to reportAdLoaded/reportAdStarted report Conviva about Ad PLayer Info updates.
Parameters:
Name Type Description
adPlayerInfo Object Conviva Ad Player Info Object for setting the metadata and the length of the AdPlayerInfo should be grater than 0.
Example
var adPlayerInfo = {};
adPlayerInfo[Conviva.Constants.FRAMEWORK_NAME] = "IMA3";
adPlayerInfo[Conviva.Constants.FRAMEWORK_VERSION] = "3.0.0";
convivaAdAnalytics.setAdPlayerInfo(adPlayerInfo);

setCallback()

Required. Callback function invoked at a frequency of 1s to report the Conviva metrics for AdAnalytics.
Examples
// To register the callback
convivaAdAnalytics.setCallback(function() {
    convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.BUFFER_LENGTH, 1000);
    convivaAdAnalytics.reportAdMetric(Conviva.Constants.Playback.PLAY_HEAD_TIME, 2000);
});
// To de register the callback
convivaAdAnalytics.setCallback(null);