Heap.io Destination

Send your event data from RudderStack to Heap.io.

4 minute read

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.

Connection compatibility

Destination Information
Status: Generally Available Supported sources: Android (Java) , Android (Kotlin) , iOS (Obj-C) , iOS (Swift) , Web, Unity, AMP , Cloud, Warehouse, React Native , Flutter, Cordova, Shopify Refer to it as Heap.io in the Integrations object.

Connection Modes
Source	Cloud mode	Device mode	Hybrid mode
AMP
Android (Java)
Android (Kotlin)
Cloud
Cordova
Flutter
iOS (Obj-C)
iOS (Swift)
React Native
Shopify
Unity
Warehouse
Web

Supported Message Types
Source	Identify	Page	Track	Screen	Group	Alias	Record	AudienceList
Cloud mode
Supported sources
Device mode
Web

In the web device mode integration, that is, using JavaScript SDK as a source, RudderStack loads the Heap native SDK from thehttps://cdn.heapanalytics.com/ domain.
Based on your website’s content security policy, you might need to allowlist this domain to load the Heap SDK successfully.

Setup

From your RudderStack dashboard, add the source. Then, from the list of destinations, select Heap.io.
Assign a name to your destination and click Next.

Connection settings

Setting	Description
App ID	Enter your Heap App ID.
Data Residency	Select US or EU based on where your Heap dataset resides. Note that: This setting applies only in cloud mode. In device mode, the Heap native SDK handles event routing, so this setting has no effect. See Data residency for more information.

Event filtering settings

Setting	Description
Client-side Events Filtering	Specify which events should be blocked or allowed to flow through to Heap. See the Client-side Events Filtering guide for more information.

Web SDK settings

Setting	Description
Use device mode to send events	Turn on this toggle to send events from your JavaScript SDK in web 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. See Consent Management in RudderStack for more information on this feature.

Identify

You can use the identify call to capture the relevant details about the visiting user.

userId or anonymousId is a required field to send the identify call successfully.

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` `traits.userId` `traits.id` `context.traits.userId` `context.traits.id` `anonymousId` Required	`identity`
`traits` `context.traits`	`properties`

If idempotencyKey is present in traits or context.traits, it is removed before sending to Heap.

Track

You can use the track call to track your user actions and their associated properties.

userId or anonymousId is a required field to send the track call successfully.

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` `traits.userId` `traits.id` `context.traits.userId` `context.traits.id` `anonymousId` Required	`identity`
`event` Required	`event`
`properties`	`properties`
`timestamp` `originalTimestamp`	`timestamp`
`properties.idempotencyKey`	`idempotency_key`

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.

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 only. In 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`

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.

FAQ

Where can I find my Heap App ID?

Log in to your Heap account.
Go to App > Settings > Projects, and copy the required development or production App ID.