In this guide we will learn how you can implement Media Analytics for your custom video players or audio players.
The Media Analytics plugin currently supports out of the box the HTML5, Vimeo and YouTube media players (more details: list of all supported media players). If you are using a different media player for your videos and audio, you can measure them by registering your own player.
If you need help implementing Media Analytics for your media player or if you wish to share your implementation with us, please contact us. If you work with us. we will be able to maintain it and ensure it always works in the future.
Let's start by adding the raw skeleton for a media player to your website tracking code. A media player tracker basically consists of two parts:
window.matomoMediaAnalyticsAsyncInit = function () {
var MA = Matomo.MediaAnalytics;
function MyPlayer(node, mediaType) {
// in this class we track interactions with the player
// instance is created whenever a media for this player was found
}
MyPlayer.scanForMedia = function(documentOrElement) {
// called whenever it is needed to scan the entire document
// or when a certain element area is scanned for new videos or audio
};
// adding the newly created player to the Media Analytics tracker
MA.addPlayer('myPlayerName', MyPlayer);
};
It is recommended to define this method before the Matomo (formerly Piwik) JavaScript Tracking Code.
The method scanForMedia is called whenever your player is supposed to search for new media. As an argument it receives
either the JavaScript variable document, or an instance of an HTMLElement when only a certain part of the DOM is
supposed to be searched for new media.
In the following example the player searches for video elements. Your own player would maybe search for iframe elements or for a certain class to identify a media player within a web page.
MyPlayer.scanForMedia = function (documentOrHTMLElement) {
// find all medias for your player
var html5Videos = documentOrHTMLElement.getElementsByTagName('video');
for (var i = 0; i < html5Videos.length; i++) {
// for each of the medias found, create an instance of your player as long as the media is
// not supposed to be ignored via a "data-matomo-ignore" attribute
if (!MA.element.isMediaIgnored(html5Videos[i])) {
new MyPlayer(html5Videos[i], MA.mediaType.VIDEO);
// there is also a MA.mediaType.AUDIO constant if you want to track audio
}
}
};
Now that we detect media within a web page we need to implement the actual tracking. The basic concept behind this is
to create a Matomo.MediaAnalytics.MediaTracker instance that lets you call methods like play, pause or seek which
reflect what is currently happening in the player.
function MyPlayer (node, mediaType) {
if (node.hasPlayerInstance) {
// prevent creating multiple trackers for the same media
// when scanning for media multiple times
return;
}
node.hasPlayerInstance = true;
// find the actual resource / URL of the video
var actualResource = MA.element.getAttribute(node, 'src');
// a user can overwrite the actual resource by defining a "data-matomo-resource" attribute.
// the method `getMediaResource` will detect whether such an attribute was set
var resource = MA.element.getMediaResource(node, actualResource);
// create an instance of the media tracker.
// Make sure to replace myPlayerName with your player name.
var tracker = new MA.MediaTracker('myPlayerName', mediaType, resource);
// for video you should detect the width, height, and fullscreen usage, if possible
tracker.setWidth(node.clientWidth);
tracker.setHeight(node.clientHeight);
tracker.setFullscreen(MA.element.isFullscreen(node));
// the method `getMediaTitle` will try to get a media title from a
// "data-matomo-title", "title" or "alt" HTML attribute. Sometimes it might be possible
// to retrieve the media title directly from the video or audio player
var title = MA.element.getMediaTitle(node);
tracker.setMediaTitle(title);
// some media players let you already detect the total length of the video
tracker.setMediaTotalLengthInSeconds(node.duration);
var useCapture = true;
node.addEventListener('play', function() {
// if the player supports something like playlists you might want to check
// whether the source has changed and if so, call the following 3 methods:
// tracker.reset();
// tracker.setResource(newResource);
// tracker.setMediaTitle(newMediaTitleOrEmptyString);
// this allows you to automatically track a new media as soon
// as the currently played video or audio changes
// notify the tracker the media is now playing
tracker.play();
}, useCapture);
node.addEventListener('pause', function() {
// notify the tracker the media is now paused
tracker.pause();
}, useCapture);
node.addEventListener('ended', function() {
// notify the tracker the media is now finished
tracker.finish();
}, useCapture);
node.addEventListener('timeupdate', function() {
// notify the tracker the media is still playing
// we update the current made progress (time position) and duration of
// the media. Not all players might give you that information
tracker.setMediaProgressInSeconds(node.currentTime);
tracker.setMediaTotalLengthInSeconds(node.duration);
// it is important to call the tracker.update() method regularly while the
// media is playing. If this method is not called eg every X seconds no
// updated data will be tracked.
// The method itself will not actually send a tracking request whenever it
// is called. Instead it will make sure to respect the set ping interval and
// eg only send a tracking request every 5 seconds.
tracker.update();
}, useCapture);
node.addEventListener('seeking', function() {
// "seekStart" is needed when the player is seeking or buffering.
// It will stop the timer that tracks for how long the media has been played.
tracker.seekStart();
}, true);
node.addEventListener('seeked', function() {
// we update the current made progress (time position) and duration of
// the media. Not all players might give you that information
tracker.setMediaProgressInSeconds(node.currentTime);
tracker.setMediaTotalLengthInSeconds(node.duration);
// "seekFinish" is needed when the player has finished seeking or buffering.
// It will start the timer again that tracks for how long the media has been played.
tracker.seekFinish();
}, useCapture);
// for videos it might be useful to listen to the resize event to detect a
// changed video width or when the video has gone fullscreen
window.addEventListener('resize', function () {
tracker.setWidth(node.clientWidth);
tracker.setHeight(node.clientHeight);
tracker.setFullscreen(MA.element.isFullscreen(node));
}, useCapture);
// here we make sure to send an initial tracking request for this media.
// This basically tracks an impression for this media.
tracker.trackUpdate();
}
For more information about all the available methods have a look at the Media Analytics JavaScript Tracker API reference.
Once you have added support for your custom player analytics, please contact us, and we will try to help you maintain it in the future.
You can use the MediaAnalytics plugin to track the media consumption in mobile apps, desktop apps and games. For this to work you need to use the Matomo HTTP Tracking API or a Matomo Tracking SDK.
These HTTP Tracking API parameters can be used to track the usage of media:
ma_id - (required) A unique id that is always the same while playing a media. As soon as the played media changes (new video or audio started), this ID has to change.ma_re - (required) The URL of the media resource.ma_mt - (required) video or audio depending on the type of the media.ma_ti - The name / title of the media.ma_pn - The name of the media player, for example html5.ma_st - The time in seconds for how long a user has been playing this media. This number should typically increase when you send a media tracking request. It should be 0 if the media was only visible/impressed but not played. Do not increase this number when a media is paused.ma_le - The duration (the length) of the media in seconds. For example if a video is 90 seconds long, the value should be 90.ma_ps - The progress / current position within the media. Defines basically at which position within the total length the user is currently playing.ma_ttp - Defines after how many seconds the user has started playing this media. For example a user might have seen the poster of the video for 30 seconds before a user actually pressed the play button.ma_w - The resolution width of the media in pixels. Only recommended being set for videos.ma_h - The resolution height of the media in pixels. Only recommended being set for videos.ma_fs - Should be 0 or 1 and defines whether the media is currently viewed in full screen. Only recommended being set for videos.ma_se - An optional comma separated list of which positions within a media a user has played. For example if the user has viewed position 5s, 10s, 15s and 35s, then you would need to send 5,10,15,35. We recommend to round to the next 5 seconds and not send a value for each second. Internally, Matomo may round to the next 15 or 30 seconds. For performance optimisation we recommend not sending the same position twice. Meaning if you have sent ma_se=10 there is no need to send later ma_se=10,20 but instead only ma_se=20.When tracking a media impression it is important to set the parameter ma_st to 0:
https://yourpiwikdomain/matomo.php?ma_st=0ma_id=8C1gOQ9CPOiQfzft&ma_ti=MediaName&ma_pn=playerName&ma_mt=video&ma_re=https%3A%2F%2Fplayer.example.org%2Fvideo%2F1111111&idsite=1&rec=1&r=077275&h=15&m=33&s=48&url=http%3A%2F%2Fexample.piwik&...
When tracking a media progress it is important to send the same media unique id (ma_id) while the same media is playing.
As soon as a new video or audio is playing you need to reset all parameters and generate a new ma_id.
https://yourpiwikdomain/matomo.php?ma_st=5&ma_ttp=12&ma_fs=1&ma_w=500&ma_h=300&ma_ps=34&ma_le=100ma_id=8C1gOQ9CPOiQfzft&ma_ti=MediaName&ma_pn=playerName&ma_mt=video&ma_re=https%3A%2F%2Fplayer.example.org%2Fvideo%2F1111111&idsite=1&rec=1&r=077275&h=15&m=33&s=48&url=http%3A%2F%2Fexample.piwik&...
While a media is playing we recommend sending an update regularly, for example every 5 seconds. Most of the parameters
usually remain the same when sending updated media progress requests, but the current media position (ma_ps) and the played
media time (ma_st) should change with every request.
There are many Matomo Tracking SDKs available for Matomo so you do not have to send pure HTTP requests. There is for example a Matomo Tracking SDK for PHP, Android, iOS, C#, Java and more. They usually allow you to set custom tracking parameters like this:
$phpTracker->setCustomTrackingParameter('ma_st', 0);
$phpTracker->setCustomTrackingParameter('ma_re', 'https://example.org/media.mp4');
$phpTracker->setCustomTrackingParameter('ma_ti', 'Media title');
...
Now that you've learnt how to implement analytics tracking of your custom Media player, you may want to learn more about the Media Analytics JavaScript API, or read the Media Analytics User FAQs or the Developer FAQs.