Guide 184 · Conversions · GA4 + Tag Manager
Key event for file downloads in GA4: file_download, the file name, and the rate
Enhanced measurement sends file_download whenever a visitor clicks a link to a file, and the file_name parameter says which file. Marking file_download itself makes every download a key event, which is rarely what the business wants. This guide marks it for a site where the download is the product, checks the file name in DebugView, and works out the download rate for a week.
After the steps, the file_download key event appears under the Key events tab in Admin, and the standard reports show it within a day. The worked example below gives the count and the rate to expect.
Download the reference: the file_download key-event reference (JSON) (706 bytes, MD5 16e15f1f4c8fe3f0e5c352703d67c807). It holds the event name, the counting method, the worked-example figures recomputed for this guide, and the checkpoints that prove the key event is recording. The figures in the file are the same figures shown on this page.
What you need
- Editor access or above at property level in GA4. Marking an event as a key event is a property setting, and the star in the Events table does not appear for a Viewer.
- Enhanced measurement enabled in the web data stream, so file_download is collected. The event fires on links to files with matching extensions, such as pdf, docx, and xlsx.
- A file whose download is the outcome. In this guide the file is the pricing guide, pricing-guide.pdf, and the new event from the companion guide is not used here because every download on this site is a guide.
The trace
- Confirm file_download is collecting. Open Reports, then Engagement, then Events, and find the file_download row. If it is missing, enhanced measurement is off in the data stream, or no visitor has clicked a file link yet.
- Check the file_name parameter in DebugView. Open Admin, then Data display, then DebugView, download the file, and watch file_download arrive with file_name set to pricing-guide.pdf. The parameter is what separates one file from another.
- Decide whether to mark file_download or build a narrower event. If every download on the site is a guide that matters, mark file_download. If only one file matters, build a new event from file_download with a file_name condition first, as the create-key-event guide shows, and mark that instead. This guide marks file_download.
- Mark file_download as a key event. Open Admin, then Data display, then Events, and click the star on the file_download row. A standard property can mark up to 30 events, and this is one of them.
- Read the download count in the Events report. In the worked example the week shows 486 file_download events, of which 372 are the pricing guide and 114 are other files. Marking file_download counts all 486 as key events, which is why the narrower event exists for sites where only one file matters.
- Work out the session key event rate. The week shows 2,100 sessions and 351 sessions with a file_download key event, which is 351 / 2,100 = 16.71%. The 486 events came from 351 sessions, so 135 of those sessions downloaded more than one file.
Dead ends
DEAD END — MARKING file_download ON A SITE WITH A HUNDRED FILES. Every staff handbook, every invoice template, and every old brochure becomes a key event. The key event rate stops describing the outcome and starts describing the file library. Build the narrow event instead.
DEAD END — READING THE COUNT AS UNIQUE DOWNLOADS. The 486 events are downloads, not people. One visitor who downloads the same guide three times counts three times under once per event. Use sessions with a key event, 351 here, when the question is how many visits downloaded something.
DEAD END — EXPECTING file_download ON A BUTTON THAT IS NOT A LINK. Enhanced measurement fires on link clicks to files. A download button that runs a script without a file link fires nothing, and the event must be sent from Tag Manager instead.
End state
The file_download event is a key event on this site, where every download is a guide. The week closes at 486 key events from 351 sessions, a session key event rate of 16.71%.
| Figure | Value |
|---|---|
| Sessions in the week | 2,100 |
| file_download key events | 486 |
| Pricing guide downloads | 372 |
| Other file downloads | 114 |
| Sessions with a file_download key event | 351 |
| Session key event rate | 16.71% |
The rate is 351 / 2,100 = 16.71%, recomputed in Python 3 and rounded to two places. The file split adds up: 372 + 114 = 486. The figures are a worked example, not a real property.
Sources
- Analytics Help — [GA4] Recommended events — the recommended event names, including generate_lead, sign_up, and purchase
- Analytics Help — About key events — marking an event as a key event, the 30-event limit for a standard property, and 50 for Analytics 360
- Analytics Help — Monitor events in DebugView — watching events with their parameters in DebugView
Checked 11 November 2026. The click paths above are the ones in Google's help pages, read 11 November 2026. The file_download event is an enhanced measurement event with a file_name parameter, and marking it from Admin, then Data display, then Events, are as Google documents them. No step in this guide was run inside a live Analytics property, because Admin needs a Google sign-in and this site does not sign in as anyone. The figures on this page are a worked example recomputed in Python 3 with decimal arithmetic, not numbers from a real property. Google moves menu items without warning; if a path on this page no longer matches, the linked help page is the current map.