Session Recording

Session Recording allows you to record users navigating through your website and play back the individual sessions to watch how real users use your product.

Using Session Recording

Recordings can only be used with our JavaScript library and requires the feature to be enabled in PostHog's Project Settings (/project/settings). Once enabled, the JS library will start recording sessions by default.

Session Recording does not work if you send data using Segment's SDK as this data is not collected. If you use Segment, you may want to add the PostHog library too (make sure to only send regular event data from one source).

Recordings can be toggled on and off in the JS library by appropriately setting the config. Users who opt out of event capturing will not have their sessions recorded.

To watch recordings, you can either visit the 'Recordings' page or click on any data point in an insight and from the list of persons related to that data point. This is specially useful in funnels, where you can drill down and watch recordings of users who converted or dropped off.

When watching recordings, you can change the speed as well as select the option 'skip inactive' - this will skip chunks of the recording where the user was inactive on the page.

Ignoring sensitive elements

To avoid recording passwords or other sensitive information, the default PostHog settings do not capture any user input fields in recordings (the text is replaced by '*'s). This setting can be adjusted by using the recording configurations.

If your application displays sensitive user information outside of input fields, you need to update your codebase to prevent PostHog from capturing this information during session recordings.

To do so, you should add the CSS class name ph-no-capture to elements which should not be recorded. This will lead to the element being replaced with a block of the same size when you play back the recordings. Make sure everyone who watches recordings in your team is aware of this, so that they don't think your product is broken when something doesn't show up!

Recording configurations

There are some configurations that can be used to adjust how recordings are captured.

To configure these options, pass them to your posthog.init call along with your other posthog-js configurations. They go inside of the session_recording attribute, like so:

posthog.init('<ph_project_api_key>', {
    api_host: '<ph_instance_address>',
    session_recording: {
        inlineStylesheet: false
    }
    // ... other options
})

Console logs recording (beta)

PostHog can also capture console logs from your application. This is useful for debugging, providing extra context on what is happening in your users browser environment. As console logs can contain sensitive information we do not capture these logs automatically. You can enable this feature globally from your PostHog project settings page or client-side by setting enable_recording_console_log in our JavaScript library config to true.

Console logs will be recorded if either the project setting or the client-side config is set to true. If recordings overall are disabled then console logs will also not be recorded.

posthog.init('<ph_project_api_key>', {
    api_host: '<ph_instance_address>',
    // REMINDER: This is only needed if you aren't using the project settings config
    enable_recording_console_log: true 
    // ... other options
})

Further controls

If you want more granular controls, you can choose to enable session recording using feature flags. This enables you to control session recordings based on users with certain previous events/actions or properties (or just to capture a percentage of all sessions).

To do this set disable_session_recording in our JavaScript library config to true.

Then conditionally call the method posthog.startSessionRecording to enable it using the feature flag.

For example:

posthog.init('<ph_project_api_key>', {
    api_host: '<ph_instance_address>',
    disable_session_recording: true
    // ... other options
})
window.posthog.onFeatureFlags(function() {
    if (window.posthog.isFeatureEnabled("your-feature-flag")) {
        window.posthog.startSessionRecording()
    }
})

Equally you can stop the recording at any point via:

posthog.stopSessionRecording()

Recordings data retention

Depending on how your app or website is built, recordings can take a lot of disk space. To manage this, we have the following retention policy options in place.

PostHog Cloud & Clickhouse Self-hosted

By default, recordings are automatically deleted after 3 weeks. Old recordings are deleted with Clickhouse's Table TTL. If you're self-hosting, you can set your own retention policy by updating the RECORDINGS_TTL_WEEKS configuration on your instance settings page.

Please note, if your Clickhouse storage is nearing capacity, you'll want to temporarily increase your volume size before running the command above (even if you're decreasing the value). Otherwise, the command can hang.

Legacy Postgres Self-hosted

Recordings are kept indefinitely by default. You can set recordings to delete after a configurable number of days in the project settings page.

Preserving recordings

We're working towards a solution for archiving and preserving recordings data for future reference. You can follow up on this GitHub issue.

In order to simplify the archival process, since posthog-js 1.24.0, recording length is capped at 24 hours.

Troubleshooting

Having trouble with recordings? Below are some tips for getting past some common issues

My browser freezes / crashes when recordings are enabled

Some Cookie banners or "CMP"s modify the webpage in reaction to any changes to cookies, which can cause an infinite loop. If you are using a tool like this and experience the webpage becoming unresponsive or slow then try configuring posthog to use persistence: "localStorage+cookie". This will use localStorage for the majority of storage needs, bypassing the infinite loop issue sometimes caused by cookie management tools.

Recordings are not being captured

There are a few common reasons that you may not see recordings appear in your project.

Permitted domain setting

In your project settings page, there's a section for 'Authorized URLs'. This is the list of domains where posthog will capture recordings. You should make sure it's not too restrictive.

For example, you may have https://www.example.com in the list. This will stop PostHog from capturing recordings on https://example.com.

If no domains are set here, PostHog will capture recordings on all domains.

posthog-js configurations

If you had previously disabled session recordings, you may have set the disable_session_recording option to true in posthog-js.

To re-enable session recordings you want to either remove the disable_session_recording option or set it to false.

You can read more about posthog-js configurations here.

Content security policy

When recordings are enabled, postHog-js will fetch a recorder.js script from the PostHog server. (This is not included in the default posthog-js to minimize the default bundle size)

Depending on your content security policy, this script may be blocked. If you have a default-src, script-src, script-src-elem, or connect-src directive in your CSP, you may need to add https://app.posthog.com (or your host URL if you are self hosted) to your list.

If PostHog is being blocked by your content security policy, you should see an error message in your developer console with more details.

Ad/tracking blockers

Some ad/tracking blockers will block PostHog from fetching posthog-js. If you're testing your app locally, you may need to disable any ad/tracking blockers that you're running in your browser.

Website is not recording properly

If you're having issues with recordings not looking correct, there are a couple things to do.

Update posthog-js

We're always making improvements to the recordings feature, so you'll want to make sure that you're running the latest version of posthog-js on your website.

To check the version that you're using, you can run the following in your console:

window.posthog.LIB_VERSION

Report your specific issue

To report a specific problem, you can open a GitHub issue. To help us figure it out as quickly as possible, please include the following information:

• The URL of the page that you're trying to record
• The version of posthog that you're using
• The version of posthog-js that you're using
• Details about the specific issue with your recording (e.g. how it looks and how it should look)
• If you're on posthog-cloud, a link to the specific recording
• Any unique details about your website (e.g. the frameworks that you're using etc.)