Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

feat(growth): in-memory first-touch attribution store (#43570)

Sean Oliverc8e98cec0e57
diff --git a/packages/common/hooks/index.ts b/packages/common/hooks/index.ts
index 3d3b082f3d3..495fbf0ee3c 100644
--- a/packages/common/hooks/index.ts
+++ b/packages/common/hooks/index.ts
@@ -12,6 +12,6 @@ export * from './useIsomorphicLayoutEffect'
export * from './useOnChange'
export * from './useParams'
export * from './useSearchParamsShallow'
-export * from './useTelemetryCookie'
+export * from './useFirstTouchStore'
export * from './useThemeSandbox'
export * from './useViewport'
diff --git a/packages/common/hooks/useFirstTouchStore.ts b/packages/common/hooks/useFirstTouchStore.ts
new file mode 100644
index 00000000000..eb7e1d481d1
--- /dev/null
+++ b/packages/common/hooks/useFirstTouchStore.ts
@@ -0,0 +1,17 @@
+import { useEffect } from 'react'
+
+import { setFirstTouchData } from '../telemetry-first-touch-store'
+import { getSharedTelemetryData } from '../telemetry-utils'
+
+interface UseFirstTouchStoreProps {
+ enabled: boolean
+}
+
+export function useFirstTouchStore({ enabled }: UseFirstTouchStoreProps) {
+ useEffect(() => {
+ if (!enabled) return
+
+ const telemetryData = getSharedTelemetryData(window.location.pathname)
+ setFirstTouchData(telemetryData)
+ }, [enabled])
+}
diff --git a/packages/common/hooks/useTelemetryCookie.tsx b/packages/common/hooks/useTelemetryCookie.tsx
index 8e02fd14a0f..0e06ed2d2ed 100644
--- a/packages/common/hooks/useTelemetryCookie.tsx
+++ b/packages/common/hooks/useTelemetryCookie.tsx
@@ -8,9 +8,8 @@ interface UseTelemetryCookieProps {
}
/**
- * This hook saves the initial telemetry data to a cookie so we can preserve first-touch attribution
- * (e.g. `document.referrer`) until the initial pageview is emitted. If the user never
- * consents, this cookie is never used.
+ * @deprecated Superseded by `useFirstTouchStore` which uses an in-memory store
+ * instead of a cookie. Removal tracked under GROWTH-646.
*/
export function useTelemetryCookie({ enabled }: UseTelemetryCookieProps) {
const telemetryStorageKey = LOCAL_STORAGE_KEYS.TELEMETRY_DATA
diff --git a/packages/common/telemetry-first-touch-store.test.ts b/packages/common/telemetry-first-touch-store.test.ts
new file mode 100644
index 00000000000..889c570049d
--- /dev/null
+++ b/packages/common/telemetry-first-touch-store.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it } from 'vitest'
+
+import {
+ clearFirstTouchData,
+ getFirstTouchData,
+ setFirstTouchData,
+} from './telemetry-first-touch-store'
+
+const makeFakeData = (pathname: string) =>
+ ({
+ page_url: `https://supabase.com${pathname}`,
+ pathname,
+ page_title: 'Test',
+ session_id: 'test-session',
+ ph: { referrer: 'https://google.com' },
+ }) as ReturnType<typeof getFirstTouchData> & {}
+
+describe('telemetry-first-touch-store', () => {
+ // Reset between tests so module-scoped state doesn't leak
+ afterEach(() => {
+ clearFirstTouchData()
+ })
+
+ it('returns null before any write', () => {
+ expect(getFirstTouchData()).toBeNull()
+ })
+
+ it('stores data and returns it on read', () => {
+ const data = makeFakeData('/pricing')
+ setFirstTouchData(data)
+ expect(getFirstTouchData()).toEqual(data)
+ })
+
+ it('is write-once: a second call with different data is a no-op', () => {
+ const first = makeFakeData('/pricing')
+ const second = makeFakeData('/docs')
+
+ setFirstTouchData(first)
+ setFirstTouchData(second)
+
+ expect(getFirstTouchData()).toEqual(first)
+ })
+
+ it('clearFirstTouchData resets to null', () => {
+ setFirstTouchData(makeFakeData('/pricing'))
+ clearFirstTouchData()
+ expect(getFirstTouchData()).toBeNull()
+ })
+
+ it('allows writing again after clearFirstTouchData', () => {
+ const first = makeFakeData('/pricing')
+ const second = makeFakeData('/docs')
+
+ setFirstTouchData(first)
+ clearFirstTouchData()
+
+ setFirstTouchData(second)
+ expect(getFirstTouchData()).toEqual(second)
+ })
+})
diff --git a/packages/common/telemetry-first-touch-store.ts b/packages/common/telemetry-first-touch-store.ts
new file mode 100644
index 00000000000..42719bf17fa
--- /dev/null
+++ b/packages/common/telemetry-first-touch-store.ts
@@ -0,0 +1,27 @@
+/**
+ * In-memory store for first-touch attribution data (referrer, UTMs, page URL).
+ *
+ * Captured before consent so no device storage is needed. Data is read once
+ * by PageTelemetry after consent, then cleared. Lost on hard reload — accepted
+ * trade-off (GROWTH-656).
+ */
+
+import type { getSharedTelemetryData } from './telemetry-utils'
+
+export type SharedTelemetryData = ReturnType<typeof getSharedTelemetryData>
+
+let firstTouchData: SharedTelemetryData | null = null
+
+/** Write-once — subsequent calls are no-ops. */
+export function setFirstTouchData(data: SharedTelemetryData): void {
+ if (firstTouchData !== null) return
+ firstTouchData = data
+}
+
+export function getFirstTouchData(): SharedTelemetryData | null {
+ return firstTouchData
+}
+
+export function clearFirstTouchData(): void {
+ firstTouchData = null
+}
diff --git a/packages/common/telemetry.tsx b/packages/common/telemetry.tsx
index 0ea50a3931e..d9b3efaf688 100644
--- a/packages/common/telemetry.tsx
+++ b/packages/common/telemetry.tsx
@@ -9,7 +9,7 @@ import { useLatest } from 'react-use'
import { useUser } from './auth'
import { hasConsented, useConsentState } from './consent-state'
-import { IS_PLATFORM, IS_PROD, LOCAL_STORAGE_KEYS } from './constants'
+import { IS_PLATFORM } from './constants'
import { useFeatureFlags } from './feature-flags'
import { post } from './fetchWrappers'
import type { FirstReferrerData, MwDiagData } from './first-referrer-cookie'
@@ -19,22 +19,19 @@ import {
parseMwDiagCookie,
} from './first-referrer-cookie'
import { ensurePlatformSuffix, isBrowser } from './helpers'
-import { useParams, useTelemetryCookie } from './hooks'
+import { useFirstTouchStore, useParams } from './hooks'
import { posthogClient, type ClientTelemetryEvent } from './posthog-client'
import { TelemetryEvent } from './telemetry-constants'
import {
- clearTelemetryDataCookie,
- getSharedTelemetryData,
- getTelemetryCookieOptions,
-} from './telemetry-utils'
+ clearFirstTouchData,
+ getFirstTouchData,
+ type SharedTelemetryData,
+} from './telemetry-first-touch-store'
+import { getSharedTelemetryData, getTelemetryCookieOptions } from './telemetry-utils'
export { posthogClient, type ClientTelemetryEvent }
-const { TELEMETRY_DATA } = LOCAL_STORAGE_KEYS
-
-// Reexports GoogleTagManager with the right API key set
export const TelemetryTagManager = () => {
- // useConsentState is used here to trigger a re-render when consent state changes
const { hasAccepted } = useConsentState()
const isGTMEnabled = Boolean(
@@ -54,11 +51,6 @@ export const TelemetryTagManager = () => {
)
}
-//---
-// PAGE TELEMETRY
-//---
-type SharedTelemetryData = ReturnType<typeof getSharedTelemetryData>
-
function getFirstTouchAttributionProps(telemetryData: SharedTelemetryData) {
const urlString = telemetryData.page_url
@@ -80,7 +72,6 @@ function getFirstTouchAttributionProps(telemetryData: SharedTelemetryData) {
...(getParam('utm_term') && { $utm_term: getParam('utm_term') }),
}
- // Ad network click IDs (first-touch attribution)
const clickIdProps = {
...(getParam('gclid') && { gclid: getParam('gclid') }), // Google Ads
...(getParam('gbraid') && { gbraid: getParam('gbraid') }), // Google Ads (iOS)
@@ -126,14 +117,13 @@ function handlePageTelemetry({
firstReferrerData,
mwDiagData,
}: HandlePageTelemetryOptions) {
- // Send to PostHog client-side (only in browser)
if (typeof window !== 'undefined') {
const livePageData = getSharedTelemetryData(pathname)
const liveReferrer = livePageData.ph.referrer
- const cookieReferrer = telemetryDataOverride?.ph?.referrer
+ const storedReferrer = telemetryDataOverride?.ph?.referrer
- const shouldUseCookieReferrer = Boolean(
- cookieReferrer && isExternalReferrer(cookieReferrer) && !isExternalReferrer(liveReferrer)
+ const shouldUseStoredReferrer = Boolean(
+ storedReferrer && isExternalReferrer(storedReferrer) && !isExternalReferrer(liveReferrer)
)
const pageData = telemetryDataOverride
@@ -141,7 +131,7 @@ function handlePageTelemetry({
...livePageData,
ph: {
...livePageData.ph,
- referrer: shouldUseCookieReferrer ? cookieReferrer! : liveReferrer,
+ referrer: shouldUseStoredReferrer ? storedReferrer! : liveReferrer,
},
}
: { ...livePageData, ph: { ...livePageData.ph } }
@@ -149,9 +139,6 @@ function handlePageTelemetry({
...(telemetryDataOverride ? getFirstTouchAttributionProps(telemetryDataOverride) : {}),
}
- // --- First-referrer edge cookie handoff ---
- // If the edge cookie has external context and the current referrer is internal,
- // override the referrer so PostHog gets the real acquisition source.
const firstReferrerCookiePresent = Boolean(firstReferrerData)
let firstReferrerCookieConsumed = false
@@ -163,7 +150,6 @@ function handlePageTelemetry({
pageData.ph.referrer = firstReferrerData.referrer
firstReferrerCookieConsumed = true
- // Prefer attribution context captured at the external entry point.
const { utms, click_ids, landing_url } = firstReferrerData
Object.entries(utms).forEach(([key, value]) => {
@@ -200,7 +186,6 @@ function handlePageTelemetry({
}
})()
- // Align frontend and backend session IDs for correlation
if (pageData.session_id) {
document.cookie = `session_id=${pageData.session_id}; ${getTelemetryCookieOptions()}`
}
@@ -222,15 +207,11 @@ function handlePageTelemetry({
...Object.fromEntries(
Object.entries(featureFlags || {}).map(([k, v]) => [`$feature/${k}`, v])
),
- // Measurement properties for handoff observability
- // Only included on the initial pageview (when firstReferrerData is explicitly
- // passed as null or a value — subsequent pageviews leave it as undefined)
+ // Only included on the initial pageview — subsequent pageviews omit firstReferrerData entirely
...(firstReferrerData !== undefined && {
first_referrer_cookie_present: firstReferrerCookiePresent,
first_referrer_cookie_consumed: firstReferrerCookieConsumed,
}),
- // Phase 1 middleware diagnostic: present only when _sb_mw_diag cookie was found
- // (i.e., the request was routed through www middleware on /dashboard or /docs)
...(mwDiagData && {
mw_diag_hit: mwDiagData.hit,
mw_diag_would_stamp: mwDiagData.would_stamp,
@@ -251,7 +232,6 @@ export function handlePageLeaveTelemetry(
slug?: string,
ref?: string
) {
- // Send to PostHog client-side (only in browser)
if (typeof window !== 'undefined') {
const pageData = getSharedTelemetryData(pathname)
posthogClient.capturePageLeave({
@@ -283,14 +263,13 @@ export const PageTelemetry = ({
const pagesPathname = router?.pathname
const appPathname = usePathname()
- // Get from props or try to extract from URL params
const params = useParams()
const slug = organizationSlug || params.slug
const ref = projectRef || params.ref
const featureFlags = useFeatureFlags()
- useTelemetryCookie({ enabled: enabled && IS_PLATFORM })
+ useFirstTouchStore({ enabled: enabled && IS_PLATFORM })
const pathname =
pagesPathname ?? appPathname ?? (isBrowser ? window.location.pathname : undefined)
@@ -327,98 +306,54 @@ export const PageTelemetry = ({
})
}, [API_URL, enabled, hasAcceptedConsent, slug, ref])
- // Handle initial page telemetry event
const hasSentInitialPageTelemetryRef = useRef(false)
-
- // Track previous pathname for App Router to detect actual changes
const previousAppPathnameRef = useRef<string | null>(null)
- // Initialize PostHog client when consent is accepted
useEffect(() => {
if (hasAcceptedConsent && IS_PLATFORM) {
posthogClient.init(true)
}
}, [hasAcceptedConsent, IS_PLATFORM])
+ // Waiting for router.isReady before sending to avoid dynamic route placeholders
useEffect(() => {
- // Send page telemetry on first page load
- // Waiting for router ready before sending page_view
- // if not the path will be dynamic route instead of the browser url
if (
(router?.isReady ?? true) &&
+ enabled &&
hasAcceptedConsent &&
!hasSentInitialPageTelemetryRef.current
) {
- // Read the edge-set cookies (cross-app handoff)
const cookieHeader = document.cookie
const firstReferrerData = parseFirstReferrerCookie(cookieHeader)
const mwDiagData = parseMwDiagCookie(cookieHeader)
+ const firstTouchData = getFirstTouchData()
- const cookies = cookieHeader.split(';')
- const telemetryCookieValue = cookies
- .map((cookie) => cookie.trim())
- .find((cookie) => cookie.startsWith(`${TELEMETRY_DATA}=`))
- ?.slice(`${TELEMETRY_DATA}=`.length)
-
- if (telemetryCookieValue) {
- try {
- const telemetryData = JSON.parse(
- decodeURIComponent(telemetryCookieValue)
- ) as SharedTelemetryData
- handlePageTelemetry({
- apiUrl: API_URL,
- pathname: pathnameRef.current,
- featureFlags: featureFlagsRef.current,
- slug,
- ref,
- telemetryDataOverride: telemetryData,
- firstReferrerData,
- mwDiagData,
- })
- } catch (error) {
- if (!IS_PROD) {
- console.warn('Invalid telemetry cookie data:', error)
- }
- handlePageTelemetry({
- apiUrl: API_URL,
- pathname: pathnameRef.current,
- featureFlags: featureFlagsRef.current,
- slug,
- ref,
- firstReferrerData,
- mwDiagData,
- })
- } finally {
- clearTelemetryDataCookie()
- }
- } else {
+ try {
handlePageTelemetry({
apiUrl: API_URL,
pathname: pathnameRef.current,
featureFlags: featureFlagsRef.current,
slug,
ref,
+ ...(firstTouchData && { telemetryDataOverride: firstTouchData }),
firstReferrerData,
mwDiagData,
})
+ } finally {
+ clearFirstTouchData()
+ hasSentInitialPageTelemetryRef.current = true
}
-
- hasSentInitialPageTelemetryRef.current = true
}
- }, [router?.isReady, hasAcceptedConsent, slug, ref])
+ }, [router?.isReady, enabled, hasAcceptedConsent, slug, ref])
useEffect(() => {
- // For pages router
if (router === null) return
function handleRouteChange() {
- // Wait until we've sent the initial page telemetry event
if (!hasSentInitialPageTelemetryRef.current) return
-
sendPageTelemetry()
}
- // Listen for page changes after a navigation or when the query changes
router.events.on('routeChangeComplete', handleRouteChange)
return () => {
@@ -427,10 +362,8 @@ export const PageTelemetry = ({
}, [router])
useEffect(() => {
- // For app router
if (router !== null) return
- // Only track if pathname actually changed (not initial mount)
if (
appPathname &&
previousAppPathnameRef.current !== null &&
@@ -439,7 +372,6 @@ export const PageTelemetry = ({
sendPageTelemetry()
}
- // Update previous pathname
previousAppPathnameRef.current = appPathname
}, [appPathname, router, sendPageTelemetry])
@@ -452,16 +384,11 @@ export const PageTelemetry = ({
return () => window.removeEventListener('beforeunload', handleBeforeUnload)
}, [enabled, sendPageLeaveTelemetry])
- // Identify the user
useTelemetryIdentify(API_URL)
return null
}
-// ---
-// EVENT TELEMETRY
-// ---
-
type EventBody = components['schemas']['TelemetryEventBodyV2']
export function sendTelemetryEvent(API_URL: string, event: TelemetryEvent, pathname?: string) {