Added gift link filter to web analytics

[luissazevedo]

ref https://linear.app/ghost/issue/BER-3746/integrate-gift-link-usage-tracking-with-analytics

What

Adds a Gift link filter on the Web traffic tab, under Location in the filter dropdown, in both site-wide analytics (apps/stats) and per-post analytics (apps/posts). Selecting it produces an editable chip — Gift link · is · [used ▾] — where only the value (used / not used) is changeable.

It's a static binary select (not a Tinybird-backed option list), and is gated behind the giftLinks labs flag.

How

• New gift_link select field (options used / not used) added to both stats-filter.tsx files, right after location, shown only when the giftLinks labs flag is on.
• gift_link added to SUPPORTED_FILTER_FIELDS so the filter round-trips through the URL (bookmark/shareable) into the Tinybird query params. The URL ⇄ filter sync is also gated on the labs flag, so a stale gift_link param (e.g. a shared link) can't apply an invisible, unremovable filter when the flag is off.
• The data query needs no change — both web.tsx views already forward non-audience filters generically.
• Option values match the contract the Added gift dimension to the web analytics data files #28854 pipes expect: used → gift_link=true, not used → gift_link=false. The pipes resolve gift_link == 'false' || '0' as "no gift link", any other value as "has a gift link".

Backend dependency

Consumes the gift_link dimension + value-aware endpoint logic from #28854 — that PR must be merged/deployed first. As of its latest revision, #28854 wires gift_link into every endpoint this filter hits (api_kpis_v2, api_top_pages_v3, api_top_locations_v2, api_active_visitors_v2, filtered_sessions_v2), so both used and not used return correct data with the value encoding above.

Testing

• Lint: ✅ both apps
• tsc --noEmit: ✅ both apps
• Unit: ✅ stats 234/234, posts 484/484

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2cfb3cb6-8ac9-4ecb-949b-54ec74afa96a

📥 Commits

Reviewing files that changed from the base of the PR and between ba65f6d and 4e57d91.

📒 Files selected for processing (2)

• apps/posts/src/views/PostAnalytics/components/stats-filter.tsx
• apps/stats/src/views/Stats/components/stats-filter.tsx

🚧 Files skipped from review as they are similar to previous changes (2)

• apps/posts/src/views/PostAnalytics/components/stats-filter.tsx
• apps/stats/src/views/Stats/components/stats-filter.tsx

---

Walkthrough

Both apps/stats and apps/posts add a gift_link filter field gated by the giftLinks labs flag. The URL sync helpers now accept a dynamic supportedFields set, and useFilterParams computes that set from the labs flag in each app. Each StatsFilter view adds giftLinkField with binary “used”/“not used” options, conditionally inserts it into the Basic group, and updates buildFilterParams to include gift_link values in Tinybird request params.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change by adding a gift link filter to web analytics.
Description check	✅ Passed	The description directly explains the gift link filter, labs gating, URL sync, and backend dependency.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ber-3746-gift-link-analytics-filter

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[nx-cloud]

🤖 Nx Cloud AI Fix

Ensure the fix-ci command is configured to always run in your CI pipeline to get automatic fixes in future runs. For more information, please see https://nx.dev/ci/features/self-healing-ci

---

View your CI Pipeline Execution ↗ for commit 4e57d91

Command	Status	Duration	Result
nx run-many --target=build --projects=tag:publi...	✅ Succeeded	3s	View ↗
nx run-many -t test:unit -p @tryghost/posts,@tr...	✅ Succeeded	3m 20s	View ↗
nx run @tryghost/admin:build	✅ Succeeded	2m 2s	View ↗
nx run ghost:build:assets	✅ Succeeded	2s	View ↗
nx run-many -t lint -p @tryghost/posts,@tryghos...	✅ Succeeded	22s	View ↗
nx run ghost:build:tsc	✅ Succeeded	6s	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-06-30 10:09:00 UTC

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/posts/src/views/PostAnalytics/components/stats-filter.tsx`:
- Around line 36-39: The gift link filter in stats-filter.tsx is forwarding raw
values from GIFT_LINK_OPTIONS through buildFilterParams, so “not used” currently
sends gift_link=not_used even though the intended semantics are used/non-empty
and not used/empty. Update the frontend gating around the giftLinks path in
PostAnalytics (including the filter option handling and any related usage in
buildFilterParams) so this option is only enabled once the backend supports both
literal values, and keep the flag off until the backend behavior is ready.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d2adb8cf-e50c-42bc-895b-540b79b7a9bd

📥 Commits

Reviewing files that changed from the base of the PR and between d6c0cc7 and ba65f6d.

📒 Files selected for processing (4)

• apps/posts/src/hooks/use-filter-params.ts
• apps/posts/src/views/PostAnalytics/components/stats-filter.tsx
• apps/stats/src/hooks/use-filter-params.ts
• apps/stats/src/views/Stats/components/stats-filter.tsx

[coderabbitai]

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Verify backend handling of the literal gift_link values.

buildFilterParams forwards the raw option value, so selecting not used sends gift_link=not_used (and used sends gift_link=used). Per the comment at Lines 33-35 the intended semantics are "used → non-empty gift_link, not used → empty", which only holds once the value-aware backend handling from #28854 lands. Until then the not used path will return incorrect data. Since this is gated behind giftLinks, confirm the flag stays off until the backend supports both values.

Also applies to: 125-125

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/posts/src/views/PostAnalytics/components/stats-filter.tsx` around lines
36 - 39, The gift link filter in stats-filter.tsx is forwarding raw values from
GIFT_LINK_OPTIONS through buildFilterParams, so “not used” currently sends
gift_link=not_used even though the intended semantics are used/non-empty and not
used/empty. Update the frontend gating around the giftLinks path in
PostAnalytics (including the filter option handling and any related usage in
buildFilterParams) so this option is only enabled once the backend supports both
literal values, and keep the flag off until the backend behavior is ready.