Skip to content

fix(download-proxy): Report telemetry per download, not per range - #975

Merged
kotevcode merged 1 commit into
mainfrom
fix/download-proxy-dedupe-ranges
Aug 31, 2026
Merged

fix(download-proxy): Report telemetry per download, not per range#975
kotevcode merged 1 commit into
mainfrom
fix/download-proxy-dedupe-ranges

Conversation

@kotevcode

Copy link
Copy Markdown
Contributor

Summary

GA4 showed more `download_completed` events than `download_vpr` clicks on ad-wave days. Two causes, one of which is fixable in the Worker:

  1. Per-request reporting. Download managers (IDM etc.) fetch one installer as N concurrent byte ranges, and browsers resume a paused download with a new `Range` request. Each request emitted its own `download_started` / `download_completed`. Over the last 14 days, `partial=1` was 142 Windows completions from just 50 users (~3×).
  2. Ad blockers. `download_vpr` is a browser-side GTM event; the proxy events are server-side. 38% of completions arrived with no GA ids (no `_ga` cookie → GA never ran in that browser), so those visitors can't have fired the click event at all. Not fixable, but now visible.

Changes

  • `segmentRole(status, contentRange)`: a 200 is first+final; a 206 is first when its `Content-Range` starts at byte 0 and final when it ends at `total-1`. Unparseable or `*`-total ranges fall back to first+final so a misbehaving origin never drops a download.
  • `download_started` is emitted only for the first segment; `download_completed` / `download_aborted` only for the final one. Middle segments are logged to the console as `download_segment_completed/aborted` and never sent to GA. `partial=1` stays on the reported events so download-manager users remain identifiable.
  • Every GA4 event now carries `attributed: 1|0` (previously console-only), separating visitors whose browser passed GA ids from those where GA was blocked.
  • README telemetry section rewritten; CHANGELOG entry under Unreleased → Changed.

Result: an 8-range IDM download yields 1 started + 1 completed instead of 8 + 8; a browser pause/resume yields 1 started, 1 aborted, 1 completed.

Known edge: a Safari-style `bytes=0-1` probe still emits one extra `download_started` (no end event).

After merge

  • `pnpm --filter @antseed/download-proxy deploy`
  • GA4: register `attributed` as an event-scoped custom dimension; consider moving the key event (PMax target) from `download_completed` to `download_started`, or keep `completed` now that it is 1:1 with downloads.
  • Funnel: `download_vpr → download_started → download_completed` on unique users; read `download_vpr` for page/section breakdowns only.

Testing

  • `pnpm --filter @antseed/download-proxy typecheck` — clean
  • `pnpm --filter @antseed/download-proxy test` — 25 passed (10 new: segmented download, browser resume, fallbacks, middle-segment naming, `deliverEvent` payloads for attributed/unattributed/unconfigured)

…uest

Download managers fetch an installer as several concurrent byte ranges and
browsers resume paused downloads with a new Range request; each request
emitted its own download_started/download_completed, inflating both ~3x for
those clients. Only the request covering byte 0 now starts a download and
only the one delivering the last byte ends it; middle segments are logged
locally. Every GA4 event also carries an attributed (1/0) param so downloads
from browsers that blocked GA (and so never fired download_vpr) are
distinguishable.
@kotevcode
kotevcode merged commit 7357554 into main Aug 31, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant