Heap Destination

Segment makes it easy to send your data to Heap (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Heap in the format they understand. Learn more about how to use Heap with Segment.

Getting Started

When you toggle on Heap in Segment, this is what happens:

  • Our CDN is updated within 5-10 minutes. Then our snippet will start asynchronously loading heap.js onto your page. This means you should remove Heap’s snippet from your page.
  • Heap will automatically start recording data.

Required Field

If you are sending events to Heap via our server side destination, you must provide a userId. All anonymous events will be rejected since Heap’s API also rejects them on their end.

Identify

Client Side

When you call identify on Analytics.js, we call Heap’s identify method with the userId and traits you provide.

Server Side

Our server-side libraries support the identify call. The identify call will send a request to Heap’s identify endpoint.

Track

Client Side

When you call track or one of its helper functions on analytics.js, we call Heap’s track function with exactly the same parameters.

Server Side & Mobile

Calling track from one of our mobile SDKs or server-side sources records a Heap Custom Event with the same event name and properties.


Web

If you are using Heap via Segment’s client-side analytics.js library, we asynchronously load Heap’s javascript library onto the page. As such, all native functionality of Heap, including auto capturing of all events.

Nested Objects and Arrays

While these are not the preferred way to send data types, in the event that you send us nested objects or nested arrays of objects, we will flatten and stringify them before sending to Heap. For example:

analytics.track('Signed Up', {
  foo: {
    bar: {
      cheese: 'american',
      prop: [1, 2, 3],
      products: [{"A": "Jello"}, {"B": "Peanut"}]
    }
  }
});

The properties would be sent as:

foo.bar.cheese: 'american' foo.bar.prop: '[1,2,3]' foo.bar.products: "[{'A': 'Jello'},{'B': 'Peanut'}]"

Dates

We will convert all date type properties or traits into an ISO string.


Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

App ID

You can find the snippet containing your app ID in Heap’s QuickStart docs. It’s inside the heap.load('YOUR_APP_ID') function call.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!