Skip to main content
Pre-release. This guide applies when the Integrations hub is enabled for your ABConvert account.
The Heap integration adds your visitors’ ABConvert test groups to Heap events so you can compare storefront behavior by test group.

​
When to use it

  • Compare clicks on the blue snowboard product page between Control and Variant A.
  • Find sessions containing an assignment to a specific test group.
  • Follow visitors in several running tests without overwriting one test’s tag with another.

​
When not to use it

  • For statistical significance and revenue results, use ABConvert’s reports.
  • For Shopify checkout or server-side order events, configure Heap’s separate Shopify integrations. Storefront tags do not automatically carry into those events.

​
How it works

ABConvert uses Heap already installed on your storefront. It does not install Heap, identify visitors, or change your consent settings. For each active test the visitor is assigned to, ABConvert adds an event property named abconvert_test_<test ID>. Its value is the test group index as a string. For example, abconvert_test_49603: "1" tags subsequent Heap events with test group 1 of test 49603. ABConvert also sends abconvert_assignment once per test group per page load: Returning visits send the assignment again. The event count is not a count of unique visitors or unique test entries. Preview and manually forced QA assignments are excluded. Heap persists event properties across visits. On a later page where the integration and ABConvert browser SDK run, ABConvert removes its saved properties for tests no longer assigned to the visitor. It leaves your other Heap properties alone. Events captured before tagging or cleanup may still have missing or older tags.

​
Setup

1

Install Heap on your storefront

Follow Heap’s web installation guide. Keep your existing consent controls in place. No Heap API key is needed in ABConvert.
2

Enable Heap in ABConvert

Open Integrations, find Heap under Analytics & Session, and enable it.
3

Verify in Heap

Visit a storefront page with a running test using a normal visitor session. Find abconvert_assignment in your Heap project and check its test ID and test group. Then interact with the page and verify that subsequent events include abconvert_test_<test ID>.Use the assignment event and its properties in Heap’s event or session filters. Session replay must be available in your Heap project to inspect recordings. Called or queued in ABConvert confirms a call to Heap’s SDK, not receipt in your Heap project.

​
Common mistakes

  • Counting assignment events as unique exposures. A new page sends another event. Use distinct visitors or sessions for your comparison.
  • Expecting every first pageview to have a tag. Heap may capture the pageview before ABConvert knows the visitor’s assignment. Check subsequent interactions too.
  • Expecting disabling to erase past tags. Disabling stops new calls. Previously saved Heap properties can remain; remove only the relevant abconvert_test_<test ID> properties with Heap’s removeEventProperty API if you need to clear them.

​
FAQ

ABConvert adds persistent properties for up to 12 concurrent tests, using less than 2 KB of Heap’s shared 4 KB event-property allowance. Your own properties use that allowance too. Additional tests still send assignment events. Test IDs must contain up to 128 letters, digits, underscores, or hyphens to receive a persistent property. Event text is limited to 1,023 characters per field.
Cleanup history is saved in local storage on each storefront origin. Clearing that storage separately from Heap cookies, or moving between origins, can leave older tags behind. If local storage is unavailable, ABConvert sends assignment events without adding new persistent properties. It cannot recover lost cleanup history or remove tags while the integration is disabled.
Heap uses its own event and session analysis tools. This integration does not add the separate Heatmap service’s screenshot or test-group preview workflow.