> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abconvert.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Heap integration

> Tag Heap storefront activity with ABConvert test groups to compare visitor behavior across your tests.

<Warning>
  **Pre-release.** This guide applies when the Integrations hub is enabled for your ABConvert account.
</Warning>

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:

| Field                   | Meaning          | Example                  |
| ----------------------- | ---------------- | ------------------------ |
| `experiment_id`         | Test ID          | `"49603"`                |
| `experiment_name`       | Test name        | `"Snowboard price test"` |
| `variant_id`            | Test group index | `"1"`                    |
| `variant_friendly_name` | Test group name  | `"Variant A"`            |

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

<Steps>
  <Step title="Install Heap on your storefront">
    Follow [Heap's web installation guide](https://developers.heap.io/docs/web). Keep your existing consent controls in place. No Heap API key is needed in ABConvert.
  </Step>

  <Step title="Enable Heap in ABConvert">
    Open **Integrations**, find **Heap** under **Analytics & Session**, and enable it.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](https://developers.heap.io/reference/removeeventproperty) if you need to clear them.

## FAQ

<Accordion title="What if Heap loads after consent?">
  ABConvert waits up to ten seconds for Heap's SDK or queue. If it appears later, tagging can resume on the next assignment update or page load. Declined consent, blockers, and an unavailable SDK can prevent delivery.
</Accordion>

<Accordion title="Are there limits on tags?">
  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.
</Accordion>

<Accordion title="Does cleanup work across storefront domains?">
  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.
</Accordion>

<Accordion title="Does this include Heatmap's test-group screenshot workflow?">
  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.
</Accordion>