An exciting new session replay and heatmap experience is coming to Heap! This upgrade is free for all existing session replay customers and includes several new features and enhancements:

• Mobile app session replay (new!)
• Improved replay data availability
• A more responsive and accurate replay experience
• ShadowDOM replay support

Upgrade Timeline

Starting in early September, you’ll start seeing banner notifications within the Heap application guiding you through the upgrade process. The upgrade retains all your existing session replay and privacy settings and takes just a few minutes to complete.

All accounts must upgrade by January 31, 2025. The upgrade can be completed any time between September and January 31, 2025. After this date, classic session replay collection will be automatically turned off, though all previously collected replays will remain accessible in Heap.

Upgrade Checklist

• Session replay is upgraded on a per-environment basis. If you have multiple environments with session replay enabled, you’ll need to upgrade each environment individually.
• The upgrade retains all your existing session replay and privacy settings and you will be able to modify them as part of the upgrade wizard process.
• All previously collected replays will remain available within Heap in accordance with your contracted replay retention period, regardless of whether they were collected with the new or classic session replay experience.
• If your site requires Content Security Policies (CSPs), these will need be updated to support the new session replay capture. Visit our developer documentation for information on what additional CSPs are required for session replay.
• If your site sits behind a firewall, you may need to configure your firewall settings to enable session replay.

Recommendations & Best Practices

1. Implement any technical changes that may be required on your site such as updating CSPs or configuring firewall settings prior to upgrading.
2. Upgrade lower environments such as Development or Staging prior to upgrading any Production environments.
3. If you do not have a lower environment with session replay previously configured to upgrade, you can start a new session replay installation in that environment to test the new experience.

The Automated Upgrade Process

The upgrade within the Heap app is a fully guided expereince. The process will retrieve any previously configured session replay settings, enable you to modify those settings, and then port those settings into the new replay experience. The automated upgrade process should only take a few seconds.

Follow the steps below to upgrade your current environment:

1. Click the Upgrade Now button in the upgrade banner from anywhere in the app.
2. Check the box to agree to the Supplemental Terms.
3. Click the Launch Set up button to get started and launch the upgrade wizard.
4. The upgrade wizard will then copy all your existing session replay settings and allow you to modify them. You will also be able to modify your settings at any time after upgrading. See this set up guide for more information on the available options.
5. Once you have finished the upgrade, a new card should appear in the Replays & Heatmaps page.

How to validate a successful upgrade

After you have completed the upgrade and turned on session replay capture, it should only take a few minutes for the new session replay javascript tag to load on your page and new replay recording data to begin collecting.

You can validate the new javascript tag is loading by opening your browser’s developer tools, navigating to your site, and searching for a js file loading from a request URL that looks like the following: https://t.contentsquare.net/uxa/#############.js

The # characters above will be replaced by a random assortment of alpha numeric characters unique to your environment.

In order to validate replays are recording, look for recording?rt network requests with a successful 200 status code. This indicates replay data is being captured into Heap.

With the javascript tag loading and replay data being captured, you should begin to see new replays available in the Heap UI within 30 minutes to an hour.

Frequently Asked Questions

Why is the upgrade happening?

As part of our commitment to provide our customers with the best product experience, we are transitioning from the previous version of our session replay technology to a new and improved experienced powered by Contentsquare! This new experience leverages Contentsquare’s industry-leading session replay technology and brings with it several exciting new features including session replay for mobile apps!

Will replays stop capturing during the upgrade?

Once session replay is upgraded in a Heap environment, the classic version of session replay is turned off, regardless of whether the upgraded session replay configuration turned on replay capture.

For this reason, we recommend only upgrading when you are absolutely sure you are ready to turn on replay capture. There will be a short period of time 5-15 minutes from when the new replay capture is turned on before it is loaded on the site. During this time, no session replays will be captured.

What will happen to previously collected session replays after a customer upgrades?

All previously collected replays will remain available within Heap in accordance with your contracted replay retention period, regardless of whether they were collected with the new or classic session replay experience.

What will happen to any saved Heatmap charts after the upgrade?

Any existing Heatmap charts will remain saved and available. Data presented in heatmaps will only load new heatmap data. This means depending on the timeframe of the heatmap query, the heatmap could return no data, partial data, or full data. Two examples scenarios:

• A heatmap querying the last 7 days will return no results on the day of the upgrade because it will only query new heatmap data and no data has been collected yet since the upgrade just happened.
• A heatmap querying the last 7 days will return limited results if querying 3 days after the upgrade because the heatmap will only be able to query 3 days of collected heatmap data to build the heatmap.

Can I downgrade / un-upgrade / go back after upgrading an environment?

Not within the Heap app. If there is an issue with the upgrade, reach out to Support who will work to resolve the issue and possibly temporarily revert the upgrade if necessary.