---
name: analytics-wiring
description: When a page or stack needs analytics instrumentation - event tracking, conversion goals, funnel events, consent banners. Triggers - "analytics setup", "GA4", "Plausible", "PostHog", "track conversions", "event tracking", "set up tracking", "conversion goals", "consent banner", "cookie consent". Wires Plausible by default (privacy-first), GA4 if the operator insists, PostHog if event-tracking funnels need it. Standardizes event names across the toolkit.
metadata:
version: 0.1.0
---
# Analytics Wiring
You instrument pages with analytics so the operator can measure what's converting. The default is **Plausible** (privacy-first, $9/mo, no cookie banner needed in most jurisdictions). GA4 is the fallback if a client insists. PostHog is the layer when funnels need event-level tracking.
## Standard event taxonomy
Every page in the toolkit fires a consistent set of events. Standardization matters — it lets the operator copy the same dashboards across every client.
| Event | When | Required props |
|---|---|---|
| `page_view` | Every page load (auto from analytics provider) | `page_path`, `page_title` |
| `cta_clicked` | Primary or transitional CTA clicked | `cta_id` (slug like `hero-primary`), `cta_label`, `cta_destination` |
| `lead_submitted` | Form submitted successfully | `form_id`, `form_type` (`contact`, `audit-request`, `lead-magnet`, `application`) |
| `call_booked` | Cal.com / SavvyCal booking confirmed | `booking_type`, `service` |
| `pricing_viewed` | Pricing block enters viewport | none |
| `funnel_step_advanced` | User advances in a multi-step funnel | `funnel_id`, `from_step`, `to_step` |
| `video_played` | VSL or demo video starts | `video_id`, `video_title` |
| `video_25/50/75/100` | Video progress milestones | `video_id`, `progress_pct` |
| `quiz_started` / `quiz_completed` | Quiz funnel | `quiz_id`, `result` (on completion) |
Don't deviate without a reason. Custom events are added to `references/event-taxonomy-extensions.md` and reviewed quarterly.
## Workflow
### Step 1 — load context
Read `.agents/agency-context.md` §13 (Tech / Domain Inventory). Determine which provider(s) are configured.
If §13 is empty or vague, ask via `AskUserQuestion`:
> "Which analytics setup?"
> - "Plausible (recommended — privacy-first, no cookie banner)"
> - "GA4 (operator client requirement)"
> - "PostHog (event-tracking funnel)"
> - "Combo: Plausible + PostHog (funnels)"
Persist the choice to §13.
### Step 2 — install the provider
For Plausible:
- Add the Plausible script to the `Layout` component:
```html
```
- Use the custom-events extension for our event taxonomy:
```html
```
- Verify install via Plausible's installation checker.
For GA4:
- Add the GA4 gtag script to Layout.
- Configure events via `gtag('event', '{event_name}', { ...props })`.
- Add a cookie consent banner (we ship one in `design-system/primitives/CookieBanner.tsx`).
For PostHog:
- Install the JS SDK: `npm i posthog-js`.
- Initialize in a client-only script in Layout:
```ts
import posthog from 'posthog-js';
if (typeof window !== 'undefined') {
posthog.init('{PUBLIC_POSTHOG_KEY}', { api_host: 'https://app.posthog.com' });
}
```
- Wire `posthog.capture('{event_name}', props)` to our event taxonomy.
### Step 3 — wire CTA tracking
Every CTA component (`Button` with `as="a"`, or ``) needs an `onClick` (or analytics-aware Link wrapper) that fires `cta_clicked`. The `Button` primitive in `design-system/primitives/Button.tsx` has this baked in via a `trackingId` prop.
```tsx
```
The Button's onClick fires the event with `cta_id="hero-primary", cta_label="Get my dental SEO audit", cta_destination="/audit"` automatically.
### Step 4 — wire form tracking
Every form (`