Funnel beacon

How DriftGuard measures acquisition and activation on driftguard.org — first-party events, no third-party marketing pixels on docs or trial flows.

Rollout status: Ingest (#213) and client beacon (web/funnel-beacon.js, #230) are live on /start, docs shell, and signup flows. Daily rollups and GET /internal/funnel-metrics ship with CP-5.6c/d (#218, #229). Wizard step micro-events remain CP-5.6b.1.

Why a first-party beacon

Correlate docs traffic → trial → first watch without exposing PII to ad networks
Same event schema for browser, server hooks, and future CI/MCP sources
Rate-limited public ingest — anonymous page_view does not require sign-in

Architecture

funnel-beacon.js (browser)
    │  dg_aid cookie + sendBeacon / fetch
    ▼
POST /api/funnel/events
    │  validate · PII strip · idempotent event_id
    ▼
funnel_events_hot (D1, 7d) + R2 archive + daily rollups (CP-5.6c)

Server-only lifecycle events (signed_up, first_watch, trial_claimed) are emitted from auth and watch routes — never accepted from the browser beacon.

Client-allowed events

Event	Typical stage	Use
`page_view`	`discover`	Marketing + docs page load
`docs_engaged`	`docs_engaged`	30s or scroll depth on docs
`cta_click`	`intent`	Primary buttons (trial, pricing)
`trial_intent`	`trial_intent`	`/start` wizard submit
`wizard_step_view`	varies	Wizard instrumentation (CP-5.6b.1)
`oauth_start`	`auth`	OAuth button click

Ingest API

POST https://driftguard.org/api/funnel/events
Content-Type: application/json

{
  "event_name": "page_view",
  "stage": "discover",
  "anonymous_id": "<dg_aid cookie>",
  "context": { "page": "/docs/guides/funnel-beacon" }
}

Responses: 202 accepted · 200 duplicate event_id · 400 validation error. Rate limit: 120 requests / hour / IP.

Privacy

The server strips forbidden keys (email, tokens, API keys, webhook URLs, raw repo paths) from properties and context. Do not send authenticated identifiers from the browser — use server hooks for signed_up and first_watch.

See also Security overview for hosted data boundaries.

Implementation reference

Engineering spec for web/funnel-beacon.js (cookie, transport, default hooks): internal repo doc docs/analytics/FUNNEL-BEACON.md. Full event catalog and D1 schema: docs/analytics/FUNNEL-ANALYTICS.md.

Analytics overview (CP-5.3 product metrics preview)
Adopt paths — funnels align to onboarding journeys
Security overview