Enriching_Player_Analytics_with_Custom_Event_Data .md

Enriching Player Analytics with Custom Event Data

While Kaltura collects most of the highly requested and common analytics data points, sometimes you may require information that is not already collected. Kaltura provides a convenient way for you to collect any kind of data you want with the customVar feature.

Configuring the player

Kaltura players accept a customVar argument through the KAVA analytics framework. These are named customVar1, customVar2 and customVar3.

Configuring Javascript Player

First check in the KMC to make sure the KAVA plugin is enabled on your player: it is enabled by default.

Next configure the player to accept customVar1 via KAVA:

     var player = KalturaPlayer.setup({
                targetId: "kaltura-player",
                provider: {
                    partnerId: 12345,
                    uiConfId: 678910
                },
                plugins: {
                    kava: {
                        customVar1: "hello"
                    }
                }
            });

Configuring iOS Player

If you refer to the iOS analytics documentation, you will notice the createKavaConfig method below accepts customVar[123]

func createKavaConfig() -> KavaPluginConfig {
    return KavaPluginConfig(partnerId: PARTNER_ID, entryId: entryId, ks: ks, playbackContext: nil, referrer: nil, applicationVersion: nil, playlistId: nil, customVar1: nil, customVar2: nil, customVar3: nil)
}

Configuring Android Player

Refer to the android player setup page which also links to the Android KAVA demo

            //Set your configurations.
            KavaAnalyticsConfig kavaConfig = new KavaAnalyticsConfig()
                    .setPartnerId(123456) //Your partnerId. Mandatory field!
                    .setBaseUrl("yourBaseUrl")
                    .setUiConfId(123456)
                    .setKs("your_ks")
                    .setCustomVar1("customVar1")
                    .setCustomVar2("customVar2")
                    .setCustomVar3("customVar3");

Querying Analytics for customVar

Now that you have supplied customVar to your player, and users are interacting with your players, you will want to see how your customVar data is performing.

Using the Kaltura analytics API you will be able to create different kinds of reports for your customVar.

TOP_CONTENT report

Using the report.getTable API call, as shown below, a reportType of TOP_CONTENT is produced and it allows you to filter by string via the customVar1In field of reportInputFilter

Which will return a tab-delimited report like:

{
  "header": "object_id,entry_name,count_plays,sum_time_viewed,avg_time_viewed,count_loads,load_play_ratio,avg_view_drop_off,unique_known_users",
  "data": "1_z81cf9,TAKE2_EDIT,6,1,1,9,1,1,1;
           1_em9nua,inside    ,1,0,0,1,1,0,1;",
  "totalCount": 2,
  "objectType": "KalturaReportTable"
}

As you can see, a ; delimited list of all the entryIds that matched "hello" were returned in the data object.

CUSTOM_VAR report

If you wanted to query all of the customVar data for your account, this is also possible using a reportType of TOP_CUSTOM_VAR1, TOP_CUSTOM_VAR2, or TOP_CUSTOM_VAR3

Which returns the following result:

{
  "header": "custom_var1,count_plays,sum_time_viewed,avg_time_viewed,count_loads,load_play_ratio,avg_view_drop_off",
  "data": "hello,6,0.533,0.088888,9,1,0.6;                				
  	       world,1,0.066,0.066666,1,1,0.5;",
  "totalCount": 2,
  "objectType": "KalturaReportTable"
}

As you see the "hello" and "world" are the two customVar1 that have been used with this account during the specified time period.