Using Bitmovin Player events for custom metrics reporting

Introduction

The Bitmovin Player SDKs offer a variety of playback events, generally triggered by user interactions like play/pause/seek, but also by playback-inherent changes like an ABR quality change, Timed metadata becoming available, etc.
Events are also triggered when something unexpected happens, like a network error or an incompatible codec.

A complete list of the available events can be found on each Player SDK:

Web SDK Events
iOS SDK Events
Android SDK Events
Roku SDK Events

Subscribing to Events

Most of the Analytics/Metrics Report Systems can leverage the event-based player to collect and capture playback-related data. To listen/subscribe to the events, an event handler is needed. The event handler will specify the logic required to connect to the Analytics/Metrics System, which in most of the cases will make use of an API or dedicated SDK to communicate.

The following Javascript example code shows how to subscribe 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 your 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 you take a look at the Github Repository for further details of the implementation.

• Define your communication model with your Analytics System: The Metrics and Analytics systems generally have a communication model, that also requires authentication and the creation of a playback session. Once this model is clear, it can be implemented in the application that handles the Bitmovin Player.
  The following code example shows 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();

• Define the required Events, and provide the specific data: every metrics system would require specific data about 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 Events API of the 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