# Heap.io Destination


[Heap.io](https://heap.io/) is a popular analytics platform built for marketers, product managers, and customer success teams.

RudderStack supports Heap.io as a destination to which you can send your event data in real-time.

Find the open source transformer code for this destination in the [GitHub repository](https://github.com/rudderlabs/rudder-transformer/tree/main/src/v0/destinations/heap).

## Connection compatibility

{{< destination-config >}}

{{< info >}}
In the web device mode integration, that is, using [JavaScript SDK]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/_index.md" >}}) as a source, RudderStack loads the Heap native SDK from the`https://cdn.heapanalytics.com/` domain. 

Based on your website's content security policy, you might need to [allowlist this domain]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/load-js-sdk.md#allowlist-destination-domain" >}}) to load the Heap SDK successfully.
{{< /info >}}

## Setup

1. From your [RudderStack dashboard](https://app.rudderstack.com/signup?type=freetrial), add the source. Then, from the list of destinations, select **Heap.io**.
2. Assign a name to your destination and click **Next**.

### Connection settings

| Setting | <div style="width: 350px;">Description</div> |
| :----| :-----|
| App ID | Enter your [Heap App ID](#where-can-i-find-my-heap-app-id). |
| Data Residency | Select **US** or **EU** based on where your Heap dataset resides. <br /><br />Note that:<ul><li>This setting applies only in [cloud mode]({{< ref "destinations/rudderstack-connection-modes.md#cloud-mode" >}}).</li><li>In [device mode]({{< ref "destinations/rudderstack-connection-modes.md#device-mode" >}}), the Heap native SDK handles event routing, so this setting has no effect.</li></ul> See [Data residency](#data-residency) for more information. |

### Event filtering settings

| Setting | <div style="width: 350px;">Description</div> |
| :----| :-----|
| Client-side Events Filtering | Specify which events should be blocked or allowed to flow through to Heap. <br /><br />See the [Client-side Events Filtering]({{< ref "sources/event-streams/sdks/event-filtering.md" >}}) guide for more information. | 

### Web SDK settings

| Setting | <div style="width: 350px;">Description</div> |
| :----| :-----|
| Use device mode to send events | Turn on this toggle to send events from your JavaScript SDK in [web device mode]({{< ref "destinations/rudderstack-connection-modes.md#device-mode" >}}). |  
| Consent management settings | Configure the consent management settings for the specified source by choosing the **Consent management provider** from the dropdown and entering the relevant consent category IDs. <br /><br />See [Consent Management in RudderStack]({{< ref "data-governance/consent-management/overview.md" >}}) for more information on this feature. |

## Identify

You can use the [`identify`]({{< ref "event-spec/standard-events/identify.md" >}}) call to capture the relevant details about the visiting user. 

{{< warning >}}
`userId` or `anonymousId` is a **required** field to send the `identify` call successfully.
{{< /warning >}}

A sample `identify` call is shown below:

```javascript
rudderanalytics.identify("1hKOmRA4GRlm", {
  name: "Alex Keener",
  email: "alex@example.com",
})
```

### Supported traits mapping

RudderStack maps the following user traits to the corresponding Heap properties:

| RudderStack property | Heap property | 
| :-------------------- | :---------------------- | 
| `userId` <br /> `traits.userId` <br /> `traits.id`<br />`context.traits.userId` <br /> `context.traits.id` <br /> `anonymousId` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `identity` |  
| `traits` <br />`context.traits` | `properties` | 

{{< info >}}
If `idempotencyKey` is present in `traits` or `context.traits`, it is removed before sending to Heap.
{{< /info >}}

## Track

You can use the [`track`]({{< ref "event-spec/standard-events/track.md" >}}) call to track your user actions and their associated properties.

{{< warning >}}
`userId` or `anonymousId` is a **required** field to send the `track` call successfully.
{{< /warning >}}

A sample `track` call is shown below:

```javascript
rudderanalytics.track("Order Completed", {
  userId: "1hKOmRA4GRlm",
  order_id: "12345",
  category: "clothing",
  revenue: 99.9,
  shipping: 13.99,
  tax: 10.99,
  promotion_id: "NEW_PROMO_10",
})
```

### Supported properties mapping

RudderStack maps the following event properties to the corresponding Heap properties:

| RudderStack property | Heap property | 
| :-------------------- | :---------------------- | 
| `userId` <br /> `traits.userId` <br /> `traits.id`<br />`context.traits.userId` <br /> `context.traits.id` <br /> `anonymousId` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `identity` |  
| `event`<br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `event` |
| `properties` | `properties` |
| `timestamp` <br /> `originalTimestamp` | `timestamp` |
| `properties.idempotencyKey` | `idempotency_key` |

{{< info >}}
RudderStack maps `properties.idempotencyKey` to the top-level `idempotency_key` field in the Heap event. It is then removed from the nested properties object to match the Heap API specification.
{{< /info >}}

## Data residency

Use the **Data Residency** setting to send cloud-mode events to the Heap datacenter where your dataset resides.

Note that this setting applies to `identify` and `track` calls in [cloud mode]({{< ref "destinations/rudderstack-connection-modes.md#cloud-mode" >}}) only. In [device mode]({{< ref "destinations/rudderstack-connection-modes.md#device-mode" >}}), the Heap native SDK handles routing.

The following table shows the endpoints used to send events based on the **Data Residency** setting:

| Data Residency | Endpoints |
| :--- | :--- |
| `US` (default) | `https://heapanalytics.com/api/track` and `https://heapanalytics.com/api/add_user_properties` |
| `EU` | `https://c.eu.heap-api.com/api/track` and `https://c.eu.heap-api.com/api/add_user_properties` |

{{< info >}}
**Backward compatibility**

- Existing Heap integrations without a **Data Residency** value continue to use the **US** endpoints. 
- If your Heap dataset resides in the **EU** datacenter, you will need to select **EU** in the **Data Residency** setting.
{{< /info >}}

## FAQ

#### Where can I find my Heap App ID?

1. Log in to your [Heap account](https://heapanalytics.com/app/settings/projects).
2. Go to **App** > **Settings** > **Projects**, and copy the required development or production App ID.

<br />