Track Files

Are you interested in tracking files like PDFs? Unlike most website pages, you will be unable to install our tracking code on those files? In such cases, we will need a different approach.

Your Options

There are multiple ways to track files with Parse.ly. Each approach has merits.

Count each download as a conversion

This could potentially be the simplest solution. If your team purchased conversions, and you’re interested in tracking a particular file extension (like *.pdf), then Parse.ly Support could have you set up within minutes. You would just need to tell us the file extensions you’re interested in tracking and we’ll take care of the rest. Anytime a visitor clicks to download your file, you can take advantage of each of our attribution models to see what motivated your reader to download.

Sometimes, it isn’t so simple. Suppose you have 4 pages that contain 25 PDFs each. When your visitor downloads one of these PDFs, we’re only going to be able to tell you which of the 4 pages they downloaded from. You won’t know which of the 25 PDFs they downloaded.

However, if you have a developer on your team, then they could self-manage your conversions. This would give them more control over how to handle each PDF download. They could dynamically set the conversion label to accept the file name as a variable. In this way, you would know exactly which PDF your readers downloaded. The catch with this method is that you’re typically going to be limited to 20 conversion labels per your contract.

There is an alternative.

Count each download as a “page view”

This method will also require time from your developers, but you will be able to track all of your file downloads. You won’t receive the conversion attribution models, but you will still have access to referrer information.

This method will require your developers to use dynamic tracking so that we can count the number of times your visitors download each file. This could be all that you need.

The only thing lacking with this method is that your files won’t have any of the metadata that powers all of the filters of Parse.ly. To supply that metadata, you will need to purchase API access. From there, you could have complete information.

Next Steps

I want Parse.ly Support to track files as conversions

1. Confirm that you have conversions in your contract. If you’re not sure, contact your Relationship Manager.
2. Email support@parsely.com and let us know the file extension(s) that you want to track. For example: “Anytime my readers download a PDF, I want to count this as a conversion.”

We can self-manage our conversions

1. Confirm that you have conversions in your contract. If you’re not sure, contact your Relationship Manager.
2. Add conversions via Google Tag Manager or the methods described here.

I want to track file downloads as pageviews

Step 0: Prerequisites for tracking files as pageviews

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.
   • 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: