chore(website): track plugin download clicks in Google Analytics (#685)

[niklam]

Related Issue

Fixes #685

What changed?

Adds GA4 event tracking to the download links on /downloads/ so install activity can be analysed by platform, install method, and the app version current at the time. GA4 is already loaded site-wide (G-HKB3F7KB00); previously no custom events were fired.

• New packages/website/src/components/DownloadLink.astro — renders the anchor and, via a single Astro-deduped bundled <script>, attaches a click handler to every a[data-download-link] that fires gtag("event", "file_download", { platform, method, app_version }). Mirrors the existing ChangelogLeadIn.astro pattern (no inline <script> in MDX).
• downloads.mdx now uses the component for all four links: the two direct-download buttons (method="direct") and the two store links (method="store"), tagged platform="stream-deck" / "mirabox".

Event parameters:

Param	Values
platform	stream-deck, mirabox (ready for ulanzi) — reuses the ecosystem ids from the changelog version-check flow
method	direct (our download redirect) or store (Elgato Marketplace / Mirabox Space)
app_version	PUBLIC_IRACEDECK_VERSION at build time; omitted when blank

The handler no-ops if gtag is unavailable and never blocks the navigation/download — GA4 flushes the event via sendBeacon. Forward-compatible: when Ulanzi joins the downloads page it is instrumented identically with platform="ulanzi", no new event name.

Follow-up outside the repo: platform, method, and app_version must be registered as custom dimensions in the GA4 property to be queryable in reports.

No changelog entry — internal instrumentation, invisible to users (per the changelog rule).

How to test

1. cd packages/website && pnpm dev
2. Open http://localhost:4321/downloads/.
3. DevTools → Network, filter collect. Clicking any of the four links fires a request with en=file_download and ep.platform / ep.method / ep.app_version (GA4 DebugView shows the same). Dev uses the fallback version 1.22.0-dev.0.

Verified locally: pnpm --filter @iracedeck/website build passes and the built /downloads/index.html carries the data attributes + inlined tracking script; pnpm lint, pnpm format, and the full pnpm test suite (177 files / 5401 tests) are green.

Checklist

• Linked to an approved issue
• New code has unit tests — N/A: the website package has no test harness; the change is an .astro component with no testable TS logic (same as the existing ChangelogLeadIn.astro). Verified via build + built-output inspection instead.
• Changes registered in all applicable plugins (Stream Deck, Mirabox) — N/A: website-only change, no plugin/action code touched.
• No unrelated changes included

Summary by CodeRabbit

• New Features
  • Added improved analytics tracking for download actions across all supported platforms (Stream Deck, Mirabox, and Ulanzi) and installation methods (direct downloads and marketplace installations) to better measure user engagement and download patterns.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 69075218-46b6-4252-93b0-c5838c280709

📥 Commits

Reviewing files that changed from the base of the PR and between 9bad174 and 4419b91.

📒 Files selected for processing (2)

• packages/website/src/components/DownloadLink.astro
• packages/website/src/content/docs/downloads.mdx

---

📝 Walkthrough

Walkthrough

Adds a new DownloadLink.astro component that renders an anchor element with data-* attributes and a client-side script firing a GA4 file_download event on click. Updates downloads.mdx to import and use this component in place of plain <a> tags for all four download/store links.

Changes

GA4 Download Click Tracking

Layer / File(s)	Summary
DownloadLink component and GA4 click handler packages/website/src/components/DownloadLink.astro	Defines typed Props (href, platform, method, class?), renders the anchor with data-platform, data-method, and data-app-version attributes, and includes a client-side script that attaches click listeners to all [data-download-link] anchors and calls window.gtag('event', 'file_download', …) with optional app_version.
downloads.mdx wired to DownloadLink packages/website/src/content/docs/downloads.mdx	Imports DownloadLink and replaces four plain <a> elements (Stream Deck direct, Stream Deck store, Mirabox direct, Mirabox store) with <DownloadLink> component instances carrying the appropriate platform and method props.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• niklam/iracedeck#200: Originally built the downloads page (downloads.mdx) that this PR instruments with GA4 tracking by replacing its plain anchor tags with the new DownloadLink component.

Poem

🐇 Hop, hop — a click is heard,
The rabbit logs each download word.
file_download flies to GA4 skies,
Platform, method, version applied.
No delay, no redirect stopped,
Just pure analytics, nicely tracked! 📊

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'track plugin download clicks in Google Analytics' directly summarizes the main change: adding GA4 event tracking to download links. It is clear, specific, and accurately represents the core objective.
Description check	✅ Passed	The description covers all required template sections: Related Issue (Fixes #685), What changed (detailed explanation with implementation), How to test (clear steps), and Checklist (mostly complete). The PR description is comprehensive and well-documented.
Linked Issues check	✅ Passed	The PR fully addresses issue #685: it instruments all four required links (Stream Deck direct, Mirabox direct, Elgato Marketplace, Mirabox Space) with correct platform/method parameters, fires file_download events on click with app_version, and follows the specified ChangelogLeadIn.astro pattern.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked issue #685: a new DownloadLink.astro component and updates to downloads.mdx to use it for GA4 tracking. No unrelated modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/685-download-analytics

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}