📘

Partner-Owned

This integration is set up and supported by Segment. For questions, reach out directly to their team.

Overview

Installing Heap via Segment enables you to enhance Heap’s autocaptured data with user identities, custom user properties, and custom events configured in Segment.

How do Heap and Segment work together?

Segment ingests data from Sources and sends data to Destinations. In Segment terms, Heap is a Destination (data from Segment is sent into Heap).

After installing Heap via Segment, Heap is also considered a destination by Segment. Within Segment you can configure your Heap app ID and Segment will load Heap’s libraries to your website (rather than deploying the Heap code directly on site). All standard functionality of Heap is maintained when deployed via Segment.

How does installing Segment impact how you will implement Heap?

Most Segment users deploy Heap on the web via Segment. In this setup, Segment loads Heap’s JavaScript library asynchronously onto the page, Heap retains all native functionality including autocapture of all events.

Notes and exceptions:

• It's critical that Heap libraries load only once, so you must NOT install the Heap snippet directly AND install via Segment.
• If Segment is deployed via Google Tag Manager, direct installation of Heap is recommended to avoid delays in data collection or missed events.

Base Installation

Web

We recommend installing Heap for the web via Segment to leverage Segment for centralized tag management and to quickly extend Segment configuration to Heap (eg, User Identification, User Properties, and Custom Events).

Exceptions:

• You have data collection privacy concerns and plan to leverage disableTargetText (a Heap API)
• You are not committed to using Segment long-term. If Heap is implemented via Segment and Segment is removed, then Heap will need to be re-installed and re-configured.

To set up the Heap Segment source, all you need to do is visit the Heap destination connection page in your Segment account. From this view, you’ll need to confirm the Source and provide your Heap app ID in the next view.

You can find your Heap app ID in Heap by navigating to Account > Manage > Projects, then selecting the project you need to find the app ID for. All app IDs associated with environments on that project will be listed.

❗️

If you are using Segment to load Heap, do not also install the Heap snippet natively in your site. This could cause unexpected events and errors in your data.

The ID is also listed within the web installation snippet on the installation page.

Mobile

When installing Heap on mobile apps, the iOS or Android SDK must be installed directly to fully enable autocapture. Heap can be deployed to mobile apps using Segment’s cloud mode, but only custom events configured in Segment will be captured via Heap’s server-side API.

We currently support Segment’s cloud-based connection mode on mobile, which sends data to Heap via our server-side track API, but does not package Heap’s SDK with Segment’s. Setting up Heap in this way won't enable autocapture functionality, and only Segment-tracked events will be sent to Heap (as server-side events).

It is possible to install the Heap SDK natively as well as through Segment to get both autocaptured events and Segment-tracked events. Note that since Segment data will come into Heap as server-side events, this will limit the ability to perform “within-a-session” analysis. You can, however, use a time restriction (e.g. “within an hour”) as a proxy. Please consult your Account Manager or reach out to [email protected] to discuss this option further.

Data Format

Once enabled, Heap will automatically capture all of the data included in our standard autocapture solution in addition to the following data from Segment:

• Any custom events tracked via Segment
• Any custom user properties sent as traits to Segment

Please refer to Segment’s documentation for more information on the Heap Segment Source.

Mapping Segment APIs to Heap

Device Mode

Heap supports Segment API calls in “device mode” to identify and track.

Calls to analytics.identify() are split into two Heap API calls: userId and traits are sent to Heap as heap.identify() and heap.addUserProperties() calls, respectively.

Calls to analytics.track are sent via heap.track.

We do not currently support page, alias, or group calls.

You can view Heap’s Segment device mode integration at this Segment repo.

Cloud Mode

Heap supports Segment API calls in “cloud mode” to /identify and /track.

• Calls to /identify are sent via Heap’s server-side Add User Properties API.
• Calls to /track are sent via Heap’s server-side Track API.

We do not support Segment event replay at this time. See Heap’s Segment cloud mode integration to learn more.

Configuring Third-Party Data Sources

Both Heap and Segment ingest data from third-party applications such as email marketing tools, A/B testing tools, etc. In general, it's recommended to set up other data tools as Segment Sources, and to pass relevant data from Segment to Heap.

To integrate data from third-party applications you plan to send to multiple destinations, we recommend configuring them in Segment as Sources and passing relevant data to Heap. For applications that Heap has a productized integration to, integrating directly to Heap will make sure the data is best architected for analysis.

Custom Events

We recommend setting up custom events in Segment and passing that custom data on to Heap. If you have existing custom events in Segment, only send the ones to Heap which are relevant to analyses - especially if there are many custom events, and/or you suspect some events may be incorrectly configured.

Only add Heap as a destination for events from relevant data sources. A recommended Segment setup includes client-side and server-side sources for development, staging, and production.

If you already have custom events set up in Segment, those custom events can be sent into Heap. When managing events that exist in both Heap and Segment, we recommend that if you have a custom event in Segment already, use that one. However, if you need a custom event for other Segment destinations, use the same event in Heap.

When creating custom events, keep in mind server-side custom events are only needed for:

• Offline events
• Mission-critical/end of funnel events when values must be exact
• When custom properties are needed

User Identity & User Properties

If you have already implemented user identity, whenever the Segment analytics.identify() endpoint is called, Segment will call the heap.identity() endpoint with the same identity value, as well as heap.addUserProperties() with any traits included in the Segment identity call. Heap will still assign anonymous user IDs, Segment ID values are used as the Identity value in Heap.

Note: If you are sending emails to Heap as a user property or trait via Segment’s analytics.identify() API, the email user property in Heap will start with an underscore, _email. This is expected and won't suggest issues with your implementation.