Matomo (Piwik) should automatically track clicks on Download files (with a known extension, eg. jpg, png, exe, zip, etc.) and clicks on Outlinks (links to other websites) using Javascript click handlers. There are a few reasons why this could fail:

  • Conflicting Javascript code
    In some rare cases, Download and Outlink tracking doesn’t work in Matomo is because your page is using another Javascript script or library which sets click handlers as well. If a third-party click handler returns a value, it is causing the browser to cancel other registered click handlers. Instead they should return false. Most scripts and libraries are doing it correctly, but you might have to manually edit your Javascript code to return false in onclick events.
  • Matomo doesn’t respond fast enough and user is redirected to the click target
    Matomo click handler works by adding a small delay during which the request is sent to the Matomo server. If somehow the request doesn’t reach the server within this delay, the request will be not be tracked and the user will be redirected to the clicked download file or to the external website. You can increase this delay, from the default of 500ms (0.5 second), by adding the following in the Javascript code, after the piwik.getTracker(..) line:

    _paq.push([‘setLinkTrackingTimer’, 750]); // increase to 750 milliseconds

  • You’re using an old browser version
    For example there were known WebKit bug where the tracking request was interrupted. One workaround is to add the target=”_blank” attribute to anchor elements.

  • Track a file extension not known to Matomo yet, see the developer guide Customise the type of files tracked as downloaded.

  • Manually track a click as a download, when automatic download tracking does not work for some reason, you can Manually record a click as a download.

  • Enable Send Beacon in the Matomo JavaScript tracker The Send Beacon is enabled by default in Matomo 4, but can be enabled manually if necessary.

If this doesn’t help solve the issue, you can find additional relevant information in this FAQ: Matomo is not tracking outlinks clicks to my own websites

Previous FAQ: When the Matomo server is unavailable (down) how does this affect my websites loading speed and tracking data collection?