How do I track PDF downloads?
Important limitation: you can’t tag “PDF views”
Piano Analytics cannot track the display of a PDF document itself once it is opened (for example, in a browser PDF viewer or after it is downloaded and opened locally). This is because PDF files do not provide a reliable JavaScript execution environment for Piano Analytics tags.
In practice, PDF “downloads” are measured by tracking the click on the link or button that points to the PDF.
Recommended approach for PDF downloads
For PDF download measurement, it is generally recommended to implement a click.download hit on the element that initiates the download (link, button, etc.). This keeps download behavior separate from normal navigation in reporting and makes the data easier to interpret.
If needed, you can also pass a parameter/value that identifies the resource (for example, the PDF URL or filename) so you can distinguish downloads in reporting.
For implementation details, refer to the Piano Analytics Developers documentation on click tagging.
Validate your implementation (Tag Inspector)
Please note that once the tag has been implemented, you can use the Piano Analytics Tag Inspector plugin for Chrome. You will thus be able to directly review your tagging (this goes for tagging in general, not just clicks).
When testing a PDF link: - Click the PDF link/button - Confirm a hit is sent and that the click is categorized as click.download - Note the click name/label and any useful properties (such as the destination URL), which you can later use for filtering and analysis
If no hit is sent when you click a PDF link, the download is not tagged (or the click tagging is not implemented on that element).
Analyze PDF downloads in Piano Analytics
Once your PDF links are tagged, you can analyze downloads in Explorer under the Clicks/Content click analyses by: - Filtering on the click type click.download - Filtering or breaking down by the Click property (the click name/label)
Common ways to report on downloads include: - Using the Download Clicks metric to count download interactions - Adding the Page property to identify which page the download was initiated from (useful to understand the source context) - Using the event URL (often exposed as event_url) when you need the full destination URL of the PDF, depending on your tagging setup
Troubleshooting
Not all PDF links are tagged: Only clicks with a configured click marker are tracked.
No hit is sent on click: Verify using Tag Inspector. You can also use your browser developer tools (F12) to check that a tracking request is triggered when clicking the PDF link.
URL data looks incomplete: In some cases, the captured URL/referrer information may be impacted by browser or site policies (for example, restrictive referrer policies). If you need a reliable identifier for each PDF, consider explicitly sending the PDF URL/filename as part of the click data.
Choose the click type intentionally: It is up to you to decide on the click type you wish to push based on existing tags and the way you want your data to be displayed in the interface. For downloads,
click.downloadis typically the clearest choice.