Player Events & Analytics

Get Summary

Tracking player events

The Videojs Events plugin was designed to work with Video.js and the Nuevo plugin. The plugin fires the most important player events and counts some statistical data. The plugin includes the basic implementation for Google and Matomo (formerly Piwik) analytics platforms that you can enable in a simple way if only Analytics or Matomo code snippets are applied to your website. It is essential to include video title and video ID through Nuevo plugin options. This allows for the identification of video in statistics.

Code snippet

<script src="//www.domain.com/videojs/video.min.js"></script>
<script src="//www.domain.com/videojs/nuevo.min.js"></script>
<script src="//www.domain.com/videojs/plugins/videojs.events.js"></script>

const player = videojs("my_player", {license: "key" });
player.nuevo({title:"video title", video_id:"video id"});
player.events({analytics:true});

Analytics and Matomo are not typical video-analytics platforms. Collecting and presenting data is limited and not so user-friendly. Events collected for the mentioned platforms are: firstStart, progress (10%, 25%, 50%, 75%, 90%), completed, fullscreen, and watchedTime. For each event sent, Analytics and Matomo allow you to include category and label values. The category is assigned automatically, and it can be "video," "live video," or "audio." The "label" is the video title, if it is defined by the user.

Plugin by Nuevodevel.com supports much more events and details that you can log in different ways. The most simple way to track player events is through javascript functions on a website. The downside of such a method is that you can't log the total watched time value when the user leaves the website page with the player. Each event is accompanied by a group of static parameters, like SessionID (it's just a timestamp when video starts to play), videoID, videoTitle (both if assigned by the user), and category (Video, Live video or Audio). Other parameters with values appropriate for specific events can be passed as well.To catch a single event (e.g., ended event), javascript code looks like:

Code snippet

player.on('track', (e, data) => {
if (data.event === 'firstPlay') {
let session_id = data.sessionId;
let video_id = data.videoId;
let video_title = data.videoTitle;
let category = data.category;
let duration = data.duration;
let start_time = data.initialTime;
// do something with data...
}
});

To catch multiple events, you can use a javascript switch statement.
Available events that you can track through javascript are:

firstPlay (fired when video starts). Paramter initialTime points to video start time, as not necessary this must me 0 position.
10% (10% watch time progress).
25% (25% watch time progress).
50% (50% watch time progress).
75% (75% watch time progress).
90% (90% watch time progress).
ended (fired when media playback has been completed).
buffered (fired when buffering starts. Parameter bufferTime indicates the time when buffering ended).
pause (fired when media paused. Parameter pauseCount inidicates the number of the playback pause event).
resume (fired when media playback resumed. Parameter resumeCount inidicates the number of the playback resume event).
replay (fired ehen the user decided to replay media).
enterFullscreen (fired when the user goes fullscreen).
exitFullscreen (fired when the user goes back from fullscreen).
seek (fired when the user seek in media time. Parameter seekTo indicates the time position the user seek to).
mute (fired when media is muted).
unmute (fired when media is unmuted).
rateChange (fired when media playback rate has been changed. Parameter rate indicates new rate value).
resolutionChange (fired when video resolution has been changed. Parameter rate indicates new resolution, e.g. 1080p).
summary (fired only when media playback was ended. The most important available parameter is watchedTime with the value equal to real time that the user spent to watch video. Other parameters are totalDuration, pauseCount, bufferCount and seekCount).
user Provides details about the user like IP address, region, country, browser and device).

To obtain the user details, the plugin fetches one of three popular IP geolocation services: Abstrac, ipdata.co ipapi.co.
All three services have limits. Abstract service has only paid plans (starting at $9.00), ipadata service offers 1500 free requests daily (on-commercial use) or paid plans (starting at $10.00), and ipapi service offers up to 1000 requests daily free or paid plans (from $12.00). The first two services require you to provide an API key, which you may pass as a plugin's option. If you do not provide an apiKey, the plugin attempts to fetch the ipapi.co service. In order to be compliant with GDPR for users located in the EEA, you can anonymize the user's IP. IP anonymization sets the last digits of users' IP addresses to zeros, so the website visitor's IP address is made anonymous.

Code snippet

player.events({ abstractApiKey: "Your API Key" });
orplayer.events({ ipdataApiKey: "Your API Key" });

player.events({ anonymizeIP: true });

Catching user details through javascript requires fetching the user event's object.

Code snippet

player.on('track', (e, data) => {
if (data.event === 'user') {
let user_ip = data.userInfo.ip_address;
let city = data.userInfo.city;
let region = data.userInfo.region;
let country = data.userInfo.country;
let country_code = data.userInfo.country_code;
let country_code = data.userInfo.country_code;
let browser = data.userInfo.browser;
let device = data.userInfo.device;
}
});

If you do not need user details or prefer to avoid http request to fetch user details, you may disable userIP plugin's option.

Code snippet

player.events({ userIP: false });

The public function getSummary allows you to extract summary data in JavaScript at any time, not only when the video is ended. This may be useful for apps with dynamic routing to catch video summary data before dynamic navigation.

Code snippet

let summarydata = player.getSummary();

let session_id = summarydata.session_Id;
let video_id = summarydata.video_Id;
let video_title = summarydata.videoTitle;
let category = summarydata.category;
let watched_time = summarydata.watchedTime;
let pause_count = summarydata.pauseCount;
let resume_count = summarydata.resumeCount;
let seek_count = summarydata.seekCount;
let buffer_duration = summarydata.bufferDuration;

Tracking Url

The Events plugin allows you to define custom tracking Url.

Code snippet

player.events({ trackingUrl: "https://script_url" });

Player events will be sent to a custom URL on the server using the sendBeacon method. The navigator.sendBeacon() method asynchronously sends an HTTP POST request containing a small amount of data to a web server. For each event, an array of objects is sent to the server. An example array for the firstPlay event is like this:

Code snippet

{
event: "firstPlay",
value: 0,
sessionId: "unique timestamp",
category: "video",
videoId: "Id of the video",
videoTitle: "Titlte of the video"
}

Event name	Event value(sec)
firstPlay	start time (s)
progress	10%, 25%, 50%, 75% or 90%
replay	null
completed	video duration (sec)
fullscreen	1 or 0
watchedTime	time (sec)
user	ip_address, city, region, country, country_code, browser, device

The set of events sent to the custom URL doesn't differ much from the ones sent to Analytics or Matomo. However, there is one extra object sessionID, which allows to identify events for the same playback, and what is more important, there is an event user containing an array of user details, usually fired shortly after the firstPlay event.

Reading events posted to a URL depends on the web server configuration and the programming language used. The event's data is sent to the server as serialized JSON. In the most popular PHP language, to get single event data, you can find this code useful:

Code snippet

<?php
$data = file_get_contents("php://input");
$data = json_decode($data);

$event_name = $data->event;
$event_value = $data->value;
$session_id = $data->sessionId;
$category = $data->category;
$video_id = $data->videoId;
$video_title = $data->videoTitle;
?>

Since the value of the user event is not a single value but another array of objects, the PHP code can be like below:

Code snippet

<?php
$data = file_get_contents("php://input");
$data = json_decode($data);

$event_name = $data->event;
if($event_name=='user') {
$user = json_decode($data->value);
$ip = $user->ip_address;
$city = $user->city;
$region = $user->region;
$country = $user->country;
$country_ip = $user->country_ip;
$browser = $user->browser;
$device = $user->device;
}
?>

Once you have event data, you can save it in a database, build your own analytics application, present the data in your preferred way.