@djangocfg/analytics 2.1.476

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@djangocfg/analytics",
+  "version": "2.1.476",
+  "description": "First-party analytics for django-cfg apps: one route listener, N transports (self-hosted + GA4). Pageviews, sessions, and authenticated-user attribution.",
+  "keywords": [
+    "django",
+    "analytics",
+    "pageviews",
+    "ga4",
+    "privacy",
+    "react",
+    "nextjs",
+    "typescript"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "packages/analytics"
+  },
+  "bugs": {
+    "url": "https://github.com/markolofsen/django-cfg/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "require": "./src/index.ts"
+    },
+    "./core": {
+      "types": "./src/core/index.ts",
+      "import": "./src/core/index.ts",
+      "require": "./src/core/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "lint": "eslint ."
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-ga4": "^2.1.0"
+  },
+  "peerDependenciesMeta": {
+    "react-ga4": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@djangocfg/typescript-config": "^2.1.476",
+    "@types/node": "^25.9.5",
+    "@types/react": "19.2.15",
+    "next": "^15.5.9",
+    "react-ga4": "^2.1.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/core/client.ts

@@ -0,0 +1,139 @@
+/**
+ * The analytics client. Framework-agnostic, zero React.
+ *
+ * One instance owns the fan-out to every transport, plus the two pieces of
+ * state that MUST be module-scoped rather than component-scoped:
+ *
+ *   - the dedup key (see `trackPageview`)
+ *   - the flush listeners (registered once, in `init`)
+ *
+ * Nothing is registered at module top level: listeners attach only inside
+ * `init()`. A top-level side effect would defeat `sideEffects: false` and get
+ * tree-shaken in some bundlers while surviving in others — the worst kind of
+ * inconsistency.
+ */
+
+import type { AnalyticsEventPayload, AnalyticsOptions, AnalyticsTransport } from './types'
+
+export class AnalyticsClient {
+  private transports: AnalyticsTransport[] = []
+  private started = false
+  private debug: boolean
+
+  /**
+   * The last pageview key we sent.
+   *
+   * MUST live here, not in a React ref. React 19 StrictMode remounts components
+   * in development, and a `useRef` is reset by that remount — so the guard would
+   * not guard. A module/instance-scoped value survives it.
+   *
+   * This is also what makes `router.refresh()` not count as a pageview: the URL
+   * key is unchanged, so it is suppressed.
+   */
+  private lastPageviewKey: string | null = null
+
+  private flushHandler?: () => void
+  private pagehideHandler?: () => void
+
+  constructor(options: AnalyticsOptions) {
+    this.transports = options.transports ?? []
+    this.debug = options.debug ?? true
+  }
+
+  async init(): Promise<void> {
+    if (this.started || typeof window === 'undefined') return
+    this.started = true
+
+    for (const t of this.transports) {
+      try {
+        await t.init?.()
+      } catch (err) {
+        // A broken transport must never break the page it is measuring.
+        this.warn(`transport "${t.name}" failed to init`, err)
+      }
+    }
+
+    this.registerFlushListeners()
+  }
+
+  /**
+   * Track a pageview, unless it is a duplicate of the last one.
+   *
+   * The key is the full URL, so a `router.refresh()` or a StrictMode double
+   * effect collapses into one event, while a real navigation always fires.
+   */
+  trackPageview(payload: AnalyticsEventPayload): void {
+    const key = `${payload.pathname}?${payload.props?.search ?? ''}`
+    if (key === this.lastPageviewKey) return
+    this.lastPageviewKey = key
+
+    this.fanOut((t) => t.pageview(payload))
+  }
+
+  trackEvent(name: string, props: Record<string, unknown> = {}): void {
+    if (typeof window === 'undefined') return
+
+    this.fanOut((t) =>
+      t.event({
+        event_name: name,
+        pathname: window.location.pathname,
+        props,
+      }),
+    )
+  }
+
+  /**
+   * Attach (or clear) the authenticated user.
+   *
+   * Pass `null` on logout. A user id left attached after logout is a real
+   * privacy leak — the next anonymous session inherits it.
+   */
+  identify(userId: string | null): void {
+    this.fanOut((t) => t.identify?.(userId))
+  }
+
+  flush(final = false): void {
+    this.fanOut((t) => t.flush?.(final))
+  }
+
+  destroy(): void {
+    if (this.flushHandler) {
+      document.removeEventListener('visibilitychange', this.flushHandler)
+    }
+    if (this.pagehideHandler) {
+      window.removeEventListener('pagehide', this.pagehideHandler)
+    }
+    this.started = false
+  }
+
+  private registerFlushListeners(): void {
+    // visibilitychange -> hidden is the PRIMARY signal, and pagehide is the
+    // backstop.
+    //
+    // Deliberately NOT 'unload': it disqualifies the page from the bfcache
+    // entirely. And deliberately not 'beforeunload': also bfcache-hostile, and
+    // iOS Safari may never fire it at all — so a beforeunload-only flush loses
+    // every mobile Safari session.
+    this.flushHandler = () => {
+      if (document.visibilityState === 'hidden') this.flush(true)
+    }
+    this.pagehideHandler = () => this.flush(true)
+
+    document.addEventListener('visibilitychange', this.flushHandler)
+    window.addEventListener('pagehide', this.pagehideHandler)
+  }
+
+  private fanOut(fn: (t: AnalyticsTransport) => void): void {
+    for (const t of this.transports) {
+      try {
+        fn(t)
+      } catch (err) {
+        this.warn(`transport "${t.name}" threw`, err)
+      }
+    }
+  }
+
+  private warn(message: string, err?: unknown): void {
+    if (this.debug) console.warn(`[analytics] ${message}`, err)
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Framework-agnostic entry point. Zero React, zero Next.
+ *
+ * Import from here in a Vite/vanilla app, or anywhere you want the client
+ * without pulling React into the graph.
+ */
+
+export { AnalyticsClient } from './client'
+export type { AnalyticsEventPayload, AnalyticsOptions, AnalyticsTransport } from './types'
+
+/**
+ * The batched beacon transport. Also imported by @djangocfg/devtools — the
+ * unload-delivery rules (sendBeacon's silent-failure trap, the shared keepalive
+ * quota) are implemented ONCE, here, rather than re-derived per consumer.
+ */
+export { BeaconTransport } from './transport'
+export type { BeaconOptions } from './transport'
+
+export { djangocfg } from '../transports/djangocfg'
+export type { DjangoCfgTransportOptions } from '../transports/djangocfg'
+export { ga4 } from '../transports/ga4'
+export type { Ga4TransportOptions } from '../transports/ga4'

package/src/core/transport.ts

@@ -0,0 +1,124 @@
+/**
+ * The batched beacon transport. THE one place this logic exists.
+ *
+ * Owned by @djangocfg/analytics and imported by @djangocfg/devtools, so the
+ * unload-delivery rules below are implemented once rather than re-derived (and
+ * re-broken) per consumer. Zero React, zero UI, zero framework — safe to import
+ * from anywhere, including a vanilla capture hook.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE TRAP THIS EXISTS TO PREVENT
+ * ─────────────────────────────────────────────────────────────────────────────
+ * The obvious unload flush loses data SILENTLY:
+ *
+ *     navigator.sendBeacon(url, new Blob([json], { type: 'application/json' }))
+ *
+ * `application/json` is NOT a CORS-safelisted Content-Type, so the request
+ * leaves no-cors mode and triggers an OPTIONS preflight — which, during unload,
+ * usually cannot complete. The POST is never sent. `sendBeacon` still returns
+ * `true`, because true means "queued", not "delivered". No error, no exception,
+ * no retry. Verified in Chrome 149.
+ *
+ * The events you lose are the ones that mattered most: whatever crashed the page
+ * and caused the navigation away.
+ *
+ * Rules, all of which this module encodes:
+ *   1. Prefer SAME-ORIGIN ingest (Next rewrites / Vite proxy). Same-origin means
+ *      no CORS and therefore no preflight, ever. It also dodges ad blockers.
+ *   2. On unload, send `text/plain` — CORS-safelisted, so no preflight. The body
+ *      is still JSON; only the label differs. The server reads it with an
+ *      additive parser scoped to the ingest view.
+ *   3. CHECK sendBeacon's boolean return and fall back to fetch(keepalive).
+ *   4. Respect the 64KB keepalive quota, which is per-document and SHARED
+ *      between sendBeacon and fetch(keepalive).
+ */
+
+/** Stay under the shared 64KB per-document keepalive quota. */
+const KEEPALIVE_LIMIT = 60_000
+
+export interface BeaconOptions {
+  /** Where to POST. Relative keeps it same-origin — see rule 1. */
+  url: string
+
+  /**
+   * Called when the queue is drained. Receives the events being sent, and must
+   * return the request body. Lets each consumer keep its own payload shape.
+   */
+  serialize: (events: unknown[]) => string
+
+  /** Flush automatically once the queue reaches this size. */
+  batchSize?: number
+
+  /** Send cookies, so the server can attribute events to a signed-in user. */
+  credentials?: RequestCredentials
+}
+
+export class BeaconTransport {
+  private queue: unknown[] = []
+  private readonly url: string
+  private readonly serialize: (events: unknown[]) => string
+  private readonly batchSize: number
+  private readonly credentials: RequestCredentials
+
+  constructor(options: BeaconOptions) {
+    this.url = options.url
+    this.serialize = options.serialize
+    this.batchSize = options.batchSize ?? 25
+    this.credentials = options.credentials ?? 'include'
+  }
+
+  /** Queue an event, flushing automatically once the batch is full. */
+  push(event: unknown): void {
+    this.queue.push(event)
+    if (this.queue.length >= this.batchSize) this.flush(false)
+  }
+
+  /**
+   * Send what is queued.
+   *
+   * `final` must be true when the document is going away — it switches to a
+   * delivery mechanism that survives unload. Getting this wrong is the entire
+   * point of this module.
+   */
+  flush(final: boolean): void {
+    if (this.queue.length === 0) return
+
+    const events = this.queue.splice(0, this.batchSize)
+    const body = this.serialize(events)
+
+    if (final) {
+      // A raw string (not a typed Blob) sends as text/plain, which is
+      // CORS-safelisted — so no preflight, and it actually leaves the browser.
+      if (body.length < KEEPALIVE_LIMIT && navigator.sendBeacon?.(this.url, body)) {
+        return
+      }
+      // sendBeacon refused: over quota, or unavailable. keepalive is the
+      // documented fallback that also outlives the document.
+      void fetch(this.url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'text/plain' },
+        body,
+        keepalive: true,
+        credentials: this.credentials,
+      }).catch(() => {
+        // The page is dying. There is nothing useful left to do.
+      })
+      return
+    }
+
+    void fetch(this.url, {
+      method: 'POST',
+      // Not an unload flush, so the honest content type is fine.
+      headers: { 'Content-Type': 'application/json' },
+      body,
+      credentials: this.credentials,
+    }).catch(() => {
+      // Telemetry must never surface an error into the app it is measuring.
+    })
+  }
+
+  /** Number of events waiting to be sent. */
+  get pending(): number {
+    return this.queue.length
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,86 @@
+/**
+ * Core types. No React, no framework, no DOM assumptions beyond `window`.
+ */
+
+/** A single tracked event. `pageview` is the default and most common. */
+export interface AnalyticsEventPayload {
+  event_name: string
+
+  /** Raw URL path, e.g. `/en/blog/hello-world`. */
+  pathname: string
+
+  /**
+   * Templated route, e.g. `/[locale]/blog/[slug]`.
+   *
+   * Without this, `/en/pricing` and `/ru/pricing` fragment into two separate
+   * "pages" and the top-pages report is meaningless on a locale-prefixed site.
+   */
+  route?: string
+
+  /** Lifted out of the path into its own dimension, for the same reason. */
+  locale?: string
+
+  hostname?: string
+  page_title?: string
+  referrer?: string
+
+  utm_source?: string
+  utm_medium?: string
+  utm_campaign?: string
+  utm_content?: string
+  utm_term?: string
+
+  click_id?: string
+  click_id_param?: string
+
+  /** Arbitrary custom properties. Stored as jsonb server-side. */
+  props?: Record<string, unknown>
+}
+
+/**
+ * A destination for events.
+ *
+ * The whole point of the package: ONE route listener fans out to N transports.
+ * Before this, the GA4 layer owned its own route listener; adding a second
+ * destination would have meant a second listener, double-firing with a drifting
+ * taxonomy.
+ */
+export interface AnalyticsTransport {
+  readonly name: string
+
+  /** Called once, on init. Must not throw. */
+  init?(): void | Promise<void>
+
+  /** Record a pageview. */
+  pageview(event: AnalyticsEventPayload): void
+
+  /** Record a custom event. */
+  event(event: AnalyticsEventPayload): void
+
+  /** Attach an authenticated identity. Pass `null` on logout. */
+  identify?(userId: string | null): void
+
+  /**
+   * Send anything buffered. Called on visibilitychange->hidden and pagehide.
+   *
+   * `final` is true when the document is going away, which is when a transport
+   * must use a delivery mechanism that survives unload (sendBeacon /
+   * fetch keepalive) rather than a normal fetch.
+   */
+  flush?(final: boolean): void
+}
+
+export interface AnalyticsOptions {
+  transports: AnalyticsTransport[]
+
+  /**
+   * Track in development too.
+   *
+   * Defaults to TRUE, which reverses the old GA4 layer's behavior. That layer
+   * was `isProd`-gated, so it was silent in dev — you could not tell whether
+   * tracking worked until you shipped. Self-hosting removes the reason for that
+   * gate: your own dev traffic goes to your own database, which is arguably the
+   * entire point.
+   */
+  debug?: boolean
+}

package/src/events.ts

@@ -0,0 +1,60 @@
+/**
+ * Analytics Events Constants
+ *
+ * Predefined event names and categories for consistent tracking
+ * across the entire application.
+ */
+
+/**
+ * Event Categories
+ */
+export const AnalyticsCategory = {
+  AUTH: 'auth',
+  ERROR: 'error',
+  NAVIGATION: 'navigation',
+  ENGAGEMENT: 'engagement',
+  USER: 'user',
+} as const;
+
+/**
+ * Predefined Event Names
+ */
+export const AnalyticsEvent = {
+  // Auth Events
+  AUTH_OTP_REQUEST: 'auth_otp_request',
+  AUTH_OTP_VERIFY_SUCCESS: 'auth_otp_verify_success',
+  AUTH_OTP_VERIFY_FAIL: 'auth_otp_verify_fail',
+  AUTH_LOGIN_SUCCESS: 'auth_login_success',
+  AUTH_LOGOUT: 'auth_logout',
+  AUTH_SESSION_EXPIRED: 'auth_session_expired',
+  AUTH_TOKEN_REFRESH: 'auth_token_refresh',
+  AUTH_TOKEN_REFRESH_FAIL: 'auth_token_refresh_fail',
+
+  // OAuth Events
+  AUTH_OAUTH_START: 'auth_oauth_start',
+  AUTH_OAUTH_SUCCESS: 'auth_oauth_success',
+  AUTH_OAUTH_FAIL: 'auth_oauth_fail',
+
+  // Error Events
+  ERROR_BOUNDARY: 'error_boundary',
+  ERROR_API: 'error_api',
+  ERROR_VALIDATION: 'error_validation',
+  ERROR_NETWORK: 'error_network',
+
+  // Navigation Events
+  NAV_ADMIN_ENTER: 'nav_admin_enter',
+  NAV_DASHBOARD_ENTER: 'nav_dashboard_enter',
+  NAV_PAGE_VIEW: 'nav_page_view',
+
+  // Engagement Events
+  THEME_CHANGE: 'theme_change',
+  SIDEBAR_TOGGLE: 'sidebar_toggle',
+  MOBILE_MENU_OPEN: 'mobile_menu_open',
+
+  // User Events
+  USER_PROFILE_VIEW: 'user_profile_view',
+  USER_PROFILE_UPDATE: 'user_profile_update',
+} as const;
+
+export type AnalyticsCategoryType = typeof AnalyticsCategory[keyof typeof AnalyticsCategory];
+export type AnalyticsEventType = typeof AnalyticsEvent[keyof typeof AnalyticsEvent];

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @djangocfg/analytics
+ *
+ * One route listener, N transports.
+ *
+ * @example
+ * ```tsx
+ * <AnalyticsProvider
+ *   transports={[djangocfg({ site: 'example.com' }), ga4({ trackingId })]}
+ *   userId={user?.id}
+ * >
+ *   <PageviewTracker route="/[locale]/blog/[slug]" locale={locale} />
+ *   {children}
+ * </AnalyticsProvider>
+ * ```
+ */
+
+export { AnalyticsClient } from './core/client'
+export type {
+  AnalyticsEventPayload,
+  AnalyticsOptions,
+  AnalyticsTransport,
+} from './core/types'
+
+export { djangocfg } from './transports/djangocfg'
+export type { DjangoCfgTransportOptions } from './transports/djangocfg'
+export { ga4 } from './transports/ga4'
+export type { Ga4TransportOptions } from './transports/ga4'
+
+export { AnalyticsProvider, useAnalytics, useAnalyticsClient } from './react/context'
+export type { AnalyticsProviderProps } from './react/context'
+
+export { PageviewTracker } from './next/PageviewTracker'
+export type { PageviewTrackerProps } from './next/PageviewTracker'
+
+export { AnalyticsCategory, AnalyticsEvent } from './events'
+export type { AnalyticsCategoryType, AnalyticsEventType } from './events'

package/src/next/PageviewTracker.tsx

@@ -0,0 +1,93 @@
+'use client'
+
+/**
+ * Next.js App Router pageview tracking.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THE <Suspense> BOUNDARY IS MANDATORY
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `useSearchParams()` without a Suspense boundary above it de-opts the ENTIRE
+ * page into client-side rendering. Not this component — the whole page. It is
+ * silent, and it is a repo-wide performance regression that shows up as a
+ * mysteriously worse Lighthouse score weeks later.
+ *
+ * `usePathname()` is exempt; only `useSearchParams()` triggers it.
+ * `@vercel/analytics` wraps its own tracker in Suspense for exactly this reason.
+ *
+ * So the inner component is never exported. The exported one is already wrapped.
+ */
+
+import { usePathname, useSearchParams } from 'next/navigation'
+import { Suspense, useEffect } from 'react'
+
+import { useAnalyticsClient } from '../react/context'
+
+export interface PageviewTrackerProps {
+  /**
+   * The templated route, e.g. `/[locale]/blog/[slug]`.
+   *
+   * Next does not expose this to client components, so the app must pass it.
+   * Without it, `/en/pricing` and `/ru/pricing` are counted as two different
+   * pages, which makes the top-pages report useless on a locale-prefixed site.
+   */
+  route?: string
+
+  /** Current locale, lifted into its own dimension rather than fused into the path. */
+  locale?: string
+}
+
+function Tracker({ route, locale }: PageviewTrackerProps) {
+  const pathname = usePathname()
+  const searchParams = useSearchParams()
+  const client = useAnalyticsClient()
+
+  useEffect(() => {
+    if (!client || !pathname) return
+
+    const search = searchParams?.toString() ?? ''
+    const params = new URLSearchParams(search)
+
+    client.trackPageview({
+      event_name: 'pageview',
+      pathname,
+      route,
+      locale,
+      hostname: window.location.hostname,
+      page_title: document.title,
+      // Only the FIRST pageview of a visit has a meaningful referrer; on
+      // subsequent client-side navigations document.referrer still holds the
+      // original external referrer, which is what we want for attribution.
+      referrer: document.referrer,
+      utm_source: params.get('utm_source') ?? undefined,
+      utm_medium: params.get('utm_medium') ?? undefined,
+      utm_campaign: params.get('utm_campaign') ?? undefined,
+      utm_content: params.get('utm_content') ?? undefined,
+      utm_term: params.get('utm_term') ?? undefined,
+      ...extractClickId(params),
+      // `search` feeds the client's dedup key, so ?page=2 counts as a new
+      // pageview while router.refresh() does not.
+      props: { search: search ? `?${search}` : '' },
+    })
+  }, [client, pathname, searchParams, route, locale])
+
+  return null
+}
+
+/** Known ad-platform click ids. One column pair server-side, not six. */
+const CLICK_ID_PARAMS = ['gclid', 'fbclid', 'msclkid', 'ttclid', 'li_fat_id', 'twclid']
+
+function extractClickId(params: URLSearchParams) {
+  for (const key of CLICK_ID_PARAMS) {
+    const value = params.get(key)
+    if (value) return { click_id: value, click_id_param: key }
+  }
+  return {}
+}
+
+export function PageviewTracker(props: PageviewTrackerProps) {
+  return (
+    <Suspense fallback={null}>
+      <Tracker {...props} />
+    </Suspense>
+  )
+}

package/src/react/context.tsx

@@ -0,0 +1,79 @@
+'use client'
+
+/**
+ * React bindings. Router-agnostic: the provider owns the client, and a router
+ * adapter (see ../next) feeds it location changes.
+ */
+
+import { createContext, useContext, useEffect, useMemo, useRef, type ReactNode } from 'react'
+
+import { AnalyticsClient } from '../core/client'
+import type { AnalyticsOptions } from '../core/types'
+
+const AnalyticsContext = createContext<AnalyticsClient | null>(null)
+
+export interface AnalyticsProviderProps extends AnalyticsOptions {
+  children: ReactNode
+
+  /**
+   * The signed-in user's id, or null/undefined when anonymous.
+   *
+   * MUST be an opaque id — never an email. And it MUST go back to null on
+   * logout: a stale user_id attached to the next anonymous session is a real
+   * privacy leak, not a cosmetic bug.
+   */
+  userId?: string | null
+}
+
+export function AnalyticsProvider({
+  children,
+  transports,
+  debug,
+  userId,
+}: AnalyticsProviderProps) {
+  // The client must survive React 19 StrictMode's dev remount, or its pageview
+  // dedup key would reset and every pageview would fire twice.
+  const clientRef = useRef<AnalyticsClient | null>(null)
+  if (clientRef.current === null) {
+    clientRef.current = new AnalyticsClient({ transports, debug })
+  }
+  const client = clientRef.current
+
+  useEffect(() => {
+    void client.init()
+    return () => client.destroy()
+  }, [client])
+
+  useEffect(() => {
+    // Inside an effect, never during render: reading auth state during render
+    // produces a server/client hydration mismatch.
+    client.identify(userId ?? null)
+  }, [client, userId])
+
+  return <AnalyticsContext.Provider value={client}>{children}</AnalyticsContext.Provider>
+}
+
+/**
+ * Track custom events from a component.
+ *
+ * Returns a stable object, so it is safe in a dependency array.
+ */
+export function useAnalytics() {
+  const client = useContext(AnalyticsContext)
+
+  return useMemo(
+    () => ({
+      event: (name: string, props?: Record<string, unknown>) => client?.trackEvent(name, props),
+      identify: (userId: string | null) => client?.identify(userId),
+      flush: () => client?.flush(false),
+      /** False when no AnalyticsProvider is mounted above this component. */
+      isEnabled: client !== null,
+    }),
+    [client],
+  )
+}
+
+/** Internal: the router adapters need the raw client. */
+export function useAnalyticsClient(): AnalyticsClient | null {
+  return useContext(AnalyticsContext)
+}

package/src/transports/djangocfg.ts

@@ -0,0 +1,64 @@
+/**
+ * First-party transport: POST to django-cfg's /cfg/analytics/<path>/.
+ *
+ * The delivery rules (unload flush, sendBeacon's silent-failure trap, the shared
+ * keepalive quota) live in ../core/transport.ts — ONE implementation, shared with
+ * @djangocfg/devtools. Do not re-implement them here.
+ */
+
+import { BeaconTransport } from '../core/transport'
+import type { AnalyticsEventPayload, AnalyticsTransport } from '../core/types'
+
+export interface DjangoCfgTransportOptions {
+  /**
+   * Where to POST. Defaults to `${NEXT_PUBLIC_API_URL}/cfg/analytics/collect/`,
+   * so it stays relative same-origin when the API shares the frontend's origin
+   * (empty base — no CORS, no preflight, dodges ad blockers) and becomes
+   * absolute on a split-domain deploy where the API lives elsewhere.
+   *
+   * Configurable because filter lists (EasyPrivacy et al.) match on PATH, not
+   * domain: a fixed path shipped in an open-source package gets blocked once,
+   * for everyone.
+   */
+  ingestPath?: string
+
+  /** Which registered AnalyticsSite these events belong to. */
+  site?: string
+
+  /** Max events per request. The server caps at 25. */
+  batchSize?: number
+}
+
+export function djangocfg(options: DjangoCfgTransportOptions = {}): AnalyticsTransport {
+  const apiBase = (process.env.NEXT_PUBLIC_API_URL ?? '').replace(/\/+$/, '')
+  const ingestPath = options.ingestPath ?? `${apiBase}/cfg/analytics/collect/`
+  const site = options.site ?? (typeof window !== 'undefined' ? window.location.hostname : '')
+
+  let userId: string | null = null
+
+  const beacon = new BeaconTransport({
+    url: ingestPath,
+    batchSize: Math.min(options.batchSize ?? 25, 25),
+    // credentials:'include' is what lets the server resolve request.user and
+    // attribute the event to a signed-in account — the differentiator.
+    credentials: 'include',
+    serialize: (events) => JSON.stringify({ site, events }),
+  })
+
+  const enqueue = (event: AnalyticsEventPayload) => {
+    beacon.push({
+      ...event,
+      props: { ...event.props, ...(userId ? { user_id: userId } : {}) },
+    })
+  }
+
+  return {
+    name: 'djangocfg',
+    pageview: (event) => enqueue({ ...event, event_name: 'pageview' }),
+    event: (event) => enqueue(event),
+    identify: (id) => {
+      userId = id
+    },
+    flush: (final) => beacon.flush(final),
+  }
+}

package/src/transports/ga4.ts

@@ -0,0 +1,59 @@
+/**
+ * Google Analytics 4 transport.
+ *
+ * This is the old `packages/layouts/src/snippets/Analytics` layer, turned into a
+ * transport. It kept its own route listener; now it is one destination among N,
+ * fed by the single listener in core/client.ts. Two listeners would double-fire
+ * with drifting taxonomies.
+ *
+ * `react-ga4` is loaded LAZILY, so a project that does not pass a GA4 tracking
+ * id never pays for the library at all.
+ *
+ * Behavior change worth knowing about: the old layer hard-gated on `isProd`, so
+ * it was completely silent in development. That gate is not reproduced here —
+ * whether to track in dev is now the caller's decision (`debug` on the client),
+ * not a hardcoded rule. GA4 still filters its own internal traffic server-side.
+ */
+
+import type { AnalyticsTransport } from '../core/types'
+
+export interface Ga4TransportOptions {
+  /** Measurement ID, e.g. `G-XXXXXXXXXX`. */
+  trackingId: string
+}
+
+export function ga4(options: Ga4TransportOptions): AnalyticsTransport {
+  const { trackingId } = options
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let ReactGA: any = null
+
+  return {
+    name: 'ga4',
+
+    async init() {
+      if (!trackingId) return
+      const mod = await import('react-ga4')
+      ReactGA = mod.default ?? mod
+      ReactGA.initialize(trackingId)
+    },
+
+    pageview(event) {
+      if (!ReactGA) return
+      const search = (event.props?.search as string) || ''
+      ReactGA.send({ hitType: 'pageview', page: `${event.pathname}${search}` })
+    },
+
+    event(event) {
+      if (!ReactGA) return
+      ReactGA.event(event.event_name, event.props ?? {})
+    },
+
+    identify(userId) {
+      if (!ReactGA) return
+      // Clearing must send an explicit null, not an omission — GA4 keeps the
+      // previous user_id otherwise, and it would bleed into the next session.
+      ReactGA.set({ user_id: userId })
+    },
+  }
+}