# Heap

## How It Works <a href="#sync-with-your-activecampaign-list" id="sync-with-your-activecampaign-list"></a>

After connecting, the Heap integration transmits data to your Heap account, enabling analysis and reporting on your referral program.

For referrers, when they are added to your campaign (e.g., they get a referral link generated) or if they click a social share button (like Facebook or LinkedIn), GrowSurf sends an Heap event. For referred friends, if they sign up using your Share URL, GrowSurf also sends an event.

{% hint style="success" %}
Under the hood, GrowSurf will load the Heap JavaScript library, identify participants (both referrers and referred friends) by their email address, and track events. Rest assured, if Heap is already installed, GrowSurf ensures the library is not loaded twice and prevents duplicate identity calls.
{% endhint %}

## Tracked Events

The following events will be emitted with the `growsurf_` prefix.

| Event                       | Description                            | Explanation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `growsurf_referral`         | \[Referred friend] New referral signup | <p>Records when a referred visitor signs up through a referral link.<br><br>This includes:</p><ul><li>Those who submit the form on your website that has referral tracking enabled (via the campaign editor)</li><li>Adding a referred participant via <a href="https://docs.growsurf.com/integrate/javascript-web-api/api-reference#add-participant"><code>growsurf.addParticipant()</code></a></li></ul>                                                                                                                                                                                                                                                                            |
| `growsurf_referral_trigger` | \[Referred friend] Referral triggered  | Records when a referred participant completes the desired qualifying action, which triggers a referral. Only applies when you are using [`growsurf.triggerReferral()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#trigger-referral).                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `growsurf_signup`           | \[Referrer] New referrer signup        | <p>Records when someone generates a referral link and joins the campaign as a participant.</p><p></p><p>This includes:</p><ul><li>Direct signups (someone entering in their email address on the GrowSurf form)</li><li>Passing in an email address via URL parameter <code>?grsf\_email</code></li><li>Passing in an email address via <code>data-grsf-email</code> attribute on an <a href="https://docs.growsurf.com/integrate/javascript-web-api/embeddable-elements">Embeddable Element</a></li><li>Adding a participant via <a href="https://docs.growsurf.com/integrate/javascript-web-api/api-reference#add-participant"><code>growsurf.addParticipant()</code></a></li></ul> |
| `growsurf_share`            | \[Referred] Social media share         | Records when a referrer shares their link by clicking 'Copy Link' or clicking a social media button                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `growsurf_invite`           | \[Referrer] Email invite(s) sent       | Records when a referrer sends invitation(s) via email                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Example Events

Events correspond with the events listed in the [`growsurf.subscribe()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#subscribe-to-event) method. To see examples of the raw `JSON` data, please see the [*Example Response*](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#example-response-6) section (Note that event objects will be flattened before being sent to Heap).

***

## How to Set Up

**Step 1**: In *Campaign Editor > 4. Options > Integrations*, open the Heap integration card and enter your [Heap App ID](https://help.heap.io/getting-started/getting-started-faqs/whats-the-difference-between-the-app-id-and-env-id-in-heap/).

{% hint style="info" %}
**Note:** If you are 100% certain that you already have Heap installed on your website, you do not need to enter in the Heap App ID. Simply press *Connect* and the integration will be enabled. However, we recommend that you still enter it to account for URLs that do not have Heap installed.
{% endhint %}

<figure><img src="https://2794996218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LeklWo0yn03AhWro2Ux%2Fuploads%2FtP6ZlhAsb8cVQAhwKfmZ%2Fimage.png?alt=media&#x26;token=e4be56eb-eb50-49eb-97ef-1fb03491bfe9" alt=""><figcaption></figcaption></figure>

**Step 2:** Once connected, GrowSurf will have all events enabled by default. Disable any events that you do not want to track.

{% hint style="danger" %}
**Important Note**: Within your Heap account, make sure to whitelist the URLs where these events occur. These are primarily two locations: your referral portal (which might be part of your user portal or web app, or the [GrowSurf-hosted referral portal](https://support.growsurf.com/article/196-where-can-i-find-my-campaigns-dedicated-landing-page)) and the referred friend's landing page (the Share URL you enter in the *Campaign Editor > 5. Installation* step).
{% endhint %}

Once GrowSurf events get emitted, you will see them show up in Heap *> Data > Live data feed*.

To view only GrowSurf-related data, filter results by setting `participant.id` to "is defined" (see image below).&#x20;

<figure><img src="https://2794996218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LeklWo0yn03AhWro2Ux%2Fuploads%2FVoXs08v5Wesn8O7YeS08%2Fimage.png?alt=media&#x26;token=fe222453-2e2b-40c4-8e41-49ad8598ebaf" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Note:** Please allow up to 15 minutes of processing time for events to appear (in some cases where Heap is backed up, it can take longer).
{% endhint %}

***

## **Troubleshooting Tips** <a href="#troubleshooting-tips" id="troubleshooting-tips"></a>

Here are common scenarios and how to troubleshoot them.

#### If you are seeing a wrongly identified user:

There are 5 different ways that GrowSurf participants can be added to your campaign. Please make sure that the GrowSurf participant email address that you are passing in matches the one you were expecting for the Heap user:

* If you pass in a `data-grsf-email` attribute to a [GrowSurf embeddable element](https://docs.growsurf.com/integrate/javascript-web-api/embeddable-elements)
* If you pass in an email address via URL parameter `?grsf_email`
* If you are using [`growsurf.addParticipant()`](https://docs.growsurf.com/integrate/javascript-web-api/api-reference#add-participant)&#x20;
* If you enter an email address via the GrowSurf form
* If you are a referred friend and you submit the form that has referral tracking configured on it from the *Campaign Editor > 5. Installation* step

#### If you are not receiving events, but were expecting them:

* Please make sure you are using the [Heap App ID](https://help.heap.io/getting-started/getting-started-faqs/whats-the-difference-between-the-app-id-and-env-id-in-heap/) from your *Production* environment (and not your *Heap Env ID*).
* Make sure you do not have any ad-blockers or browser extensions blocking requests to Heap.
* Make sure to whitelist the URL where events are being tracked (e.g, if your referrer clicks the Facebook share button from *<https://app.yoursite.com/refer>*, you'll want to make sure you whitelist that root domain. If a referred friend signs up on your Share URL, make sure to whitelist the Share URL as well).
* If you just submitted an event, make sure that you've allowed up to 15 minutes for Heap to process the event.

#### If you are receiving events, but were NOT expecting them:

* To ensure no non-GrowSurf-related events are sent to your Heap account, disconnect the integration completely. Simply toggling off all checkboxes is insufficient.
* If you're receiving events without a GrowSurf-related suffix (e.g., `growsurf_`), it indicates that GrowSurf may not be emitting these events. Please check other parts of your code to find where these events might be occurring.