greptileai / supabase-mirror / 22328312104

73%

push

github

fix: persist first referrer across app boundaries (#42768)

## Summary

Fixes GROWTH-625.

Preserves first-touch attribution across app boundaries by persisting
external referrer context at the edge and consuming it on Studio's
initial pageview.

When users come from an external source to www/docs and then navigate to
Studio, Studio often only sees the internal `supabase.com` hop. This
change preserves the original external context so first-touch
attribution is retained.

## What changed

- **Shared first-referrer cookie utilities**
(`packages/common/first-referrer-cookie.ts`):
- `isExternalReferrer`, `buildFirstReferrerData`,
`serializeFirstReferrerCookie`, `parseFirstReferrerCookie`
- `hasPaidSignals` — detects click IDs (gclid, fbclid, etc.) and paid
utm_medium values
- `shouldRefreshCookie` — centralizes stamp-or-skip decision for all
apps
- `stampFirstReferrerCookie` — shared middleware helper used by all apps
(extracted from duplicated inline logic)
- **Edge middleware on all apps** — stamps cookie for external visitors,
refreshes on paid signals:
  - `apps/www/middleware.ts` (simplified to use shared helper)
  - `apps/docs/middleware.ts` (simplified to use shared helper)
  - `apps/studio/proxy.ts` (integrated into existing proxy file)
- **Docs middleware matcher** — broadened from `/reference/:path*` to
all non-static paths so the first-referrer cookie is stamped on all docs
pages, not just reference paths
- **Telemetry** — Studio consumes cookie on initial pageview
(`packages/common/telemetry.tsx`). `handlePageTelemetry` refactored from
7 positional params to an options object for readability.
- **Tests** — 22 unit tests covering all utilities and edge cases
(including direct-navigation scenario)

## Behavior

- Writes `_sb_first_referrer` cookie when:
  - cookie is not already set and request has an external referrer, OR
- cookie exists but incoming URL has paid traffic signals (click IDs or
paid utm_medium)
- Cookie: 365-day TTL, `domain=sup... (continued)

822 of 931 branches covered (88.29%)

Branch coverage included in aggregate %.

3068 of 4346 relevant lines covered (70.59%)

113.12 hits per line