---
description: PostHog analytics setup, env vars, and event taxonomy for the site.
load-when: Adding a new analytics event, debugging missing events, or rotating the PostHog project key.
---

# PostHog events

<scope>
Region: PostHog EU cloud (`https://eu.i.posthog.com`). Client-side only — no server-side capture in this project. Initialization lives in a custom theme module loaded via `clientModules` in `docusaurus.config.ts`.
</scope>

<conventions>
## Environment variables

| Var              | Purpose                                  |
| ---------------- | ---------------------------------------- |
| `POSTHOG_KEY`    | Project key (`phc_…`).                   |
| `POSTHOG_HOST`   | `https://eu.i.posthog.com` (EU region).  |

Lives in `.env.local` for dev. For production deploys, set both as Cloudflare Pages environment variables on the project.

## Event taxonomy

| Event                  | When                                            | Properties                                  |
| ---------------------- | ----------------------------------------------- | ------------------------------------------- |
| `$pageview`            | Auto on every navigation.                       | `$current_url`, `$pathname`, `$referrer`.   |
| `outbound_link_clicked`| Click on `a[href]` whose host is not gazperi.com| `href`, `text`, `pathname` (origin page).   |
| `internal_nav_clicked` | Click on internal `<a>` (Docusaurus `<Link>`).  | `to`, `text`, `pathname`.                   |
| `docs_entry_visited`   | Route change into `/educacao/*`.                | `slug`, `title`, `referrer_pathname`.       |

No personal data captured. No `identify()` call. Anonymous device-level analytics only.
</conventions>

<instructions>
<step n="1">
**Add a new event.** Edit the PostHog client module (`src/posthog/init.ts` or wherever the listeners live). Use `posthog.capture('event_name', {key: value})`. Keep names snake_case.
</step>

<step n="2">
**Test locally.** `npm run start`, open the page, trigger the action. Check PostHog Live Events panel. Events should appear within ~5s.
</step>

<step n="3">
**Add to dashboard.** In PostHog UI → "Site — starter" dashboard, add an Insight on the new event. Pin to dashboard.
</step>

<step n="4">
**Rotate the project key.** Generate a new key in PostHog. Update `.env.local` for dev and the Cloudflare Pages env var for production. Redeploy.
</step>
</instructions>

<antipattern>
- Capturing PII (email, full name) in event properties — violates LGPD posture for this project.
- Adding events without updating this file's taxonomy table — dashboard drifts from code.
- Using the US PostHog host (`app.posthog.com`) — project is EU-only.
</antipattern>