Search docs

Type at least 3 characters to search

All pages

PostHog

PostHog is an optional web-only analytics integration. When configured, the standard JavaScript SDK captures pageviews, page leaves, and supported interactions through autocapture. Events carry the SDK's normal URL and referrer metadata. The SDK persists browser information and its anonymous identifier in local storage and cookies by default.

PostHog project settings and remote configuration control additional features such as session recording, surveys, feature flags, heatmaps, performance capture, and exception capture. Review those settings for the selected project before enabling the token.

You will leave with a public project token and a region. Leave the token empty to disable the integration completely.

During the agent-run setup, the agent inventories your PostHog organizations and projects. With a PostHog personal API management key supplied through a secure tool, it can create a project through the API and use the returned api_token. You handle PostHog login, organization choice, account authorization, and any approval the tool requires. A personal key starts with phx_; it is secret and must never go in an app environment variable or browser bundle.

  1. Choose or create a project

    Choose the EU or US organization that should receive the analytics. The agent reuses a project only after confirming its organization, region, and identity. If API access is unavailable, create the project in the PostHog dashboard and open its project settings.

    Copy the project's public project token. This is the api_token returned when a project is created, and it is designed to be sent by the browser.

  2. Set the web environment

    # apps/web/.env.local
VITE_POSTHOG_PROJECT_TOKEN=phc_...
VITE_POSTHOG_REGION=eu

    VITE_POSTHOG_REGION accepts eu or us and defaults to eu. It must match the region that owns the project. Both values are compiled into the web build, so changing either requires a rebuild.

  3. Verify the events

    Run or rebuild the web app, visit a page, navigate, and interact with the interface. Confirm that the expected pageview and autocapture events appear in PostHog, then check the project settings for any additional enabled features.

The proxy is already part of the web app

The browser sends PostHog requests to the same-origin /ffd-ph-gest path. The web server forwards static and configuration requests to the regional asset host and event requests to the regional ingestion host. You do not need a DNS record or a separate proxy deployment.

The proxy exists only when the project token is configured. The PostHog SDK is likewise not imported or initialized when the token is absent or blank.

The proxy strips cookies, authorization, referrer, and forwarded host, protocol, and port headers. In local development it replaces browser-supplied X-Forwarded-For with the request socket address. In production it preserves the hosting edge's X-Forwarded-For so PostHog can derive geography. Your edge must replace or sanitize any client-supplied value before forwarding it. A bare Node server exposed directly cannot provide trustworthy client geography with this portable proxy configuration.

Analytics traffic passes through the web service, so it consumes that host's request and bandwidth allowance as well as PostHog's ingestion allowance.

Optional features can raise those requirements. PostHog recommends accepting request bodies up to 64 MB when session recording is enabled. A host with a lower proxy limit may not support every project feature through this route.

The API has no error tracking

This integration is the web app's alone. apps/api reports to nothing: it writes structured JSON to stdout and stops there, so a deployed API's diagnostics live wherever your host keeps stdout. That is a decision rather than an omission, and docs/adr/0033-observability-is-pull-not-push.md records why, including the survey the alternatives lost.

If you want server-side error tracking, wire a purpose-built error tracker rather than extending this project. posthog-node would be the smaller change and is still the wrong shape, because it mixes operator diagnostics into a product analytics project. Either way the credential is a public write-only token, not a secret, and it belongs in apps/api with the rest of that app's configuration.

Turn analytics off

Remove VITE_POSTHOG_PROJECT_TOKEN or leave it empty, then rebuild the web app. The SDK and /ffd-ph-gest forwarding are disabled in that build.

Values you now hold

Value Goes in As
Public project token apps/web/.env.local VITE_POSTHOG_PROJECT_TOKEN, optional
eu or us apps/web/.env.local VITE_POSTHOG_REGION, defaults to eu

Updated