Player Events & Analytics

Tracking player events advanced.

The Videojs Events plugin was designed specifically to work with Video.js and Nuevo plugin. The plugin fires 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 simple way, if only Analytics or Matomo codes snippet is applied on your website. It is essential to include video title and video ID through Nuevo plugin options. This allows to identify 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>

var player = videojs("myPlayer");
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 friednly. Events collected for mentined platforms are: firstStart, progress (10%, 25%, 50%, 75%, 90%), sompleted, fullscreen aand watchedTime. For each event sent Analytics and Matomo allows to include category and label values. The category is assigned automatically and it can be "video", "live video" or "audio". Label is video title if defined by the user.

Plugin by Nuevodevel.com suports 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 website. The downside of such method is that you can't log total watched time value when the user leave 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 apropriate for specific event can be passed as well.
To catch 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 javascript switch startement.
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 3 popular IP Geolocation services: Abstract, ipdata.co or ipapi.co.
All 3 services have limits. Abstract service has only paid plans (starting from $9.00), ipadata service offers 1500 free requests daily (on-commercial use) or paid plans (starting from $10.00), ipapi service offers up to 1000 requests daily free or paid plans (from $12.00).The first two services require to provide API key, that you may pass as plugin's option. If you do not provide apiKey, the plugin attempts to fetch ipapi.co service. In order to be compliant with GDPR for users located in the EEA you can anonymize 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 to fetch 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;
}
});

Public function getSummary allows to extract summary data in javascript at any time position, not only when video 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

Events plugin allows to define custom tracking Url.

Code snippet

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

Player events will be sent to custom Url on server using 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 server. Example array for firstPlay event is like:

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

Set of events sent to custom URL doesn't differ much from the one 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 event user containing an array of user details, usually fired shortly after firstPlay event.

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

Code snippet

$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

$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 database, build your own analytics application, present data in any way.