Track file downloads

Track when users download files like PDFs, ZIPs, images, or other assets from your website using Umami custom events.

This page covers the Umami implementation. For measurement strategy — which metrics to collect, event design, and how to interpret download data — see the file download tracking guide on the main site.

Using data attributes#

Add data-umami-event attributes to your download links:

<a
  href="/files/report.pdf"
  data-umami-event="file-download"
  data-umami-event-file="report.pdf"
>
  Download Report (PDF)
</a>

Each click will record an event named file-download with a file property containing the filename.

Tracking all downloads automatically#

Use this script to automatically track clicks on any link pointing to common file types:

<script>
  document.addEventListener('DOMContentLoaded', function () {
    const fileExtensions = /\.(pdf|zip|tar|gz|rar|doc|docx|xls|xlsx|ppt|pptx|csv|mp3|mp4|dmg|exe|iso)$/i;

    document.querySelectorAll('a[href]').forEach(function (a) {
      if (fileExtensions.test(a.href) && !a.getAttribute('data-umami-event')) {
        var filename = a.href.split('/').pop().split('?')[0];
        a.setAttribute('data-umami-event', 'file-download');
        a.setAttribute('data-umami-event-file', filename);
      }
    });
  });
</script>

This finds all links to downloadable files and adds tracking attributes automatically, without modifying each link by hand.

Viewing download data#

1. Navigate to your website in Umami.
2. Click on Events to see the file-download event and its counts.
3. Click on Event data to view a breakdown by the file property, showing which files are downloaded most.