This guide is the JavaScript Tracker API Reference for Media Analytics.
You may also be interested in the Media Analytics Reporting HTTP API Reference.
In the matomo.js tracker we differentiate between two kind of methods:
.), for example
MediaAnalytics.disableTrackEvents.::, for example MediaAnalytics::removePlayer.In most cases only one Matomo tracker will be used so the only difference is how you call that method:
Tracker methods are called via _paq.push(['MediaAnalytics.$methodName']); or on a tracker instance directly eg.
Matomo.getAsyncTracker().MediaAnalytics.$methodName();
Static methods are called via _paq.push(['MediaAnalytics::$methodName']); or directly on the Matomo.MediaAnalytics object,
eg. Matomo.MediaAnalytics.$methodName().
If you do not want to use the _paq.push methods, you need to define a window.matomoMediaAnalyticsAsyncInit method
that is called as soon as the media tracker has been initialized:
window.matomoMediaAnalyticsAsyncInit = function () {
Matomo.MediaAnalytics.removePlayer('youtube');
};
scanForMedia(documentOrHTMLElementToScanForMedia).When this method is called, the MediaAnalytics tracker will search the DOM for new videos and audio and start tracking
that media. As a parameter you can optionally pass an HTMLElement if only a part of the DOM should be searched for
new media. This is especially useful for one page web applications. If no such parameter is given, the entire DOM will
be search for new media elements.
Example:
_paq.push(['MediaAnalytics::scanForMedia']);
_paq.push(['MediaAnalytics::scanForMedia', document.getElementById('test')]);
// or
Matomo.MediaAnalytics.scanForMedia();
Matomo.MediaAnalytics.scanForMedia(document.getElementById('test'));
setPingInterval(pingIntervalInSeconds)By default, the tracker sends a tracking request to your Matomo every 5 seconds while a media is currently playing. This is needed to track the current position within the video and to update for how long the media has been played. If you want to send this update more or less frequently, you can set a different ping interval using this method.
removePlayer(playerName)If you do not want to track any media of a certain player, you can disable that player by calling this method.
playerName should be either 'html5', 'vimeo', 'youtube', 'soundcloud' or 'jwplayer'.
addPlayer(playerName, player)Allows you to track a custom media player. This is useful if you are using a media player that is not yet supported by the MediaAnalytics plugin. We might also be able to support new players within this plugin, let us know which media player you use.
disableMediaAnalytics()Allows you to completely disable the tracking of any media. This is useful if you for example manage multiple websites
in your Matomo and there are some sites where you do not want to track any media. If called early in your tracking code
or via the matomoMediaAnalyticsAsyncInit method, it will not even search for media on your web page.
enableMediaAnalytics()If you have disabled the tracking of media via disableMediaAnalytics() you can enable it at a later point via this method.
It is recommended to call scanForMedia() just after enabling the media tracking to make sure it detects all media on
your website or in your application.
isMediaAnalyticsEnabled()Allows you to detect whether the tracking of media is currently enabled. Returns a boolean true or false.
enableDebugMode()Enables the debug mode that logs debug information to the developer console of your browser. This should not be enabled in production.
setMatomoTrackers()Allows you to set the tracker instances the tracker should use when tracking the progress and events of Media. Can be either
a single tracker instance, or an array of Matomo tracker instances. This is useful when you are working with multiple Matomo
tracker instances using Matomo.getTracker instead of Piwik.addTracker.
getMatomoTrackers()Returns an array of Matomo tracker instances that are used by the Media Analytics plugin. By default, this will return the same
as Matomo.getAsyncTrackers() and will return all tracker instances that were created eg via Piwik.addTracker or
_paq.push(['addTracker']); unless custom Matomo tracker instances were set via setMatomoTrackers().
setMediaTitleFallback()Matomo will automatically detect the title of a video or audio in most cases. In case you are using an old version of a media player, or an exotic media player which does not allow us to detect the title automatically, you can define a callback method to detect the title of a video or audio manually based on your own custom logic. You can find an example in the FAQ.
setMaxTrackingTime(stopTrackingAfterXSeconds)By default, Matomo will stop tracking a particular video once it has been tracked for 3 hours since the first tracking request of the video or audio. To record media longer or than this or stop tracking earlier, call this method. Recording videos longer than 3 hours may be useful if your users actually are engaging with your media for that long. Setting a lower value may be useful if you are seeing many viewed media in the visits log for example if your media player is playing a playlist.
mediaTypeThe mediaType property defines constants that are useful when you track the usage of a custom media player
via the addPlayer() method.
mediaType.VIDEO - Defines the current media is a videomediaType.AUDIO - Defines the current media is an audioYou can access this property as follows: Matomo.MediaAnalytics.mediaType.VIDEO.
elementelement.getAttribute(htmlElement, attributeName) Lets you read the value of an HTML attribute. If the attribute is not set, it will return null.element.setAttribute(htmlElement, attributeName, attributeValue) Lets you set a value of an HTML attribute on an HTML element.element.isMediaIgnored(htmlElement) Detects whether the given element is supposed to be ignored when tracking media (has a data-matomo-ignore or a data-piwik-ignore attribute).element.getMediaTitle(htmlElement) Tries to detect a media title from one of the HTML attributes data-matomo-title, data-piwik-title, title or alt. Returns null if no title can be found.element.getMediaResource(htmlElement, actualResource) If the element has set a value for the data-matomo-resource or the data-piwik-resource attribute, it will return that value and actualResource otherwise.element.isFullscreeen(htmlElement) Detects whether the given element (video) is currently viewed in full screen.disableTrackEvents()Disables the tracking of events like play, pause or resume while still tracking the media usage. When calling
this method no events for your media will be shown in "Actions => Events" and neither in the Visits log.
Example:
// disables the tracking of events on all Matomo trackers
_paq.push(['MediaAnalytics.disableTrackEvents']);
// or if you are using multiple Matomo trackers and only want to disable it for a specific tracker:
var tracker = Matomo.getAsyncTracker(matomoUrl, matomoSiteId);
tracker.MediaAnalytics.disableTrackEvents();
enableTrackEvents()If the tracking of events was disabled via disableTrackEvents(), you can enable it again using this method.
isTrackEventsEnabled()Detects if the tracking of events is currently enabled or disabled. Returns a boolean true or false.
disableTrackProgress()Disables the tracking of media progress while still tracking events like play, pause or resume. Calling this
method means there will be no data available under the "Media" menu category (like how often or how long a
media was played).
enableTrackProgress()If the tracking of progress was disabled via disableTrackProgress(), you can enable it again using this method.
isTrackProgressEnabled()Detect if the tracking of progress is currently enabled or disabled. Returns a boolean true or false.
You may be interested in the Media Analytics HTTP Tracking API Reference, or the Reporting HTTP API Reference. If you use a player other than YouTube / Vimeo / HTML5 / JwPlayer / Flowplayer / Video.js, learn about implementing analytics for your Custom Video Player.