MKConvivaAnalyticsCollector - v1.0.0

MKPlayer Conviva analytics collector plugin.

MKConvivaAnalyticsCollector is a MKPlayer plugin that adds support for Conviva analytics to collect variety of player, user and app specific metrics.

This plugin makes use of Conviva JavaScript Core SDK version 4.4.3 or newer and must be used with MKPlayer version 1.8.0 or newer. Also you must have an active account and license agreement from Conviva to use this plugin. Please refer to the documentation from Conviva for more information.

Please follow the instructions on this page to understand how to properly add this plugin to MKPlayer.

Getting started.

Install the plugin via NPM as below. As this is a private plugin, please reach out to MediaKind team for access.

npm install @medikind/mkplayer-conviva-plugin

Include mkplayer-conviva-plugin.js in the head of your HTML along side mkplayer.js as below:

<head>
    <title>My Video Player</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!-- MKPlayer JavaScript and CSS along with MKConvivaAnalyticsCollector -->
    <script  type="text/javascript"  src="./node_modules/@mediakind/mkplayer/mkplayer.js"></script>
    <link  rel="stylesheet"  href="./node_modules/@mediakind/mkplayer/mkplayer-ui.css">
    <script type="text/javascript" src="./node_modules/@mediakind/mkplayer-conviva-plugin/mkplayer-conviva-plugin.js"></script>
</head>

Initialize the plugin as below:

// Initialize MKPlayer as before with video container and player config.
const player = new mkplayer.MKPlayer(videoContainer, playerConfig);

// MKConviaAnalyticsCollectorConfig
// please refer to the documentation for all the properties available in the configuration.
const convivaAnalyticsCollectorConfig = {
    key: "<YOUR CONVIVA CUSTOMER KEY>",
    appName: "<YOUR APPLICATION NAME>",
    appVersion: "<YOUR APPLICATION VERSION>",
    viewerId: "<YOUR CUSTOMER UINQUE ID>",
    deviceMetadat: {}, // Optional device metadata
    devMode: true      // to enable development mode or `false` to use production mode
};

// Initialize the plugin
const convivaAnalyticsCollector = new mkplayerConvivaPlugin.MKConvivaAnalyticsCollector(player, convivaAnalyticsCollectorConfig);

After this step, no additional settings are required, proceed to start playback normally with MKPlayer and the plugin should automatically take care of setting things up and publish necessary metrics to the dashboard.

Please also refer to the API documentation for the list of public APIs that are available and how to use them.

Note: The lifecycle of the plugin is tied to the player instance that was passed at the time of initialization. So when the player is destroyed the plugin internally releases all resources and self-destructs, so you must ensure to re-initialze the plguin with a new player instance if you wish to use it again. There is no explicit need to call destroy() on the plugin unless you want to explicitly release the plugin and stop using analytics.

You can call destroy on the plugin to release all resources and exit. But please note that a new instance of plugin will need to be created after a call to destroy and no API must be used after this call.

convivaAnalyticsCollector.destory();

Analytics data that is collected and published by the plugin

Once you set things up as described above, the following analytics metrics are automatically collected by the plugin and plublished which you should be able to verify by visiting touchstone.

After the plugin is initialzed, no further action or API needs to be called to trigger the collection of these metrics. However if you wish to publish any custom events, then updateCustomPlaybackEvent() and updateCustomApplicationEvent() APIs are available. Please refer to the documentation for their usage related information.

Device Metadata

  • Device category is always WEB for this SDK.
  • Any other optional device metada overrides if configured in the plugins collector configuration.

Player Information

  • FRAMEWORK_NAME: This can be either native to indicate platforms native player being used or html5 to indicate when MSE/HTML5 player is being used for playback.

Content Information

  • PLAYER_NAME: always MKPlayer-Web-<sdk-version> (Example: MKPlayer-Web-1.8.0)
  • ASSET_NAME: mediaId for a registered source content or title if set in the player source configuration. It is recommended to always set a valid title when using direct sources and for registered source mediaId will be used.
  • VIEWER_ID: as set in the plugin collector configuration.
  • appName*: your application name if set in the plugin collector configuration.
  • appVersion*: your application version if set in the plugin collector configuration.
  • streamUrl: the source manifest URL which will be updated once playback is about to start.
  • IS_LIVE: is updated once playback is about to start.
  • streamFormat*: is either hls or dash and updated once playback is about to start..
  • drmType*: can be Fairplay or Widevine or Playready and is updated once playback is about to start.
  • DURATION: the current duration in seconds for the current source. This is updated once playback starts. For live this value may change as playback progresses which indicates the DVR window duration in seconds.

* These are custom tags and if you do not find this information on your analytics dashboard, please work with your Conviva representative to understand how to get these custom tags enabled for your account.

Custom Playback Events The plugin publishes a few of the below custom playback metrics. Any additional custom playback events if needed can be published by the application by calling updateCustomPlaybackEvent() plugin API.

  • muted: when audio is muted
  • unmuted: when audio is unmuted
  • resized: when the player video window size is changed. Ex: when toggling fullscreen or resizing the player window.
  • timeShift: only updated for live streams which is a negative offset less than 0 which indicates the number of seconds behind the live edge which is always 0.
  • maxTimeShift: only updated for live streams which is a negative offset less than 0 which indicates the max number of seconds of seekable range from the current live edge which is always 0. Example a value of -1800 would indicate availablilty of 30 minutes of seekable range from live edge.

Playback Metrics

  • PLAY_HEAD_TIME: current player position in milliseconds.
  • BUFFER_LENGTH: reports the current video forward duration buffer length (represented as number of seconds).
  • DROPPED_FRAMES_COUNT: reportes the number of dropped video frames if available.
  • PLAYER_STATE: reports current player state for PLAYING, PAUSED, BUFFERRING or STOPPED states.
  • SEEK_STARTED: reported when seeking starts.
  • SEEK_ENDED: reported when seeking ends.
  • AUDIO_LANGUAGE: the current audio track language related information.
  • SUBTITLE_LANGUAGE or CLOSED_CAPTIONS_LANGUAGE: subtitle or closed captions language information is published. It either subtitle or closed caption information and never both. While one is published the other is reported as off.
  • BITRATE: this information is available on certain platroms such as Chrome and not on Safari as its not availabe from the native player. But where available this information is published and reports the current bitrate values in kbps.
  • RENDERED_FRAMERATE: this information is available only on certain platforms such as Chrome browser and is derived from the player SegmentPlaybackEvent that too if this segment playback event contains related to frame rate in the mediaInfo property. For most other platforms this is not published.

References

Settings

Member Visibility

Theme

On This Page