In this guide we will learn how to customise how your Video and Audio media content is tracked (for example how to customise the video titles and video URLs), and how to specify which videos and audios should be tracked or ignored.
When analyzing your media reports in Matomo (formerly Piwik), media titles are often more useful than the Media HTTP URLs (which may contain only random numbers and letters). The YouTube and Vimeo player let us retrieve the video title automatically, so your video reports directly show the original video titles. If you use HTML5 videos or audios, or if you wish to customise the video titles in your analytics reports, read on. Media Analytics will detect the media title by searching for the following pieces of information:
data-matomo-title HTML attribute.data-piwik-title HTML attribute.title HTML attribute.alt HTML attribute.Titles are detected in this priority, meaning that you can set a data-matomo-title (recommended) or a data-piwik-title attribute to overwrite
the YouTube or Vimeo video title. A data-matomo-title always has the highest priority and overwrites any title
received from a media player.
<video data-matomo-title="My custom Video title" title="A different title"></video>
In the above example your video analytics reports in Matomo will show "My custom Video title" as the media title. If the video title cannot be detected (depending on your media player) and there is none of these HTML attributes set, then the title will be shown as "Unknown".
If you want to track a custom title that is different to your video title, you can provide a custom title that will be only used for tracking purposes by specifying a playlist item in the setup method like this:
playerInstance.setup({
playlist: [{
file: "https://example.org/actualUrl.mp4",
title: "My Video",
matomoTitle: "My custom Video title"
}
});
Instead of the matomoTitle property (recommended) you can also use piwikTitle.
You can provide a custom title when you use flowplayer for tracking purposes by specifying a matomoTitle or piwikTitle property:
flowplayer("#player", {
clip: {
sources: [
{type: "application/x-mpegurl", src: "https://example.org/actualUrl.m3u8"},
{type: "video/mp4", src: "https://example.org/actualUrl.mp4" }
],
title: "Javascript setup",
matomoTitle: "My custom Video title"
}
});
If you embed flowplayer using the video element, you can set the data-matomo-title attribute on the video element
directly as described above.
By default, the HTTP URL of a media is fetched from the player API or read in the DOM. There can be use cases
where you might want to track a custom resource URL instead of the actual resource. For example when your media
URLs contain unique ids and you prefer to have more readable URLs when analyzing your Matomo reports.
To do this you can define a custom resource via the data-matomo-resource (recommended) or the data-piwik-resource HTML attribute. For example:
<video src="https://example.org/actualUrl.mp4"
data-matomo-resource="https://example.org/trackedUrl.mp4"></video>
If your resource URL is for example user dependent, and you always want to track the same resource, you can provide a custom resource by specifying a playlist item in the setup method like this:
playerInstance.setup({
playlist: [{
file: "https://example.org/actualUrl.mp4",
title: "My Video",
matomoResource: "https://example.org/trackedUrl.mp4"
}
});
Instead of the matomoResource property (recommended) you can also use piwikResource.
You can provide a custom resource URL when you use flowplayer by specifying a matomoResource or a piwikResource property:
flowplayer("#player", {
clip: {
sources: [
{type: "application/x-mpegurl", src: "https://example.org/actualUrl.m3u8"},
{type: "video/mp4", src: "https://example.org/actualUrl.mp4" }
],
title: "Javascript setup",
matomoResource: "https://example.org/trackedUrl"
}
});
If you embed flowplayer using the video element, you can set the data-matomo-resource (recommended) or the data-piwik-resource attribute on the video element
directly as described above.
By default, all detected videos and audio will be tracked. To prevent the tracking of a specific media while still tracking
other media you can set a data-matomo-ignore (recommended) or a data-piwik-ignore attribute on a <video> or <audio> element to ignore it. For example:
<video data-matomo-ignore>...</video>
<audio data-matomo-ignore>...</audio>
<iframe data-matomo-ignore src="..."></iframe>
To avoid tracking any media from a particular media player,
you can disable analytics for one or more players calling the removePlayer method:
_paq.push(['MediaAnalytics::removePlayer', 'playerName']);
playerName should be one of html5, vimeo or youtube.
For example if you don't want to track any Vimeo videos, you can remove that player as follows:
_paq.push(['MediaAnalytics::removePlayer', 'vimeo']);
Make sure to call this method as early as possible, for example just after _paq.push(['setSiteId', 'X']);
If you want to disable any HTML5 based media player like JW Player or VideoJS, use html5 to ignore such media.
The tracking of any media can be disabled at any time by calling the following method in your website:
_paq.push(['MediaAnalytics::disableMediaAnalytics']);
This can be useful when you track several websites in one Matomo installation and you want to track the media usage
only for some of your websites. For the websites you want to disable the media tracking simply call the above shown
method. If you do not use the _paq variable, you can disable the media tracker as follows:
window.matomoMediaAnalyticsAsyncInit = function () {
Matomo.MediaAnalytics.disableMediaAnalytics();
};
Calling this method will stop tracking any media data. No media event such as "play", "pause" or "resume", nor other media data like how often or for how long a media was played, will be tracked. If you use multiple Matomo JavaScript trackers, calling this method will disable the tracking for all of them.
It is recommended to call this method as early as possible, for example just after _paq.push(['setSiteId', 'X']); unless
you want to disable the tracking only after a certain amount of time.
To enable the tracking again at a later point, call the method enableMediaAnalytics followed by a scanForMedia:
_paq.push(['MediaAnalytics::enableMediaAnalytics']);
_paq.push(['MediaAnalytics::scanForMedia']);
If you are on Matomo Cloud since January 2022 or after, then the tracking of media events will be disabled by default as it count towards your hit's quota. You can enable the tracking of events by calling _paq.push(['MediaAnalytics::enableMediaAnalytics']);.
In all other cases, the tracking of media events is enabled by default and the events can be disabled by default or for specific sites.
Learn more about this in our media events FAQ.
Yes, the tracking of media events can be disabled by calling the following method:
_paq.push(['MediaAnalytics.disableTrackEvents']);
This will stop the tracking of any action events, while still tracking the usage of the videos and audio itself. This means you will still get all media reports that are listed under the menu category "Media" but won't get to see any media events in the Visits Log or in the "Action => Events" report.
It is recommended to call this method as early as possible, for example just after _paq.push(['setSiteId', 'X']);
Yes, the tracking of media can be disabled by calling the following method:
_paq.push(['MediaAnalytics.disableTrackProgress']);
This will stop tracking any media progress. Under the menu category "Media", most reports will not show any data. The Visits Log and the "Actions => Events" report will still show data unless you disable the tracking of events as well (see above).
It is recommended to call this method as early as possible, for example just after _paq.push(['setSiteId', 'X']);
If you use a player other than YouTube / Vimeo / HTML5 / JwPlayer / Flowplayer / Video.js, learn about tracking your Custom Video Players. Or you may want to learn more about the Media Analytics JavaScript API, read the Media Analytics User Guide, the Media Analytics User FAQs or the Developer FAQs.