Conviva Android Quick Integration

This page serves as a quick reference for your integration, containing mostly code snippets that you'll need at various stages of integration. For more information or if you need any help, refer to the details on Conviva Android Sensor Integration page.

This documentation is for Android SDK 4.0.2 and above. If you are using the legacy SDK, we highly recommend you upgrade to the new SDK below. Please note that the legacy SDK is deprecated and is not supported from version 4.0.18 and above.

Integration Summary

Click an image to view the API call sequence:**

Android Custom Integration (SDK Only)	Conviva Android Player Modules
Use for video players other than Brightcove, ExoPlayer, or NexStreaming. Report all the playback metrics, such as bitrate, player states, seek, buffering, and user actions. For API call details, refer to Android Custom Integration API List.	Use for Brightcove, ExoPlayer, and NexStreaming video players. Modules autocollect most playback metrics, such as bitrate, player states, seek, and buffering. For API call details, refer to Android Module Integration API List.

Integration Summary Steps

1. Install Conviva Library

• Install the library and add dependencies.

• Initialize the ConvivaAnalytics object using your CUSTOMER_KEY.

• Create an instance of ConvivaVideoAnalytics as a videoAnalytics object to report video related events.

  • If your player has ads: Create an instance of ConvivaAdAnalytics as a adAnalytics object to report ad related events.

2. Configure Metadata

• Implement the metadata by following the instructions to use the pre-defined keys, as well as custom metadata, if applicable.

• Implement device metadata (optional). By default, Conviva SDK autocollects Android device metadata.

3. Report Events and Metadata

Implement the videoAnalytics.reportPlaybackRequested(contentInfo) method to report playback attempt request along with metadata (content, workflow, audience, and other relevant metadata). Use the videoAnalytics.reportPlaybackEnded() method to report the of end playback.

1. Integrate Video Players Add Conviva module dependency for your video player (if available), and pass player instance to Conviva by calling videoAnalytics.setPlayer(playerInstance). If following custom integration guidelines, implement video events & metric reporting as prescribed by the corresponding specification. Add Conviva module dependency for your ad player (if available), and pass ad loader instance to Conviva by calling adAnalytics.setAdListener (adsLoader, settingsInfo);. If following custom integration guidelines, implement ad metadata, events & metric reporting as prescribed by the corresponding specification.

2. Handle User Actions

• Implement the ConvivaAnalytics.reportAppBackgrounded() / ConvivaAnalytics.reportAppForegrounded() methods to report background events.

• Implement videoAnalytics.reportPlaybackEvent() method to report user events (user actions, user dialogue, etc).

• Set the permissions to enable the collection of Network Metrics, manage Data Collection and User Preferences.

2. Clean Up

Call 'release' methods to cleanup ConvivaAnalytics, videoAnalytics, adAnalytics objects upon application exit.

Test and Validate

1. After integration, perform a sanity check following the test cases in the Stream Sensor Sanity Test Plans spreadsheet. For the full validation test, use the test cases in the Stream Sensor Full Test Plans spreadsheet.

2. Use Touchstone in Pulse to debug your implementation if required.

3. Be sure to replace your TEST CUSTOMER_KEY with the PRODUCTION key and go live with your application.**Make sure the GATEWAY_URL for Touchstone is NOT used in Production!

4. Done! Analyse your data in Pulse and improve your viewer experience - let's make video experience better!

1. Install Conviva Library

Add Conviva Libraries and Configure Dependencies

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

ConvivaAnalytics.init(Context appContext, String customerKey, Map<String, Object> settings);

if(BuildConfig.DEBUG) {
   Map<String, Object> settings = new HashMap<>();
   String gatewayUrl = "YOUR Touchstone Service URL";
   settings.put(ConvivaSdkConstants.GATEWAY_URL, gatewayUrl);
   settings.put(ConvivaSdkConstants.LOG_LEVEL, ConvivaSdkConstants.LogLevel.DEBUG);
   ConvivaAnalytics.init (getApplicationContext(), TEST_CUSTOMER_KEY, settings);
}else{
   //production release
   ConvivaAnalytics.init (getApplicationContext(), PRODUCTION_CUSTOMER_KEY);
}

ConvivaVideoAnalytics videoAnalytics = ConvivaAnalytics.buildVideoAnalytics(getApplicationContext());
Map<String, Object> contentInfo = new HashMap<>();
contentInfo.put(ConvivaSdkConstants.ASSET_NAME, "[channel_id] Live Channel Name");
// set the values for the other pre-defined keys as appropriate, refer to the tables below
contentInfo.put("c3.cm.contentType", "Live-Linear");
// set the values for custom tags as required per definition for your account
contentInfo.put("my_custom_tag_key", "my_custom_tag_value");
videoAnalytics.setContentInfo(contentInfo);

ConvivaAdAnalytics adAnalytics = ConvivaAnalytics.buildAdAnalytics(getApplicationContext(),videoAnalytics);

2. Configure Metadata

Conviva categorizes metadata tags into three buckets (Predefined, Device, Custom).

Pre-defined Video and Content Metadata

The constants below are defined in the class com.conviva.sdk.ConvivaSdkConstants.

Constants for Pre-defined Video and Content Metadata

Map<String, Object> playerInfo = new HashMap<>();
playerInfo.put(ConvivaSdkConstants.FRAMEWORK_NAME, "YOUR_FRAMEWORK_NAME");
videoAnalytics.setPlayerInfo(playerInfo);

Map<String, Object> playerInfo = new HashMap<>();
playerInfo.put(ConvivaSdkConstants.FRAMEWORK_VERSION, "1.2.3");
videoAnalytics.setPlayerInfo(playerInfo);

Device Metadata

Device Metadata Instructions (Click to Expand):

Map<String, Object> deviceInfo = new HashMap<>();
deviceInfo.put(ConvivaSdkConstants.DEVICEINFO.DEVICE_BRAND, "Google");
// set the rest of the required metadata fields as per the table below
ConvivaAnalytics.setDeviceInfo(deviceInfo);

Custom Metadata

Refer to App Manager-> Metadata -> Custom Metadata page for your account to find the custom tags which shall be implemented.

Set custom tags in a similar way for either video or ads, by adding the tags to the contentInfo or adInfo objects, passed into corresponding methods of videoAnalytics / adAnalytics objects.

Update/Amend Metadata

The device metadata can be immediately set when the values are available.

Example usage:

Map<String, Object> contentInfo = new HashMap<>();
contentInfo.put(ConvivaSdkConstants.ASSET_NAME, "[channel_id] Live Channel Name");
// set the values for the other pre-defined keys as appropriate, refer to the tables below
contentInfo.put("c3.cm.contentType", "Live-Linear");
// set the values for custom tags as required per definition for your account
contentInfo.put("my_custom_tag_key", "my_custom_tag_value");
 
videoAnalytics.setContentInfo(contentInfo);

3. Report Events and Metadata

videoAnalytics.reportPlaybackRequested(Map<String, Object> contentInfo)

// Ad Break Start for client side ad insertion with separate player instance for ads
videoAnalytics.reportAdBreakStarted(ConvivaSdkConstants.AdPlayer.SEPARATE, ConvivaSdkConstants.AdType.CLIENT_SIDE);
 
// Ad Break Start for client side ad insertion with same player instance for ads
videoAnalytics.reportAdBreakStarted(ConvivaSdkConstants.AdPlayer.CONTENT, ConvivaSdkConstants.AdType.CLIENT_SIDE);

// Server-side ads are embedded within the main video content
// Ad Break Start for server-side ads
videoAnalytics.reportAdBreakStarted(ConvivaSdkConstants.AdPlayer.CONTENT, ConvivaSdkConstants.AdType.SERVER_SIDE);

videoAnalytics.reportAdBreakEnded();

videoAnalytics.reportPlaybackEnded();

4. Integrate Video Players

If instructions for your player are not shown below, please follow the instructions for "Custom Integration", or contact your Conviva representative.

Exoplayer

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

videoAnalytics.setPlayer(SimpleExoPlayer);

Map<String, Object> contentInfo = new HashMap<>();
contentInfo.put(ConvivaSdkConstants.DURATION, 126);
videoAnalytics.setContentInfo(contentInfo);

Custom Integration

// 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);

// integer parameter in kbps for this key ConvivaSdkConstants.PLAYBACK.BITRATE
videoAnalytics.reportPlaybackMetric(ConvivaSdkConstants.PLAYBACK.BITRATE, 3600);

// Syntax of the API to register the ICallback interface used to invoke for every 1 sec by Conviva
void setCallback(ICallback callback);
 
// Sample code snippet
ConvivaExperienceAnalytics.ICallback callback = new ConvivaExperienceAnalytics.ICallback() {
    @Override public void update() {
      videoAnalytics.reportPlaybackMetric(ConvivaSdkConstants.PLAYBACK.BUFFER_LENGTH, 30000);
      videoAnalytics.reportPlaybackMetric(ConvivaSdkConstants.PLAYBACK.PLAY_HEAD_TIME, 10000);
      videoAnalytics.reportPlaybackMetric(ConvivaSdkConstants.PLAYBACK.RENDERED_FRAMERATE, 20);
    }
};
videoAnalytics.setCallback(callback);

NexStreaming

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

videoAnalytics.setPlayer(nexPlayer);

Brightcove

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

videoAnalytics.setPlayer(brightcovePlayer);

Integrate Ad Managers

If instructions for your Ad SDK are not shown below, please follow the instructions for "Custom Ad Manager" integration, or contact your Conviva representative.

Google IMA/DAI

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.SEEK_ENDED);

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:

API Diagrams for Custom Ad Integration

Click an image to view the API call sequence:

**CSAI**

**SSAI**

NM* - During the Non-monitoring state, while the ad plays, the main video is not tracked. However, the ad metrics are tracked in Ad Experience and reported in Pulse Ad Metrics. Ad Session is Ad Attempt to Ad End. Ad Actual Play Time is Ad Play to Ad End. Total Ad Duration is Ad Start to Ad End. Reporting Ad Pod/Break Start and Ad Pod/Break End can provide additional insights about ad pods in the Conviva VSI Overview dashboard Improvement Opportunities data.

Stitched ad events are included in the video stream tracking. Ad session is from Ad Start to Ad End. Ad Actual Play Time is from Ad Play to Ad End. For SSAI because AST is short, Ad Duration typically equals Ad Actual Play Time. Ad errors are reported in both video sessions and Ad sessions. Reporting Ad Pod/Break Start and Ad Pod/Break End can provide additional insights in the Conviva VSI Overview dashboard Improvement Opportunities data. Ad metrics are also tracked in Ad Experience and reported in Pulse ad metrics.

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 SDK 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 SDK 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 SDK 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 SDK 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"/>

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);

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

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.reportAdEnded();

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

To know about the advanced use cases and the self-validation process, refer to the Conviva Android Sensor page.