Note: You can use our snippet to start capturing events without installing our JavaScript library.
This doc refers to our posthog-js library.
Installation
You can either load the snippet as a script in your HTML:
JavaScript snippet Recommended
This is the simplest way to get PostHog up and running on your website, and only takes a few minutes to set-up.
Add to your website & app
Paste this snippet within the <head>
tags of your website - ideally just inside the closing </head>
tag - on all pages that you wish to track.
<script>!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);posthog.init('<ph_project_api_key>', {api_host: '<ph_instance_address>'})</script>
Be sure to replace <ph_project_api_key>
and <ph_instance_address>
with your project's values. (You can find the snippet pre-filled with this data in the PostHog app under Project / Settings. (Quick links if you use PostHog Cloud US or PostHog Cloud EU)
What this code does
After adding the snippet to your website, it will automatically start to:
- Capture
$pageview
events when a user visits a page - Track when users click on links or buttons
- Record videos of user sessions that you can play back (if you've enabled the Session recordings feature, which we highly recommend!)
Place the snippet in the <head>
tags of your website, ideally just above the closing </head>
tag. You will need to do this for all pages that you wish to track.
Or you can include it using npm, by doing either:
yarn add posthog-js
And then include it in your files:
import posthog from 'posthog-js'posthog.init('<ph_project_api_key>', { api_host: '<ph_instance_address>' })
If you don't want to send a bunch of test data while you're developing, you could do the following:
if (!window.location.host.includes('127.0.0.1') && !window.location.host.includes('localhost')) {posthog.init('<ph_project_api_key>', { api_host: '<ph_instance_address>' })}
If you're using React or Next.js, checkout our React SDK or Next.js integration.
Usage
Autocapture
When you call posthog.init
the PostHog JS library begins automatically capturing user events:
- pageviews, including the URL
- autocaptured events, such as any click, change of input, or submission associated with
a
,button
,form
,input
,select
,textarea
, andlabel
tags
Autocapture tracks a significant amount of user behavior without needing to instrument event capture. You can learn more about autocapture and how to configure it in our autocapture docs.
Track across marketing website & app
We recommend putting PostHog both on your homepage and your application if applicable. That means you'll be able to follow a user from the moment they come onto your website, all the way through signup and actually using your product.
PostHog automatically sets a cross-domain cookie, so if your website is
yourapp.com
and your app is onapp.yourapp.com
users will be followed when they go from one to the other.
Permitted domains
You can also configure "permitted domains" in your 'Project Settings'. These are domains where you'll be able to record user sessions and use the PostHog toolbar.
Send custom events with posthog.capture
This allows you to send more context than the default event info that PostHog captures whenever a user does something. In that case, you can send an event with any metadata you may wish to add.
posthog.capture('[event-name]', {property1: 'value', property2: 'another value'});
Setting user properties
To set user properties, include them when capturing an event:
posthog.capture('event_name',{$set: { name: 'Max Hedgehog' },$set_once: { initial_url: '/blog' },})
For more details on the difference between $set
and $set_once
, see our user properties docs.
Identifying users
We strongly recommend reading our docs on identifying users to better understand how to correctly use this method.
Using identify
, you can associate events with specific users. This enables you to gain full insights as to how they're using your product across different sessions, devices, and platforms.
posthog.identify('distinct_id', // required{ email: 'max@hedgehogmail.com', name: 'Max Hedgehog' } // $set, optional{ first_visited_url: '/blog' } // $set_once, optional);
Alias
Sometimes, you may want to assign multiple distinct IDs to a single user. This is helpful in scenarios where your primary distinct ID may be inaccessible. For example, if a distinct ID which is typically used on the frontend is not available in certain parts of your backend code. In this case, you can use alias
to assign another distinct ID to the same user.
We strongly recommend reading our docs on alias to best understand how to correctly use this method.
Reset after logout
If a user logs out, you should call reset
to unlink any future events made on that device with that user.
This is important if your users are sharing a computer, as otherwise all of those users are grouped together into a single user due to shared cookies between sessions. We strongly recommend you call reset
on logout even if you don't expect users to share a computer.
You can do that like so:
posthog.reset()
If you also want to reset device_id
, you can pass true
as a parameter:
posthog.reset(true)
One-page apps and page views
This JS snippet automatically sends pageview
events whenever it gets loaded. If you have a one-page app, that means it'll only send a pageview once, when your app loads.
To make sure any navigating a user does within your app gets captured, you can make a pageview call manually.
posthog.capture('$pageview')
This will automatically send the current URL.
Super Properties
Super Properties are properties associated with events that are set once and then sent with every capture
call, be it a $pageview, an autocaptured button click, or anything else.
They are set using posthog.register
, which takes a properties object as a parameter, and they persist across sessions.
For example, take a look at the following call:
posthog.register({'icecream pref': 'vanilla',team_id: 22,})
The call above ensures that every event sent by the user will include "icecream pref": "vanilla"
and "team_id": 22
. This way, if you filtered events by property using icecream_pref = vanilla
, it would display all events captured on that user after the posthog.register
call, since they all include the specified Super Property.
However, please note that this does not store properties against the User, only against their events. To store properties against the User object, you should use posthog.people.set
. More information on this can be found on the Sending User Information section.
Furthermore, if you register the same property multiple times, the next event will use the new value of that property. If you want to register a property only once (e.g. for ad campaign properties) you can use register_once
, like so:
posthog.register_once({'campaign source': 'twitter',})
Using register_once
will ensure that if a property is already set, it will not be set again. For example, if the user already has property "icecream pref": "vanilla"
, calling posthog.register_once({"icecream pref": "chocolate"})
will not update the property.
Removing stored Super Properties
Setting Super Properties creates a cookie on the client with the respective properties and their values. In order to stop sending a Super Property with events and remove the cookie, you can use posthog.unregister
, like so:
posthog.unregister('icecream pref')
This will remove the Super Property and subsequent events will not include it.
Opt users out
PostHog JS offers a function to opt users out based on your cookie settings definition (e.g. preferences set via a cookie banner).
This is also the suggested way to prevent capturing any data from the admin on the page, as well as from team members of your organization. A simple way to do this is to access the page as the admin (or any other user on your team you wish to stop capturing data on), and call posthog.opt_out_capturing();
on the developer console. You can also add this logic in you app and call it directly after an admin/team member logs in.
If you still wish to capture these events but want to create a distinction between users and team in PostHog, you should look into Cohorts.
With PostHog, you can:
Opt a user out:
posthog.opt_out_capturing()
See if a user has opted out:
posthog.has_opted_out_capturing()
Opt a user back in:
posthog.opt_in_capturing()
Feature Flags
PostHog v1.10.0 introduced Feature Flags, which allow you to safely deploy and roll back new features.
Here's how you can use them:
Do something when the feature flags load:
The argument
callback(flags: string[])
will be called when the feature flags are loaded.In case the flags are already loaded, it'll be called immediately. Additionally, it will also be called when the flags are re-loaded e.g. after calling
identify
orreloadFeatureFlags
.
posthog.onFeatureFlags(callback)
- Check if a feature is enabled:
posthog.isFeatureEnabled('keyword')
- By default, this function will send a
$feature_flag_called
event to your instance every time it's called so you're able to do analytics. You can disable this by passing the send_event property:
posthog.isFeatureEnabled('keyword', { send_event: false })
- Trigger a reload of the feature flags:
posthog.reloadFeatureFlags()
Note that reloadFeatureFlags()
does not send $feature_flag_called
events. These events are only sent when you query for a feature flag
using the getFeatureFlag()
or isFeatureEnabled()
functions.
Overriding server properties
Sometimes, you might want to evaluate feature flags using properties that haven't been ingested yet, or were set incorrectly earlier. You can do so by setting properties the flag depends on with these calls:
posthog.setPersonPropertiesForFlags({'property1': 'value', property2: 'value2'})
Note that these are set for the entire session. Successive calls are additive: all properties you set are combined together and sent for flag evaluation.
Whenever you set these properties, we also trigger a reload of feature flags to ensure we have the latest values. You can disable this by passing in the optional parameter for reloading:
posthog.setPersonPropertiesForFlags({'property1': 'value', property2: 'value2'}, false)
At any point, you can reset these properties by calling resetPersonPropertiesForFlags
:
posthog.resetPersonPropertiesForFlags()
The same holds for group properties:
// set properties for a groupposthog.setGroupPropertiesForFlags({'organization': {'property1': 'value', property2: 'value2'}})// reset properties for a given group:posthog.resetGroupPropertiesForFlags('organization')// reset properties for all groups:posthog.resetGroupPropertiesForFlags()
Note: You don't need to add the group names here, since these properties are automatically attached to the current group (set via
posthog.group()
). When you change the group, these properties are reset.
Automatic overrides
Whenever you call posthog.identify
with person properties, we automatically add these properties to flag evaluation calls to help determine the correct flag values. The same is true for when you call posthog.group()
.
Default overridden properties
By default, we always override some properties based on the user IP address.
The list of properties that this overrides:
- $geoip_city_name
- $geoip_country_name
- $geoip_country_code
- $geoip_continent_name
- $geoip_continent_code
- $geoip_postal_code
- $geoip_time_zone
This enables any geolocation-based flags to work without manually setting these properties.
Feature Flag Payloads
Payloads allow you to retrieve a value that is associated with the matched flag. The value can be a string, boolean, number, dictionary, or array. This allows for custom configurations based on values defined in the posthog app.
posthog.getFeatureFlagPayload('keyword')
Bootstrapping Flags
There is a delay between loading the library and feature flags becoming available to use. For some cases, like redirecting users to a different page based on a feature flag, this is extremely detrimental, as the flags load after the redirect logic occurs, thus never working.
In cases like these, where you want flags to be immediately available on page load, you can use the bootstrap library option.
This allows you to pass in a distinctID and feature flags during library initialisation, like so:
posthog.init('<ph_project_api_key>', {api_host: '<ph_instance_address>',bootstrap: {distinctID: 'your-anonymous-id',featureFlags: {'flag-1': true,'variant-flag': 'control','other-flag': false,},},})
To compute these flag values, use the corresponding getAllFlags
method in your server-side library. Note that bootstrapping flags requires server-side initialisation.
If the ID you're passing in is an identified ID (that is, an ID with which you've called posthog.identify()
elsewhere), you can also pass in the isIdentifiedID
bootstrap option, which ensures that this ID is treated as an identified ID in the library. This is helpful as it warns you when you try to do something wrong with this ID, like calling identify
again.
posthog.init('<ph_project_api_key>', {api_host: '<ph_instance_address>',bootstrap: {distinctID: 'your-identified-id',isIdentifiedID: true,featureFlags: {'flag-1': true,'variant-flag': 'control','other-flag': false,},},})
Note: Passing in a distinctID to bootstrap replaces any existing IDs, which means you may fail to connect any old anonymous user events with the logged in person, if your logic calls identify in the frontend immediately on login. In this case, you can omit passing in the distinctID.
Early Access Feature Management
Early access features give you the option to release feature flags that can be controlled by your users. More information
posthog.getEarlyAccessFeatures((previewItemData) => {// do something with early access feature})
posthog.updateEarlyAccessFeatureEnrollment(flagKey, 'true')
Enriched analytics
You can send enriched analytics data for feature flags, which helps uncover replays where people interact with a flag, target people who've interacted with a feature, or build cohorts of people who've viewed a feature.
To enable this, you can either use our <PosthogFeature>
React component (which implements this for you), or implement it on your own if you're not using react.
To implement it on your own, there are 3 things you need to do:
- Whenever a feature is viewed, send the
$feature_view
event with the propertyfeature_flag
set to the name of the flag.
posthog.capture('$feature_view', { feature_flag: flag })
- Whenever someone interacts with a feature, send the
$feature_interaction
event with the propertyfeature_flag
set to the name of the flag. - At the same time, set the person property
$feature_interaction/<flag-key>
to true. Here's a code example.
posthog.capture('$feature_interaction', { feature_flag: flag, $set: { [`$feature_interaction/${flag}`]: true } })
Here's a code example for the entire React component.
Group analytics
Group analytics allows you to associate the events for that person's session with a group (e.g. teams, organizations, etc.). Read the Group Analytics guide for more information.
Note: This is a paid feature and is not available on the open-source or free cloud plan. Learn more here.
- Associate the events for this session with a group
posthog.group('company', '42dlsfj23f')posthog.capture('upgraded plan') // this event is associated with company ID `42dlsfj23f`
- Associate the events for this session with a group AND update the properties of that group
posthog.group('company', '42dlsfj23f', {name: 'Awesome Inc.',employees: 11,})
The name
is a special property which is used in the PostHog UI for the name of the Group. If you don't specify a name
property, the group ID will be used instead.
Handling logging out
When the user logs out it's important to call posthog.reset()
to avoid new events being registered under the previously active group.
Integrating groups with feature flags
If you have updated tracking, you can use group-based feature flags as normal.
if (posthog.isFeatureEnabled('new-groups-feature')) {// do something}
To check flag status for a different group, first switch the active group by calling posthog.group()
.
Persistence
In order for PostHog to work optimally, we require storing a small amount of information about the user on the user's browser. This ensures that if the user navigates away, and comes back to your site at a later time, we will still identify them properly. We store the following information in the user's browser:
- User's 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 a cookie
, which means that PostHog will still be able to identify your users even across subdomains. By default, this cookie is set to expire after 365
days.
If you would like to change how PostHog stores this information, you can do so with the persistence
parameter.
persistence: "cookie"
(default). Everything is stored in a cookie.persistence: "localStorage+cookie"
. User's distinct ID is stored in a cookie and everything else is stored in the browser's localStorage.persistence: "localStorage"
. Everything is stored in localStorage.persistence: "memory"
. Stores in page memory, which means data is only persisted for the duration of the page view.
As a note, 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
.
Note: Please be aware that localStorage can't be used across subdomains. If you have multiple sites on the same domain, you may want to consider the
cookie
option or make sure to set all super properties across each subdomain.
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.
Warning: Remember to call posthog.identify
every time your app loads or every page refresh will be treated as a different user.
Config
When calling posthog.init
, there are various configuration options you can set in addition to loaded
and api_host
.
To configure these options, pass them as an object to the posthog.init
call, like so:
posthog.init('<ph_project_api_key>', {api_host: '<ph_instance_address>',loaded: function (posthog) {posthog.identify('[user unique id]')},autocapture: false,// ... more options})
There are multiple different configuration options, most of which you do not have to ever worry about. For brevity, only the most relevant ones are used here. However you can view all the configuration options in posthog-core.js.
Some of the most relevant options are:
Attribute | Description |
---|---|
api_host Type: String Default: https://app.posthog.com | URL of your PostHog instance. |
ui_host Type: String Default: undefined | If using a reverse proxy for api_host then this should be the actual PostHog app URL (e.g. app.posthog.com) |
autocapture Type: Boolean Default: true | Determines if PostHog should autocapture events. This setting does not affect capturing pageview events (see capture_pageview ). |
bootstrap Type: Object Default: {} | An object containing the distinctID , isIdentifiedID , and featureFlags keys, where distinctID is a string, and featureFlags is an object of key-value pairs |
capture_pageview Type: Boolean Default: true | Determines if PostHog should automatically capture pageview events. |
capture_pageleave Type: Boolean Default: true | Determines if PostHog should automatically capture pageleave events. |
cross_subdomain_cookie Type: Boolean Default: true | Determines if cookie should be set on the top level domain (example.com). If PostHog-js is loaded on a subdomain (test.example.com), and cross_subdomain_cookie is set to false, it'll set the cookie on the subdomain only (test.example.com). |
disable_persistence Type: Boolean Default: false | Disable persisting user data across pages. This will disable cookies, session storage and local storage. |
disable_session_recording Type: Boolean Default: false | Determines if users should be opted out of session recording. |
enable_recording_console_log Type: Boolean Default: false | Determines if console logs should be recorded as part of the session recording. More information. |
loaded Type: Function Default: function () {} | A function to be called once the PostHog scripts have loaded successfully. |
mask_all_text Type: Boolean Default: false | Prevent PostHog autocapture from capturing any text from your elements. |
mask_all_element_attributes Type: Boolean Default: false | Prevent PostHog autocapture from capturing any attributes from your elements. |
opt_out_capturing_by_default Type: Boolean Default: false | Determines if users should be opted out of PostHog tracking by default, requiring additional logic to opt them into capturing by calling posthog.opt_in_capturing . |
persistence Type: localStorage or cookie or memory or localStorage+cookie Default: cookie | Determines how PostHog stores information about the user. See persistence for details. |
property_blacklist Type: Array Default: [] | A list of properties that should never be sent with capture calls. |
sanitize_properties Type: Function Default: null | A function that allows you to sanitize or modify the properties that get sent. Example: sanitize_properties: function(properties, event) { if(properties['$ip']) { properties['$ip'] = null } return properties } |
session_recording Type: Object Default: See here. | Configuration options for recordings. More details found here |
xhr_headers Type: Object Default: {} | Any additional headers you wish to pass with the XHR requests to the PostHog API. |
Advanced configuration
In this section we describe some additional details on advanced configuration available.
Attribute | Description |
---|---|
advanced_disable_decide Type: Boolean Default: false | Will completely disable the /decide endpoint request (and features that rely on it). More details below. |
secure_cookie Type: Boolean Default: false | If this is true , PostHog cookies will be marked as secure, meaning they will only be transmitted over HTTPS. |
custom_campaign_params Type: Array Default: [] | List of query params to be automatically captured (see UTM Segmentation ) |
These are features for advanced users and may lead to unintended side effects if not reviewed carefully. If you are unsure about something, just reach out.
Disable /decide
endpoint
This feature was introduced in posthog-js 1.10.0. Previously, disabling autocapture would inherently disable the /decide endpoint altogether. This meant that disabling autocapture would inadvertenly turn off session recording, feature flags, compression and the toolbar too.
One of the very first things the PostHog library does when init()
is called is make a request to the /decide
endpoint on PostHog's backend. This endpoint contains information on how to run the PostHog library so events are properly received in the backend. This endpoint is required to run most features of the library (detailed below). However, if you're not using any of the described features, you may wish to turn off the call completely to avoid an extra request and reduce resource usage on both the client and the server.
The /decide
endpoint can be disabled by setting advanced_disable_decide = true
in PostHog config.
Resources dependent on /decide
These are features/resources that will be fully disabled when the /decide endpoint is disabled.
- Autocapture. The
/decide
endpoint contains information on whether autocapture should be enabled or not (apart from local configuration). - Session recording. The endpoint contains information on where to send relevant session recording events.
- Compression. The endpoint contains information on what compression methods are supported on the backend (e.g. LZ64, gzip) for event payloads.
- Feature flags. The endpoint contains the feature flags enabled for the current person.
- Toolbar. The endpoint contains authentication information and other toolbar capabilities information required to run it.
Any custom event capturing (posthog.capture
), $identify
, $set
, $set_once
and basically any other calls not detailed above will work as expected when /decide
is disabled.
Debugging
In your dev console you can run posthog.debug()
. This will enable debugging, easily allowing you to see all data that is being sent to PostHog.
Development
For instructions on how to run posthog-js
locally and setup your development environment, please checkout the README on the posthog-js repository.