Frequently Asked Questions

What changes have been made between the classic web SDK and new web SDK?
Beyond the aforementioned significant architectural changes, there are a few specific changes:
- The new SDK introduces a plugin framework allowing customers to add custom enhancements or modifications to their data
- identify will now extend a session
- Use of POST instead of pixel GET to support larger and more structured payloads
- Encoded payloads for fetch optimization
- Event retry logic to improve data quality
- Added local storage as a storage option to reduce cookie bloat
- Event autocapture within Shadow DOM
What browsers does the new web SDK support?
The new Heap web SDK is tested against all modern browsers, including mobile and desktop Chrome, mobile and desktop Safari, Firefox and Edge.
Can a site install both the new SDK alongside the classic Heap web SDK on the same site?
This is not currently supported. We recommend replacing the existing script with the new one to avoid any unexpected behavior.
Can a site downgrade back to the classic web SDK after upgrading to the new version?
Yes, set classicSDKCompatibility: true in the heap.load config object during testing to preserve backwards compatibility.
If you need to revert, simply change the Heap code snippet back to the classic version. We support a seamless migration between the new and classic SDK. Any state persisted as part with a given SDK will be properly ported over (i.e. event properties, session properties, user + session information).
How do you recommend installing and testing the new version?
We would generally recommend three options depending on risk tolerance level:
1. Install the new SDK directly on an existing site using an existing environment and project.
  1. This approach simply drops the new SDK into an existing workflow. If everything works as intended, data collection and any subsequent analysis should remain exactly the same.
2. Install the new SDK on a development or internal build of an existing site and create a new environment within an existing project.
  1. This is the more conservative approach and fully separates our the data collected from the new SDK but still allows you to compare it against existing data collection and ensure events, charts, and other analysis are working as expected
3. Install the new SDK on a development or internal build of an existing site and create a new environment and a new project.
  1. This is the most conservative approach that not only fully separates data collection, but also by creating a new project, requiring the re-creation of any events, charts, or other analysis objects you may want to use.
Does the visual labeler work with ShadowDOM?
If the visual labeler is open on a page with a ShadowDOM, it will only be able to select the shadow root element. In the interim, we recommend utilizing Live View or the Event Definitions page to define events attached to elements within a ShadowDOM.