File name dimension: tracking downloads
File name is the dimension that records which document a visitor downloaded. GA4 enhanced measurement fires a file_download event when a link points to a recognised file extension, capturing file_name, file_extension, and link_text. It only watches a fixed list of common extensions (pdf, docx, xlsx, zip, and similar), so downloads with other extensions or behind redirects can go uncounted.
What this means
GA4 enhanced measurement inspects link clicks and, when the href ends in a recognised file extension, fires a file_download event. It records file_name (the path/name), file_extension, and link_text, so the file name dimension shows which assets people take.
This is the standard way to measure PDF whitepapers, spreadsheets, and other downloadable content without manual instrumentation.
Why some downloads are missed
Detection is extension-based against a fixed default list (including pdf, doc/docx, xls/xlsx, ppt/pptx, zip, and a handful more). A download whose URL has no extension, uses an uncommon one, or is delivered through a redirect or query-string handler will not match and goes uncounted.
For those, you add an explicit file_download or custom event so the file name dimension stays complete.
- Fired by enhanced measurement on recognised extensions
- Captures file_name, file_extension, link_text
- Extension-less or redirected downloads need manual events
How it appears in analytics and logs
A file name value means a download link with a recognised extension was clicked. Missing downloads usually mean the extension is not on GA4's default list, or the file is served via a redirect the click detector cannot see.
Diagnostic use case
Use file name to measure which downloads are popular, while confirming the file's extension is on GA4's watched list or adding explicit tracking if not.
What WebmasterID can help detect
WebmasterID can log downloads as first-party events, so document popularity is measurable without third-party scripts or visitor identification.
Common mistakes
- Assuming every download is captured regardless of extension.
- Overlooking redirect-served files the click detector cannot see.
- Not adding manual events for non-default file types.
Privacy and accuracy notes
File name records the downloaded asset, not the downloader — unless the filename itself encodes personal data. WebmasterID captures download events first-party without identifying the visitor.
Related pages
- Link URL dimension: where outbound clicks go
Link URL is the dimension that records the destination of a clicked link. In GA4 it is populated by the click event from enhanced measurement, which fires on outbound links and carries link_url, link_domain, and link_text. It answers 'where did people leave to?', but its automatic scope is limited to links leaving your domain — internal and same-domain clicks need separate handling.
- Video title dimension: which videos get watched
Video title is the dimension that records which embedded video a visitor engaged with. GA4 enhanced measurement captures it for YouTube embeds that use the IFrame Player API, firing video_start, video_progress, and video_complete with a video_title parameter. The key limit: only API-enabled YouTube players are auto-tracked — other hosts and plain embeds need manual instrumentation to populate the dimension.
- The file_download event
A file_download event records that a visitor clicked a link to a downloadable file — a PDF, document, archive, or media file. Like outbound clicks, downloads escape ordinary page analytics because no new page loads. GA4 enhanced measurement fires file_download automatically for a defined list of file extensions, capturing the link and file type without code.
- Event Explorer
Inspect file_download events behind the dimension.
Sources and verification notes
- Google Analytics Help — [GA4] Enhanced measurement eventsLists the file extensions that trigger file_download.
Last reviewed 2026-06-24. Facts are checked against primary/official sources where available; uncertain specifics are marked “Data not yet verified” rather than guessed.