Managing persistence and cookies

For PostHog to work optimally, we store a small amount of information about the user on the user's browser. This ensures we identify users properly if they navigate away from your site and come back later.

The information we store includes:

• Their distinct_id
• Session ID & Device ID
• Active & enabled feature flags
• Any super properties you have defined
• Some PostHog configuration options (e.g. whether session recording is enabled)

By default, we store all this information in both a cookie and localStorage, which means PostHog can identify your users across subdomains. By default, the name of the cookie PostHog sets is ph_<project_api_key>_posthog and it expires after 365 days.

If you want to change how PostHog stores this information, you can do so with the persistence configuration option:

• persistence: "localStorage+cookie" (default): Limited things are stored in the cookie such as the distinctID and the sessionID, and everything else in the browser's localStorage.

• persistence: "cookie" : Stores all data in a cookie.

• persistence: "localStorage": Stores everything in localStorage.

• persistence: "sessionStorage": Stores everything in sessionStorage.

• persistence: "memory": Stores everything in page memory, which means data is only persisted for the duration of the page view.

To change persistence values without reinitializing PostHog, you can use the posthog.set_config() method. This enables you to switch from memory to cookies to better comply with privacy regulations.

const handleCookieConsent = (consent) => {
  posthog.set_config({ persistence: consent === 'yes' ? 'localStorage+cookie' : 'memory' });
  localStorage.setItem('cookie_consent', consent);
};

Persistence caveats

• Be aware that localStorage and sessionStorage can't be used across subdomains. If you have multiple sites on the same domain, you may want to consider a cookie option or make sure to set all super properties across each subdomain.

• Due to the size limitation of cookies you may run into 431 Request Header Fields Too Large errors (e.g. if you have a lot of feature flags). In that case, use localStorage+cookie.

• If you don't want PostHog to store anything on the user's browser (e.g. if you want to rely on your own identification mechanism only or want completely anonymous users), you can set disable_persistence: true in PostHog's config. If you do this, remember to call posthog.identify every time your app loads. If you don't, every page refresh is treated as a new and different user.

• For browser extensions, use localStorage, sessionStorage, or memory. Each extension context may initialize its own PostHog instance. These contexts don't share storage so the instances don't know about each other. Since browser.storage and chrome.storage APIs are not supported for data persistence, you'll need to provide your own shared distinct_id during each initialization to ensure events are sent under the same identifier. See the browser extension documentation for more details.