Common reasons file-download tracking doesn’t fire
- GTM container not published - You imported the container but didn’t click Submit → Publish.
- GTM snippet not installed on your site - The GTM code needs to be in your site’s <head> and <body>.
- Extension regex doesn’t match the URL - Trackers usually look for
.pdf,.zip,.docxat the end of the URL. URLs with query strings (file.pdf?v=2) or fragments (file.pdf#page=3) trip strict$-anchored regexes. The TrackingCoder snippet handles both, but custom GTM triggers often don’t. - Link has
target="_blank"- Opening in a new tab is fine and even helps deliverability. Opening in the SAME tab is the dangerous case: the page unloads before the GTM tag finishes firing, and you lose the event. Either addtarget="_blank"or enable “Wait for Tags” on the trigger (max ~2000ms). - Cloud storage links don’t have file extensions - Dropbox (
?dl=0), Google Drive (/file/d/abc123/view), and Box (/s/abc123) shareable URLs don’t include the file extension in the URL. A regex-only trigger won’t match them. You either need a domain-based trigger (Click URL containsdrive.google.com) or to mark these links with adata-tc-downloadattribute and target that. - JavaScript-driven downloads - Some sites build the file at click time (creating a Blob, calling
URL.createObjectURL()) instead of using a normal<a href>. The href is empty orjavascript:void(0)when GTM evaluates it. You need a click trigger filtered by element class or text instead. - Inline PDF preview, not a download - On many browsers PDFs open in-tab via PDF.js. The user perceives that as “opening” the file, not downloading it - but no
downloadevent fires. Decide whether to count previews as downloads in your analytics, then trigger accordingly.
Step-by-step debugging checklist
- Verify GTM is installed - Visit your site, right-click → View Page Source, search for “GTM-”. If you don’t see it, GTM isn’t installed.
- Check GTM Preview mode - In GTM, click Preview. Navigate your site and trigger the event. Look for your tag in the Tags Fired section.
- Check the trigger - If the tag shows as “Not Fired”, click on it to see which trigger conditions aren’t met.
- Inspect the link element - Right-click → Inspect. Confirm it’s
<a href="...somefile.pdf">. Note anytarget,download, oronclickattributes. - In GTM Preview, click the link - A Click event should fire and the Click URL variable should contain the file URL. If Click URL is empty or doesn’t contain the file, the link is JS-driven and a regex trigger won’t work.
- If links are same-tab: enable Wait for Tags - On your Click trigger, set Wait for Tags = 2000ms and Check Validation. This delays the navigation just long enough for the GA4 tag to send.
How to verify it’s working
- Open GTM Preview/Debug mode
- Navigate to your site
- Trigger the event (click a download link)
- Check the GTM debug panel - your tag should appear under “Tags Fired”
- Check GA4 DebugView (GA4 → Admin → DebugView) to confirm the event arrived
Still didn’t work?
Our team can help. Describe what’s happening and we’ll get back to you within 24 hours.