Namespace: Analytics

Analytics

Main Conviva SDK class.
Most applications will only need one Analytics, created during application initialization and released during application shutdown. Provides the wrapper API's for SDK Initialisation and Global App Event API's.

Members

(static, constant) version :string

The current version of the Conviva Simplified SDK.
Type:
  • string

Methods

buildAdAnalytics(videoAnalyticsopt) → {AdAnalytics}

Required. To build the Ad Analytics component.
Parameters:
Name Type Attributes Description
videoAnalytics VideoAnalytics <optional>
 Can link VideoAnalytics object created for main video session. Empty argument incase of only Ad Monitoring decoupled with main video monitoring.
Throws:
When invoked without Analytics#init.
Type
Error
Returns:
Conviva component used for monitoring the ad analytics.
Type
AdAnalytics
Examples
// To link the main video monitoring with ad monitoring
var convivaAdAnalytics = Conviva.Analytics.buildAdAnalytics(convivaVideoAnalytics);
// To create decoupled ad monitoring
var convivaAdAnalytics = Conviva.Analytics.buildAdAnalytics();

buildVideoAnalytics() → {VideoAnalytics}

Required. To build the Video Analytics component.
Throws:
When invoked without Analytics#init.
Type
Error
Returns:
Conviva component used for monitoring the video analytics.
Type
VideoAnalytics
Example
var convivaVideoAnalytics = Conviva.Analytics.buildVideoAnalytics();

configureExistingClient(client)

Required. To configure Analytics module with the Conviva Client created by the application. This is used for new AI integration on top of legacy EI integration
Parameters:
Name Type Description
client Client Conviva Client instance created by the application.
Throws:
When invoked without instantiating Client.
Type
Error
Example
// Conviva Client Instance is created
var systemSettings = new Conviva.SystemSettings();
var systemInterface = new Conviva.SystemInterface(
  new TimeInterfaceImplementation(),
  new TimerInterfaceImplementation()
  new HttpInterfaceImplementation(),
  new StorageInterfaceImplementation(),
  new MetadataInterfaceImplementation(),
  new LoggingInterfaceImplementation()
  );
var systemFactory = new Conviva.SystemFactory(systemInterface, systemSettings);
var clientSettings = new Conviva.ClientSettings("1p4r5ff4r3e435c201e8e9a3er5t60952f5191d7");
clientSettings.gatewayUrl = "https://customerurl.conviva.com";
var client = new Conviva.Client(clientSettings, systemFactory);

// Configure the client instance created to Conviva Analytics Component
Conviva.Analytics.configureExistingClient(client);

init(customerKey, callbackFunctions, optionsopt)

Parameters:
Name Type Attributes Description
customerKey String Unique customer key provided by Conviva.
callbackFunctions Object Callback functions with platform specific system utility functions.
Pass the object if application chose using custom utility functions.
Set as null if application chose using Conviva default utility functions.
options Object <optional>
 Conviva Configs used for setting GATEWAY_URL and LOG_LEVEL. Not required for production applications.
Throws:
When parameters are invalid or instantiation fails.
Type
Error
Examples
// With custom system utility functions and development environment
var customerKey = "1p4r5ff4r3e435c201e8e9a3er5t60952f5191d7";
var callbackFunctions = {};
callbackFunctions[Conviva.Constants.CallbackFunctions.CONSOLE_LOG] = function (message, logLevel) {
console.log(message, Conviva.SystemSettings.LogLevel.DEBUG);
};
callbackFunctions[Conviva.Constants.CallbackFunctions.MAKE_REQUEST] = function (httpMethod, url, data, contentType, timeoutMs, callback) {

};
callbackFunctions[Conviva.Constants.CallbackFunctions.SAVE_DATA] = function() {
};
callbackFunctions[Conviva.Constants.CallbackFunctions.LOAD_DATA] = function() {
};
callbackFunctions[Conviva.Constants.CallbackFunctions.GET_EPOCH_TIME_IN_MS] = function() {
};
callbackFunctions[Conviva.Constants.CallbackFunctions.CREATE_TIMER] = function() {
};
var options = {};
options[Conviva.Constants.LOG_LEVEL] = Conviva.Constants.LOG_LEVEL.DEBUG;
options[Conviva.Constants.GATEWAY_URL] = "https://customerurl.conviva.com";
Conviva.Analytics.init(customerKey, callbackFunctions, options);
// With Conviva default system utility functions and development environment
var customerKey = "1p4r5ff4r3e435c201e8e9a3er5t60952f5191d7";
var options = {};
options[Conviva.Constants.LOG_LEVEL] = Conviva.Constants.LOG_LEVEL.DEBUG;
options[Conviva.Constants.GATEWAY_URL] = "https://customerurl.conviva.com";
Conviva.Analytics.init(customerKey, null, options);
// With Conviva default system utility functions and production environment
var customerKey = "1p4r5ff4r3e435c201e8e9a3er5t60952f5191d7";
Conviva.Analytics.init(customerKey, null);

release()

Required. To be released during application shutdown.
Example
Conviva.Analytics.release();

reportAppBackgrounded()

Required. To report App Backgrounding.
Throws:
When invoked without Analytics#init.
Type
Error
Example
Conviva.Analytics.reportAppBackgrounded();

reportAppEvent(eventType, eventDetailopt)

Required. To report any Global Event associated to application not associated to playaback.
Parameters:
Name Type Attributes Description
eventType String Event Type of the App event.
eventDetail Object <optional>
 Event Details of the App event.
Throws:
When invoked without Analytics#init.
Type
Error
Example
var eventType = "share-click";
var eventDetail = {};
eventDetail["location"] = "Toolbar";
eventDetail["shareService"] = "Facebook";
Conviva.Analytics.reportAppEvent(eventType, eventDetail);

reportAppForegrounded()

Required. To report App Foregrounding.
Throws:
When invoked without Analytics#init.
Type
Error
Example
Conviva.Analytics.reportAppForegrounded();

reportDeviceMetric(metricKey, metricValuesopt)

Required. To report Device Metric to Conviva SDK common for both Main Video Content and Ad Content.
Parameters:
Name Type Attributes Description
metricKey String Used for setting the Conviva Playback Metrics or Network Metrics.
metricValues integer | string <optional>
 Used for setting the metric value.
Example
// The values to be mapped are "Ethernet", "WiFi", "4G", "3G", "2G", "OTHER".
// If you can fetch wireless connection sub-type, such as "802.11 a", "802.11b", "802.11n", "802.11g",
// then pass the sub-type instead of "WiFi".
// If you can measure 4G data connection sub-type like "LTE", then pass the sub-type instead of "4G".
// Single API is sufficient for reporting for Content and Ad Sessions as Network Metrics are device specific
Conviva.Analytics.reportDeviceMetric(Conviva.Constants.Network.CONNECTION_TYPE, "WiFi");

// The network connection's link encryption type, if available.
// API accepts string values and can be of values "WEP", "WPA-TKIP",
// "WPA-AES", "WPA2", "EAP", "OPEN"...
// Single API is sufficient for reporting for Content and Ad Sessions as Network Metrics are device specific
Conviva.Analytics.reportDeviceMetric(Conviva.Constants.Network.LINK_ENCRYPTION, "WEP");

// Signal Strength in dBm
// Single API is sufficient for reporting for Content and Ad Sessions as Network Metrics are device specific
Conviva.Analytics.reportDeviceMetric(Conviva.Constants.Network.SIGNAL_STRENGTH, -500);

setDeviceMetadata(deviceMetadata)

Required. API to set Device Info metadata. Device Metadata is applicable for one analytics component and is common for all video and ad anlytics.
Parameters:
Name Type Description
deviceMetadata Object Device Metadata Object for setting the metadata and the length of the Device Metadata should be grater than 0.
Throws:
When invoked without Analytics#init.
Type
Error
Example
var deviceMetadata = {};
deviceMetadata[Conviva.Constants.DeviceMetadata.BRAND] = "Apple";
deviceMetadata[Conviva.Constants.DeviceMetadata.MANUFACTURER] = "Apple";
deviceMetadata[Conviva.Constants.DeviceMetadata.MODEL] = "MacBookPro";
deviceMetadata[Conviva.Constants.DeviceMetadata.TYPE] = Conviva.Constants.DeviceType.DESKTOP;
deviceMetadata[Conviva.Constants.DeviceMetadata.VERSION] = "NAForMac";
deviceMetadata[Conviva.Constants.DeviceMetadata.OS_NAME] = "MAC";
deviceMetadata[Conviva.Constants.DeviceMetadata.OS_VERSION] = "10.13.6";
deviceMetadata[Conviva.Constants.DeviceMetadata.CATEGORY] = Conviva.Constants.DeviceCategory.WEB;
deviceMetadata[Conviva.Constants.DeviceMetadata.SCREEN_RESOLUTION_WIDTH] = 1920;
deviceMetadata[Conviva.Constants.DeviceMetadata.SCREEN_RESOLUTION_HEIGHT] = 1080;
deviceMetadata[Conviva.Constants.DeviceMetadata.SCREEN_RESOLUTION_SCALE_FACTOR] = 1.0;
Conviva.Analytics.setDeviceMetadata(deviceMetadata);

setUniqueIdentifier(identifiers, callback)

Required To set a unique identifier for device / user. For eg: deviceId, Mac address, advertisingIdentifier etc.
Parameters:
Name Type Description
identifiers Object Key/Value pair indicating a probable data name and value
callback function A callback function name to which success/failure of the data collection to be notified
Throws:
When invoked without Analytics#init.
Type
Error
Example
var identifiers = {};
identifiers.gsfid = "88hwh9h9h9wjef";
Conviva.Analytics.setUniqueIdentifier(identifiers, function(msg) { console.log(msg) });

setUserPreferenceForDataCollection(identifiers, forAllApps)

Required to set the user preference to collect or stop collecting PII data items that are being collected
Parameters:
Name Type Description
identifiers Object Key/Value pair. key indicates a probable data name and value is false/true. If it is false, SDK will stop collecting that specific data item.
forAllApps Boolean True if end-user has restricted all apps on device from data collection. false if only current app is restricted.
Throws:
When invoked without Analytics#init.
Type
Error
Example
var identifiers = {};
identifiers.gsfid = "false";
Conviva.Analytics.setUserPreferenceForDataCollection(identifiers, true); // OR
Conviva.Analytics.setUserPreferenceForDataCollection(identifiers, false);

setUserPreferenceForDataDeletion(identifiers)

Required to set the user preference to Delete or stop collecting specific data items that are being collected
Parameters:
Name Type Description
identifiers Object Key/Value pair. key indicates a probable data name and value is false/true. If it is true, SDK will stop collecting that specific data item and notifies Conviva back-end to delete all data related to user.
Throws:
When invoked without Analytics#init.
Type
Error
Example
var identifiers = {};
identifiers.gsfid = "true";
Conviva.Analytics.setUserPreferenceForDataCollection(identifiers);