Guides

Playing Video Analytics

Integrating the analytics module in to the Banner app

Suggest Edits

Let's see how the analytics module can be integrated into the Banner app from the Playing Video tutorial.

Clone the repo and switch to the analytics branch to follow along. The pull request shows the code that has changed when integrating the analytics module.

Setup

We import the analytics module like this:

import analytics from './analytics.js';

The app expects a file called config.json with the following properties:

  • googleAnalyticsId: the Google Analytics ID (gtag)
  • ipDataAPIKey: the ipdata.co API key for geolocation

We'll load the config file like this:

let config = {};
try {
  const module = await import("./config.json", {assert: {type: "json"}});
  config = module.default;
} catch (error) {
  console.warn("config.json not found");
}

Next we'll call the analytics module's init function, passing the app name and a config object:

await analytics.init("Banner Pro", {
  google: {gtag: config.googleAnalyticsId, debug: true},
  ipdata: {apikey: config.ipDataAPIKey},
  userInfo: {username: "andrewzc"},
  lifecycle: {raw: false, summary: true},
  player: {raw: false, summary: true}
});

We'll use the API keys from the config file, and turn debug mode on so we can see live events in the GA4 debug screen. The userInfo object can be any arbitrary key/value data. For lifecycle and player tracking, we'll tun off raw events and turn on summaries for now, but we can experiment with these to see what they do.

Tracking player events

Finally, we'll call the trackPlayerEvents() function, passing the player and the video. This app just plays a single video, so we'll pass a simple object with some content metadata. 

analytics.trackPlayerEvents(player, video, {
  contentId: "bbb_30fps",
  title: "Big Buck Bunny",
  description: "Big Buck Bunny tells the story of a giant rabbit with a heart bigger than himself."
});

Believe it or not, that's all you need to do to track the player and lifecycle analytics—the rest is automatic!

Summary events

Let's give it a try and see what events the app sends! By default, it only sends a player summary and a lifecycle summary when the app disconnects. If you set the disconnect.delay to 10 seconds, you'll be able to see the events that are sent at the end of the session before the debugger hangs up.

  • The player_session_end event shows that I watched Big Buck Bunny for 64 seconds.
  • The lifecycle_session_end event shows that I spent 26 seconds in foreground, 38 seconds in background, with a foreground ratio of 40%.

With google.debug enabled, we can see the same events come through live in the Google Analytics debug view:

Raw events

If you set player.raw to true, you'll see every player event like play, pause, and skip come through. This could be useful during development, or if you want to process raw player data in your analytics backend. Note that to avoid sending the same data over and over, the content metadata is not included with raw events, only the source URL is.

You can confirm that you see the same events in the GA4 debug view:

Similarly, if we turn on lifecycle.raw, we'll see events for every lifecycle state transition:

And the same in the debug view:

Updated 3 days ago