Track Files

For a standard Parse.ly integration, we ask you to install tracking code on your site and then we crawl your site to extract metadata, but what if you want to track downloadable files? Then this is the guide for you!

Before proceeding, consider whether you want this file download to be like any other pageview or if you want attribution information, i.e., discovery of what led to the download. If you want attribution, consider Conversions tracking (sold separately).

Why track files?

Parse.ly can provide insights across the entirety of your site wherever you’ve installed our tracking code. But in some cases, you may have a significant amount of content stowed away in PDFs (where our tracking code cannot be placed).

With a script, you may send us pageviews whenever your readers download your material. And with access to our /metadata endpoint, you can assign metadata to that PDF like you would for post pages.

Step 0: Prerequisites for tracking files

This guide is for you if you::

1. Desire to trigger pageviews for your files and…
   • Have a file that you’ve linked from a page that has Parse.ly tracking. A quick way to verify the presence of our tracking code on a given page is to navigate to the page of interest and use the “Open in Parse.ly” Bookmarklet.
   • Have familiarity with adding event listeners, using browser developer tools, and can apply these methods in your CMS.
2. (Optionally) want to associate metadata with those pageviews and…
   • Purchased access to the Parse.ly API. If you haven’t, please contact your Relationship Manager or value@parsely.com.
   • Can navigate here to see the field API Secret. If you purchased API access and do not see this field, please contact Support@parsely.com.

Step 1: Trigger pageviews for your files

To trigger pageviews when your reader clicks on a download link, you can implement dynamic tracking.

The following script is an example that will generate pageviews on hyperlinks for PDFs:

<script>
  (function() {
    function downloadListener(event) {
      var fileName = this.getAttribute('href').substring(this.getAttribute('href').lastIndexOf('/') + 1);
      var downloadURL = new URL(this.href, window.location.href);
      downloadURL.searchParams.set('name', fileName);
      window.PARSELY.beacon.trackPageView({
        url: downloadURL.href
      });
    }

    function listenForDownloads() {
      var downloadBtns = document.querySelectorAll("a[href$='.pdf']");
      downloadBtns.forEach(function(downloadBtn) {
        if (!downloadBtn.getAttribute('data-track-download')) {
          downloadBtn.setAttribute('data-track-download', '');
          downloadBtn.addEventListener('click', downloadListener);
        }
      });
    }

    if (window.PARSELY) {
      listenForDownloads();
    } else {
      var oldOnload = window.onload;
      window.onload = function() {
        if (oldOnload) {
          oldOnload();
        }
        listenForDownloads();
      };
    }
  }());
</script>

After implementing something like this, follow our instructions to ensure that you’re sending pageviews.

Step 2: Sending metadata (optional)

Following the instructions found in our API Documentation, you could send a request like this one:

curl -H "Content-Type: application/json" -X POST https://api.parsely.com/v2/metadata/posts -d '{"apikey": "docs.parse.ly", "secret": "REDACTED", "metadata":{"pub_date_tmsp": "2023-12-05","title": "Getting Started with Parse.ly","tags": ["pdf"],"authors": ["lindsey"],"canonical_url": "https://docs.parse.ly/wp-content/uploads/sites/5/2022/12/Getting-Started-with-Parse.ly_v3Q422.pdf","page_type": "post","section": "User Guide","full_content": "Getting started with Parse.ly","language": "en"}}'

That command line example is for illustrative purposes only. If your CMS supports webhooks, you would likely use a webhook instead.

Step 3: Validating results

Let’s check out an example. WPVIP hosts this site and we’re using the Block Editor, so we’ll add a (hidden) Custom HTML block. This block has a copy of the script noted in Step 1 of this guide. This solution works for a single page but you could try similar at the theme level to address all pages that contain files.

Now that we’ve added the script, we’ll send the metadata via the Terminal as described in Step 2, above. Note that we need to replace REDACTED with our metadata-write secret.

If you’re following along, now is a good time to open your developer tools (F12) > Network > Filter for “action=pageview”.

Here is an example file for you to enjoy: the Parse.ly Getting Started Guide. Clicking that link will send a pageview. You should then receive a response like this: