Analytics Integration

The Cloud Solution includes a complete implementation to use Conviva video analytics for your app. To use Conviva, you only need to add a property in the client manifest.

The Cloud Solution also includes a reference implementation of Adobe Analytics. To use Abode Analytics, you need to:

• Add a property in the client manifest
• Implement an events handler in a BrightScript file
• Define some SceneGraph XML
• Modify the reference implementation to suit your particular needs

Note If you want to implement other analytics services, for example Google Analytics, You.i TV recommends that your implementation follow a pattern similar to that used for Conviva and Adobe Analytics.

Manifest Changes

In the client manifest, define a property named analytics_providers with a comma-separated list of analytics providers; for example:

analytics_providers=AdobeAnalytics,ConvivaAnalytics

conviva_gateway_url=https://<conviva_app_name>.conviva.com
conviva_api_key=<conviva_app_api_key>

where <conviva_app_name> and <conviva_app_api_key> are the credentials for your app with the Conviva service.

If the analytics_providers property is not defined, the default RMFAnalyticsDefault handler is created and used. The default RMFAnalyticsDefault handler only does logging.

SceneGraph XML Code

Define XML client code such as the following:

<?xml version="1.0" encoding="utf-8" ?>
<component name="AdobeAnalytics" extends="ContentNode">
   <interface>
      <function name="initialize"/>
      <function name="setVideoData"/>
      <function name="reportBuffering"/>
      <function name="reportPlaying"/>
      <function name="reportPaused"/>
      <function name="reportFinished"/>
      <function name="reportPosition"/>
      <function name="reportBitrate"/>
      <function name="reportPlayerClosed"/>
      <function name="reportError"/>
      <function name="getVisitorID"/>
   </interface>
 
   <script type="text/brightscript" uri="pkg:/components/adobe-analytics.brs"/>
   <script type="text/brightscript" uri="pkg:/source/utils.brs" />
</component>

The <Component name> entry in the XML must match with the analytics_providers entry in the manifest. It must also extend ContentNode.

You.i TV recommends that your XML client code include all the same functions in the interface because all analytics providers are handled in the same abstracted AnalyticsDispatcher. See the following table for more information on the argument and return type for the functions used:

Add the name of the BrightScript file containing your implementation of the actual event handler to the script section of the XML code. In this example, the implementing file is adobe-analytics.brs.

Each analytics provider that is specified in the manifest is created and added to the list in the AnalyticsDispatcher.

Custom Metadata

Some analytics services, such as Conviva, may require custom metadata. The metadata they require may also vary depending on the app. Use video player metadata key-value string pairs in your app code to specify the required custom information. Add a reserved prefix to each property name for the required metadata. The Cloud Solution uses a JSON object as an intermediary between the video player and the analytics service to mediate between data type requirements.

The Cloud Solution currently uses the following reserved prefixes:

• convivaInfo, for content information variables
• convivaTag, for properties for the contentInfo.tag field
• assetname, to optionally supply the video title. The original video title is used if assetname is empty or invalid.

For details see ConvivaAnalytics.brs, ConvivaAnalytics.xml, and Conviva_Roku_SgClient.brs.

The following example is for a particular set of custom information for Conviva. The requirement is that the app provides properties for content information variables and the contentInfo.tag field. So for this use case, you can declare the following JSON object in your C++ app code:

/* Conviva information example
{
   "convivaInfo": {
      "streamUrl": "http://link.theplatform.com/s/BpkrRC/ckSTzzdGO_K3",
      "isLive": false,
      "viewerId": "CloudTester",
      "playerName": "Roku",
      "streamFormat": "HLS"
   },
   "convivaTag": {
      "assetID": "ckSTzzdGO_K3",
      "videoType": "VOD",
      "streamProtocol": "HLD"
   },
   "assetname": "Some different name other than original asset Title. This is optional and the original video title will be used if this is empty or invalid."
}
*/

   yi::rapidjson::Document convivaInfo;
   convivaInfo.SetObject();
   CYIRapidJSONUtility::AddStringField(&convivaInfo, "streamUrl", "http://link.theplatform.com/s/BpkrRC/ckSTzzdGO_K3");
   CYIRapidJSONUtility::AddBooleanField(&convivaInfo, "isLive", false);
   CYIRapidJSONUtility::AddStringField(&convivaInfo, "viewerId", "CloudTester");
   CYIRapidJSONUtility::AddStringField(&convivaInfo, "playerName", "Roku");
   CYIRapidJSONUtility::AddStringField(&convivaInfo, "streamFormat", "HLS");

   yi::rapidjson::Document convivaTag;
   convivaTag.SetObject();
   CYIRapidJSONUtility::AddStringField(&convivaTag, "assetID", "ckSTzzdGO_K3");
   CYIRapidJSONUtility::AddStringField(&convivaTag, "videoType", "VOD");
   CYIRapidJSONUtility::AddStringField(&convivaTag, "streamProtocol", "HLS");

   yi::rapidjson::Document convivaObject;
   convivaObject.SetObject();
   CYIRapidJSONUtility::AddObjectField(&convivaObject, "convivaInfo", convivaInfo);
   CYIRapidJSONUtility::AddObjectField(&convivaObject, "convivaTags", convivaTag);
   CYIRapidJSONUtility::AddStringField(&convivaObject, "assetname", "BigBug Bunny on CloudTester");

   CYIAbstractVideoPlayer::VideoMetadata metadata;
   metadata.insert({"conviva", CYIRapidJSONUtility::CreateStringFromDocument(convivaObject)});

   CYICloud::GetInterface().SetVideoMetadata(m_pPlayer.get(), metadata);