export declare const analyticsMdxTemplate = "---\ntitle: \"Analytics\"\ndescription: \"Add PostHog analytics to your documentation site with an analytics.json file for both client-side and server-side tracking.\"\ndate: \"2026-02-24\"\ncategory: \"AI & Integrations\"\ncategoryOrder: 3\norder: 3\n---\n# Analytics\n\nTrack how users interact with your documentation using PostHog. Doccupine captures page views in two layers out of the box - in the browser and on the server - so readers running ad blockers are still counted. Browser traffic is proxied through your own domain rather than going to PostHog directly.\n\n## analytics.json\n\nPlace an `analytics.json` at your project root (the same directory where you execute `npx doccupine`).\n\n```json\n{\n  \"provider\": \"posthog\",\n  \"posthog\": {\n    \"key\": \"phc_your_project_api_key\",\n    \"host\": \"https://us.i.posthog.com\"\n  }\n}\n```\n\n## Fields\n\n- **provider**: The analytics provider to use. Currently only `\"posthog\"` is supported.\n- **posthog.key**: Your PostHog project API key. You can find this in your PostHog project settings under \"Project API Key\". This is a public identifier - it is safe to commit to version control.\n- **posthog.host**: The PostHog ingestion endpoint. Use `https://us.i.posthog.com` for US Cloud or `https://eu.i.posthog.com` for EU Cloud. If you self-host PostHog, use your instance URL.\n\n<Callout type=\"note\">\n  The PostHog project API key is a public identifier used to send events. It is not a secret and is safe to include in your repository.\n</Callout>\n\n## What gets tracked\n\nWhen `analytics.json` is configured, Doccupine enables two layers of tracking:\n\n### Client-side\n\n- **Page views**: Captured on client-side (soft) navigations using Next.js router hooks. The initial page load is counted by the server instead, so one view is never counted twice.\n- **Page leave**: Automatically captured when a user navigates away from a page.\n\n### Server-side\n\n- **Page views**: Captured in middleware on document requests - the initial load of a page. Requests behind client-side navigations carry an `RSC` header and are skipped, because the browser already counts those.\n- **Request metadata**: URL, pathname, host, referrer, and user agent are sent with each event.\n- **Smart filtering**: API routes, internal Next.js routes, and prefetch requests are automatically excluded.\n- **Ad-blocked readers**: because this half runs on your server, readers who block PostHog in the browser are still counted.\n\n## Privacy proxy\n\nDoccupine routes **browser** analytics traffic through your documentation domain using Next.js rewrites. Instead of the browser talking to PostHog directly (which ad blockers intercept), requests go through `/ingest` on your own domain and are proxied on.\n\nThis means:\n\n- No third-party domains appear in the browser's network requests.\n- Ad blockers are less likely to interfere with tracking.\n- Your users' browsing data stays within your domain boundary before reaching PostHog.\n\nThe proxy destinations are derived automatically from the `host` field in your configuration.\n\n<Callout type=\"warning\">\n  The proxy covers browser traffic only. Server-side page views are sent from\n  your server straight to PostHog - that is exactly what lets them survive an\n  ad blocker.\n</Callout>\n\n## Cookies\n\nAn analytics-enabled site sets two first-party cookies:\n\n- `ph_<key>_posthog` - set by posthog-js, holding its anonymous distinct id and session.\n- `dcp_anon_id` - httpOnly, one year, set by the server so an ad-blocked reader (who never receives the posthog-js cookie) counts as one person instead of a new person on every request.\n\nBoth hold nothing but a random identifier. Whether they require a consent notice\nunder GDPR/ePrivacy depends on your jurisdiction and what you do with the data;\nthat call is yours.\n\n## Getting a PostHog key\n\n1. Sign up at [posthog.com](https://posthog.com) (free tier available).\n2. Create a new project.\n3. Go to **Project Settings** and copy the **Project API Key**.\n4. Paste it into your `analytics.json` as the `posthog.key` value.\n\n## Behavior\n\n- **Placement**: Put `analytics.json` in the project root alongside `config.json` and `theme.json`.\n- **Hot reload**: Changes to `analytics.json` are picked up automatically in watch mode. The layout, middleware, and Next.js config are regenerated.\n- **Graceful degradation**: If `analytics.json` is missing, empty, or has an invalid configuration, no tracking code runs. Your site works exactly the same without it.\n- **Dev server restart**: After adding or removing `analytics.json` for the first time, you may need to restart the Next.js dev server for proxy rewrites to take effect.\n\n<Callout type=\"warning\">\n  After adding `analytics.json` for the first time, restart the dev server so the proxy rewrites are picked up by Next.js.\n</Callout>\n\n## Regions\n\nPostHog offers two cloud regions. Set the `host` field accordingly:\n\n| Region   | Host                       |\n| -------- | -------------------------- |\n| US Cloud | `https://us.i.posthog.com` |\n| EU Cloud | `https://eu.i.posthog.com` |\n\nIf you omit the `host` field, it defaults to the US Cloud endpoint.\n\n## Example\n\n### Minimal configuration (US Cloud)\n\n```json\n{\n  \"provider\": \"posthog\",\n  \"posthog\": {\n    \"key\": \"phc_your_project_api_key\"\n  }\n}\n```\n\n### EU Cloud\n\n```json\n{\n  \"provider\": \"posthog\",\n  \"posthog\": {\n    \"key\": \"phc_your_project_api_key\",\n    \"host\": \"https://eu.i.posthog.com\"\n  }\n}\n```\n\n## Tips\n\n- **Start simple**: Add the config with just your key and verify events appear in your PostHog dashboard before customizing further.\n- **Check your dashboard**: After deploying, visit your PostHog project to confirm page view events are flowing in.\n- **Production only**: Consider adding `analytics.json` only in your production/deployment setup to avoid tracking local development traffic.";