Conviva Android Sensor Integration

implementation 'com.conviva.sdk:conviva-ima-sdk:<version>'

Map<String, Object> info = new HashMap<>();
//if adTagurl is known prior
info.put(ConvivaSdkConstants.AD_TAG_URL, “adTagUrl”);

//Below code is applicable only if you are using client side ads.
//The second argument can be ConvivaSdkConstants.AdPlayer.CONTENT or ConvivaSdkConstants.AdPlayer.SEPARATE
// Pass "CONTENT" if ads and main video use the same player, and "SEPARATE" otherwise.
info.put(ConvivaSdkConstants.AD_PLAYER, ConvivaSdkConstants.AdPlayer.CONTENT.toString());


//if preloading is enabled
info.put(ConvivaSdkConstants.AD_PRELOAD_FEATURE, true);

// This API is used to initialise the IMA/DAI module and registers listeners for ad playback
adAnalytics.setAdListener (adsLoader, info); //info is optional here.

adAnalytics.reportAdMetric(
ConvivaSdkConstants.PLAYBACK.SEEK_STARTED, 10000);

adAnalytics.reportAdMetric(ConvivaSdkConstants.PLAYBACK.SEEK_ENDED);

adAnalytics.reportAdMetric(
ConvivaSdkConstants.PLAYBACK.PLAY_HEAD_TIME, 10000);

adAnalytics.reportAdMetric(
ConvivaSdkConstants.PLAYBACK.BUFFER_LENGTH, 10000);

adAnalytics.reportAdMetric(
ConvivaSdkConstants.PLAYBACK.RENDERED_FRAMERATE, 20);

videoAnalytics.reportPlaybackMetric(
ConvivaSdkConstants.PLAYBACK.BITRATE, 2200);

videoAnalytics.reportPlaybackMetric(
ConvivaSdkConstants.PLAYBACK.SEEK_STARTED, 10000);

videoAnalytics.reportPlaybackMetric(
ConvivaSdkConstants.PLAYBACK.PLAY_HEAD_TIME, 10000);

videoAnalytics.reportPlaybackMetric(
ConvivaSdkConstants.PLAYBACK.BUFFER_LENGTH, 10000);

videoAnalytics.reportPlaybackMetric(
ConvivaSdkConstants.PLAYBACK.RENDERED_FRAMERATE, 20);

adAnalytics.reportAdMetric(ConvivaSdkConstants.PLAYBACK.BITRATE, 1024);

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

5. Handle User Actions

Handle specific user actions such as:

• app backgrounding / foregrounding

• dialogues

• pin popups

• startover dialogues

• video slates, and so on

Use the corresponding API as prescribed on the corresponding pages.

User Actions: Backgrounding

ConvivaAnalytics.reportAppBackgrounded();

ConvivaAnalytics.reportAppForegrounded();

User Actions: User Dialogue

User Dialogues such as:

• pin popup

• accepting strong language / violence

• confirming age

• startover / resume dialogue

videoAnalytics.reportPlaybackEvent(ConvivaSdkConstants.Events.USER_WAIT_STARTED.toString());

videoAnalytics.reportPlaybackEvent(ConvivaSdkConstants.Events.USER_WAIT_ENDED.toString());

Data Saver

The Conviva sensor is designed in accordance with the Data Saver capabilities of Android N. When a user enables Data Saver in Settings and the device is on a metered network, the system blocks background data usage and signals apps to use less data in the foreground wherever possible.

If Data Saver setting is enabled and the app is in the allowed list, the Conviva sensor will continue to send heartbeats as the application is allowed to use data even on metered network. But if the app is not in the allowed list or is blocked, no heartbeat will be sent in the foreground as well as the background.

Report Network Metrics

If the necessary permissions are not added in the application's manifest file, the Conviva library will report the default values, after performing the necessary security checks.

To enable the Conviva library to collect the network metrics, the application must follow the Android permission instructions provided below

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>

• In Android M and later versions (API 23 and above), please add a runtime permission request for android.permission.ACCESS_COARSE_LOCATION.

• In Android Q and later versions (API 29 and above), please add a runtime permission request for android.permission.ACCESS_FINE_LOCATION.

For more details, see Android permissions.

if (Build.VERSION.SDK_INT >= 23) {
if (!(checkSelfPermission(Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
requestPermissions(new String[]{Manifest.permission.ACCESS_COARSE_LOCATION}, 0);
}
}

if (Build.VERSION.SDK_INT >= 29) {
if ( !(checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
requestPermissions(new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, 0);
}
}

List of metrics that require permissions and collection:

Cellular Signal Strength for WCDMA

Android SDK provides support for WCDMA signal strength from Android API 18 onwards, therefore Conviva sensor will not be able to report it below API level 18.

• Android L devices: Signal strength information for cellular networks in not available in Android L devices therefore Conviva sensor will not be able to report it. This is also captured as Google Android Issue: 60430.

• Android Q and above devices: With the release of Android 29, the functionality of the getAllCellInfo() API used for fetching the cellular networks signal strength information has changed. Your applications must add a new permission ACCESS_FINE_LOCATION for all devices using Android Q and above.

xmlns:tools=http://schemas.android.com/tools

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/>
<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" tools:node="remove"/>

Network Type

In most cases, the Conviva library will automatically detect the network type. It will return raw values, based on the mappings below.

Data Collection and User Preferences

By default, Conviva collects a set of data for better user analytics. However, the appropriate legal agreement with Conviva is required in order for Conviva to begin collecting data that would be considered PII, personal information, personal data or the like under applicable data privacy laws such as the General Data Protection Regulation (GDPR) and the California Consumer Privacy Act (CCPA). Further below in this document, there is a description of the user-preference APIs that control data collection, including opt-out and deletion of data, in compliance with data privacy laws. These APIs are in addition to existing, offline processes for opt-out and data deletion requests.

This document describes the identifiers that the libraries are capable of collecting, however actual collection of identifiers is contingent upon the customer's legal department providing written instructions to Conviva to begin collection. At the discretion of the customer's legal department, some or all of these identifiers may be collected. Conviva provides this flexibility to allow the customer to determine the precise identifiers to be collected.

Following tags are used to collect data:

• Android OS

• androidId: Android ID is unique to each application on a device and valid until factory reset. - gsfId: Google Service Framework ID which is provided by Play services framework. - gaId: Google Ad identifier provided by Google Play Service framework.
• Fire OS
  • fireAdId: Amazon Ad identifier provided by Amazon FireOS.

To retrieve the Google Service Framework ID, the following permission needs to be declared in the manifest.

<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />

public void setUserPreferenceForDataCollection (Map<String, Boolean> data);

Set user preferences to opt-out of data collection by specifying the corresponding tag to true/false. By default, Conviva assumes no restriction in collecting data.

where data is the Key/Value pair, where key indicates a probable data name and value is true/false. A value of true causes the SDK to allow collecting the data item and a value of false causes the SDK to stop collecting the data item.

Map<String, Boolean> data = new HashMap<>();
data.put("androidId", allowAndroidId); //allowAndroidId is true/false based on user preference.
data.put("gsfId", allowGsfId);         // allowGsfId is true/false based on user preference.
data.put("gaId",allowGaId);            // allowGaId is true/false based on user preference.
ConvivaAnalytics.setUserPreferenceForDataCollection(data);

public void setUserPreferenceForDataDeletion (Map<String, Boolean> data);

Delete previously collected data and opt-out of data collection by specifying the corresponding tag. By default, Conviva assumes no deletion of data.

where data is the Key/Value pair, where key indicates a probable data name and value is true/false. A value of true causes the SDK to delete and stop collecting that specific data item.

Map<String, Boolean> data = new HashMap<>();
data.put("androidId", deleteAndroidId);      // deleteAndroidId is true/false based on user preference.
data.put("gsfId", deleteGsfId);              // deleteGsfId is true/false based on user preference.
data.put("gaId",deleteGaId);                 // deleteGaId is true/false based on user preference.
ConvivaAnalytics.setUserPreferenceForDataDeletion(data);

Report Custom Events

Player Insight is an advanced feature which allows you to track custom events that are not related to video rendering, but rather specific to your player's functionality. These events and their attributes are then tabulated in the Player Insight dashboard at Conviva VSI (Pulse). Contact your Conviva representative to enable Player Insights in Pulse.

You may send a custom Player Insight event that can be associated with a video playback using the following method:

Report video-related events by the method videoAnalytics.reportPlaybackEvent(String eventType, Map eventDetail)

String eventType = "video_quality_change";

// Sample code snippet illustrating event on explicit change of video quality in the player
Map<String, Object> attr = new HashMap<>();
attr.put("old_quality", "SD");
attr.put("new_quality", "HD");
attr.put("player", "WEB player");
videoAnalytics.reportPlaybackEvent(eventType, attr);

Report app-level events by the method ConvivaAnalytics.reportAppEvent(String eventType, Map eventDetail):

// Syntax of the API to report the app-level  event
void reportAppEvent(String eventType, Map<String, Object> eventDetail);

// Sample for "share-click" event with 3 arguments
String eventType = "share-click";
Map<String, Object> attr = new HashMap<>();
attr.put("location", "Toolbar");
attr.put("assetName", "Sample Video");
attr.put("shareService", "Facebook");
ConvivaAnalytics.reportAppEvent(eventType, attr);

6. Clean Up Session

After the player session ends, use report and release methods to end object reporting.

videoAnalytics.reportPlaybackEnded();

//Only applicable for custom ad integration, don't call for modules
adAnalytics.adEnded();

adAnalytics.release(); // if initialized
videoAnalytics.release();
ConvivaAnalytics.release();

Advanced Use Cases

You can use specific APIs in the Conviva sensor for various advanced use cases, such as:

• Live or live linear streaming program changes
• Video changes in the playlist
• Playback does not recover from error and is reported once only
• Multiple errors due to retry when playback does not recover
• Playback recovers from a fatal error by switching to a different asset URL or CDN
• Warning occurs when there's no impact on the playback
• Handling user actions, such as user dialogues, backgrounding, and foregrounding

To learn more about these advanced use cases, see here.

Self Validation

Upon completion of your integration, and before submission to Conviva QA team, developers should complete a comprehensive self-validation test pass of each Device Application.

Conviva provides sample test cases with detailed steps and expected results.

Developers should be checking for both metric and metadata accuracy. Based on our experience, comprehensive self-validation can reduce your QE cycles, saving your costly project time.

For more information about self-validating the builds, downloading the test cases, and viewing sample validation videos, refer to the Self-Validation page.