Integrate Bitmovin Player events with your custom metrics report system

Resources
, ,
1

The Bitmovin Player SDKs offer a variety of events that are triggered on several situations during the playback. Generally triggered by user interactions like play/pause/seek, but also by playback inherent changes like ABR quality change, Timed metadata available, etc.
Also the events would be triggered when something unexpected happens, like a network error, incompatible codec, and so on.
A complete list of the available events can be found on each Player SDK:

Suscribing to Events
Most of the Analytics/Metrics Report Systems will benefit from the event based player to collect and submit the playback data.
To listen/suscribe to the events, an event handler is needed. The event handler will spec ify the logic required to connect to the Analytics/Metrics System, which in most of the cases will support an API or dedicated SDK to communicate.
The following Javascript code exemplifies how to suscribe to a player event and print out the data:

const player = new bitmovin.player.Player(htmlElement, conf);
player.load(source).then(function(value) {
    // Success
}).catch(function(reason) {
    // Error!
});
player.on(bitmovin.player.PlayerEvent. VideoPlaybackQualityChanged, function(eventData) {
    console.log("- VideoPlaybackQualityChanged: " + JSON.stringify(eventData));
});

The eventData object from the event handler , will contain specific information from the Event that can be accessed and passed to the Analytics System.

Steps to define a custom Analytics Collector
The following steps summarise the basic components of an analytics collector. Bitmovin offers open source access to custom collectors created for specific Analytics Systems on the market, we recommend to take a look at the Github Repository for further details of the implementation.

  1. Define your communication model with your Analytics System: The Metrics and Analytics systems generally have a communication model, that requires also authentication and the creation of a playback session. Once this model is clear, it can be implemented into the application that handles the Bitmovin Player.
    The following code exemplifies a custom collector definition:
//my custom analytics object, the definition must be provided by the Metrics System vendor/owner
 var myMetricsSystem= new CustomMetricSystem( {
          credentials: MyCredentials
          apiURL: 'https://myapi-endpoint.com'
        });
      }

//initialise player
 player = new bitmovin.player.Player(document.getElementById('player'), getPlayerConfig());
 myMetricsSystem.initializeSession();
  1. Define the required Events, and provide the specific data: every metric system would require specific data from the playback or the content in general, please be sure to identify the proper events needed from Bitmovin’s documentation.
 player.load(getPlayerSource()).then(
         //load initial session values:
myMetricsSystem.updateContentMetadata({
          applicationName: 'My Custom metrics and analytics session with Bitmovin Player',
          viewerId: 'uniqueViewerId',
          framework: 'Bitmovin Player',
          frameworkVersion: player.version,
          custom: {
            appVersion: '1.0',
            contentId: 'someContentId',
            playerVendor: 'bitmovin',
            playerVersion: player.version,
          },
        );
      }
player.on(bitmovin.player.PlayerEvent. VideoPlaybackQualityChanged, function(eventData) {
      // We calculate the bitrate with a divisor of 1000 so the values look nicer
      // Example: 250000 / 1000 => 250 kbps (250000 / 1024 => 244kbps)
      const bitrateKbps = Math.round(eventData.targetQuality.bitrate / 1000);
      if(myMetricsSystem.isSessionActive)
      {
      myMetricsSystem.ReportPlaybackMetadata(
      {"bitrate":bitrateKbps}
      );
      }
});

player.on(bitmovin.player.PlayerEvent.PlaybackFinished, function(eventData) {
    //Close the analytics session
    myMetricsSystem.closeSession()
});

Conclusion
Implementing a custom collector for your Metrics and Analytics System, should be fairly simple with the EventsApi from Bitmovin Player SDKs.
It is important to understand the communication model between client/server of your Metrics Analytics System, so the authentication and data reporting is handled properly inside the event handlers.
The even handlers provide all the data needed from the event, by accessing the event object

2

this post is also available in : Using Bitmovin Player events for custom metrics reporting