PostHog

Configure PostHog

Use the project token that starts with phc_, and the region of your PostHog project. This example waits for measurement permission before requesting the SDK, and turns off cookieless capture after a refusal.

npm install @c15t/integrations@alpha

pnpm add @c15t/integrations@alpha

yarn add @c15t/integrations@alpha

bun add @c15t/integrations@alpha

import { posthog } from '@c15t/integrations/posthog';

export const scripts = [
	posthog({
		id: 'phc_YOUR_PROJECT_TOKEN',
		region: 'eu',
		loadMode: 'after-consent',
		initOptions: { cookieless_mode: 'never' },
	}),
];

The helper initializes PostHog itself. Remove any posthog-js initializer, framework plugin or array snippet that also does, or follow use an existing PostHog SDK instead.

Register the scripts

Complete your framework quickstart first. Keep its Inth endpoint, policy, styles and consent UI. Remove the vendor's original script, SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in src/consent-scripts.ts. If your framework quickstart already has a scripts array, such as the one in c15t.config.ts in the Next.js guide, add the helper to that array instead of creating a second file. The scripts export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration point for your framework below. These are edits to that provider, not a second provider.

import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });

Options

Loading and revocation

posthog uses the measurement category. With the default cookieless_mode: 'on_reject', PostHog keeps capturing without cookies after a refusal. That mode needs cookieless server hashing turned on in your PostHog project; see PostHog's cookieless guide. Set cookieless_mode: 'never', as in the example, if a refusal must stop capture.

Turn off features you do not use

After array.js loads, PostHog reads your posthog.init options and the project's remote config, then decides which extra modules to download and whether to request /flags. Set a features switch to false for each feature your site does not use:

posthog({
	id: 'phc_YOUR_PROJECT_TOKEN',
	region: 'eu',
	loadMode: 'after-consent',
	features: {
		surveys: false,
		heatmaps: false,
		deadClicks: false,
		webVitals: false,
		featureFlags: false,
	},
});

Sizes are brotli-compressed, measured from posthog-js 1.436.1.

An unset switch adds nothing to posthog.init. For heatmaps, dead clicks, web vitals and feature flags, PostHog then follows the setting in your PostHog project. true sets the opposite value and overrides the project. For surveys and featureFlags, true is PostHog's own default, so it behaves the same as unset.

Surveys work differently. PostHog downloads surveys.js whenever the remote config includes a surveys value, even when surveys are off in the project. surveys: false is the only way to skip it.

initOptions wins over a switch that sets the same key. A capture_performance value in initOptions replaces the whole object that webVitals builds.

Avoid PostHog's option traps

These rules also apply when you pass PostHog options yourself, in initOptions or in your own posthog.init:

• Use advanced_disable_feature_flags: true to stop /flags, not advanced_disable_flags: true. The second also stops PostHog loading the remote config, so session replay never starts and other features fall back to local config.
• With feature flags off, surveys that target a feature flag never show. PostHog logs a warning about it. If you need those surveys, leave featureFlags unset and pass advanced_only_evaluate_survey_feature_flags: true instead. PostHog still requests /flags, but evaluates only survey flags.
• While heatmaps are on, in posthog.init or in the project, PostHog loads dead-clicks-autocapture.js whatever capture_dead_clicks says. Turn off both to skip it.
• capture_performance: false turns off web vitals and session replay network timing. { web_vitals: false }, which webVitals: false sets, leaves network timing to the project. capture_performance: true forces both on.

Product tours (product-tours.js, about 36 KB) and exception autocapture (exception-autocapture.js, about 6 KB) load only when the project turns them on. To keep them off whatever the project says, pass disable_product_tours: true or capture_exceptions: false in initOptions.

Guard your own capture calls

Events your code sends need their own permission check. The posthog global exists before the SDK loads, so its presence does not mean measurement is allowed:

export function trackSignupStarted(measurementAllowed: boolean) {
	if (!measurementAllowed) return;
	window.posthog?.capture('signup_started');
}

Pass the current measurement permission from your framework, for example useConsent('measurement') in React.

Use an existing PostHog SDK

If your app already initializes posthog-js, keep that setup and register a callback-only script instead of the helper. Initialize the SDK with opt_out_capturing_by_default: true and cookieless_mode: 'never' so it captures nothing before c15t reports a permission.

import type { Script, ScriptCallbackInfo } from 'c15t/modules/script-loader';

type PostHogConsentApi = {
	opt_in_capturing: () => unknown;
	opt_out_capturing: () => unknown;
};

export function posthogConsent(instance: PostHogConsentApi): Script {
	const sync = ({ hasConsent }: ScriptCallbackInfo) => {
		if (hasConsent) instance.opt_in_capturing();
		else instance.opt_out_capturing();
	};

	return {
		id: 'posthog-sdk-consent',
		category: 'measurement',
		callbackOnly: true,
		alwaysLoad: true,
		onBeforeLoad: sync,
		onConsentChange: sync,
	};
}

Add posthogConsent(posthog) to the scripts you register, passing your initialized SDK instance. callbackOnly means c15t inserts no script element. alwaysLoad makes onBeforeLoad run on the first page load even while measurement is denied, so the SDK is told to opt out. onConsentChange runs on every later change. This does not delay the SDK import or its first request. loadMode: 'disabled' is not a substitute, because it syncs nothing.

features belongs to the helper, so it does nothing here. To skip modules you do not use, pass the PostHog options from turn off features you do not use to your own posthog.init, for example disable_surveys: true.

Measure opt-in rate

If you run a banner experiment, the backend already counts visitors and choices per arm. To see the arm in PostHog as well, forward the onSurfaceShown and onChoiceRecorded callbacks, which carry experiment: { id, arm }. See banner experiments.

Verify PostHog

These checks assume loadMode: 'after-consent' from the example. After you allow measurement, array.js loads and capture requests to your API host follow. Trigger one guarded event and check that it is sent.

With loadMode: 'always', array.js loads before a choice instead. Check that no capture request is sent while measurement is denied, unless you chose cookieless capture.

If you turned features off, allow measurement and filter the DevTools Network panel by posthog. Reload the page. You should see array.js, the remote config and capture requests, but no /flags request with featureFlags: false and none of the modules you turned off, such as surveys.js or dead-clicks-autocapture.js.

Test in a private window with an opt-in policy. Open DevTools Network, disable the cache and filter by the vendor's domain:

1. Load the page. No request goes to the vendor before you choose.
2. Click Reject, then reload. There is still no vendor request.
3. Open Privacy settings and allow the helper's category. The vendor script loads without a page reload.
4. Turn the category off again and save. c15t reloads the page, and the new page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop code that already ran. The vendor's listeners, timers and queued events stay alive until the page unloads. If you set reloadOnConsentRevoked: false, stop the vendor yourself. Register a callback-only script whose onConsentChange calls the vendor's opt-out API, as shown in custom integrations, and check the permission before each of your own event calls. The reload does not delete cookies the vendor already set; see clear on revocation for your framework.

The helper sets vendor to its script ID, so once you declare that vendor a visitor can turn it off inside an allowed category. See vendor consent for your framework. The consent verification guide covers navigation, expiry and hosting checks.