Overview

This Segments Sync API enables partners to receive data from Heap so mutual customers can use behavioral segments in Heap to take action in another product.

For example, an in-app guidance product may want customers to launch personalized walkthroughs based on user activity in order to drive higher engagement. By building this integration, mutual customers of Heap and the in-app guidance product will be able to target walkthroughs based on user activity captured by Heap.

For a refresher of what segments are and how to use them, watch this video:

As a Heap partner, you have the ability to build on our Segments Sync API to ingest user lists into your tool. This is done by creating an integration. Once your integration is built, customers will be able to seamlessly turn on the integration in the Heap app with no need for tailored support from your team. Our goal is to make these integrations feel fully integrated into the Heap user experience.

Build Steps

For a technical overview, check out our reference app.

Request access to the Developers Hub and a Heap test account from your Heap Partner Manager or from [email protected].
In your Heap test account, navigate to the Developers Hub (Integrate > Developers Hub) and click Create new integration.
Set up a webhook endpoint (spec, example) to receive data from Heap. Heap will call this endpoint every 4 hours with information about which users have entered or exited the segment since the last call. You can use webhook.site to test this step and see a sample payload.
Add a UI in your product to enable users to set up their integration (example screenshot below). Heap will feature your integration in our integration directory and direct users to this UI to initiate setup.

Implement OAuth by setting up OAuth endpoints (example).
Get the property that users will be matched on in your product. For example, some products use “email” and others use “user ID”, “identity”, or “uuid”. If you have a standard user property that’s reserved for identifying users, you will want to have this property name handy for the next part of setup. Customers will be asked to select a user identity property to send in the webhooks during the setup process. What you input here will be shown in the setup modal to guide their selection.

Input the webhook URL (from step 3), OAuth Redirect URL (from step 5), and identity matching information (from step 6) in the Developers Hub to complete the integration draft.
Test your integration following the steps in the reference app.

Running a Customer Beta

Once you’re ready to test the integration with customers, reach out to your Heap Partner Manager to assist with the beta:

Do a mutual customer mapping exercise with your Heap Partner Manager to identify target customers for the beta.
Reach out to target beta customers and share about the integration and use cases.
Observe them setting up and using the integration, and share feedback with your Heap Partner Manager.
Identify opportunities for joint customer marketing (e.g. customer quotes, testimonials) and work with your Heap Partner Manager to build joint marketing collateral.

Publishing Your Integration To The Directory

When you are ready to publicly list your integration in the Heap Integrations Directory, follow these steps:

Click the Publish tab for the integration and fill out the required content.
For the Description field, follow the template below to draft your long description.

Content (sample):

[2-3 sentences describing your product]

[2-3 sentences describing the integration]

Example use cases (limit to 3-5):

[use case 1]
[use case 2]
[use case 3]

Heap is using this content to automatically populate your directory listing, so make sure to check it over before submitting!

Now sit back and relax! Your Heap Partner Manager will respond to your listing via email in 5-7 days.

Frequently Asked Questions

When setting up an integration, why do I need to specify what I use to identify users in my product?

When a customer sets up your integration, they need to map users between Heap and your product using a common identity value so that your product can identify users from Heap accurately. In Heap, customers can configure any user properties or identity as the Heap matching key. To guide customers to select the right key to match user identities in your product, we need your guidance on how users are identified in your product.

For example, if users in your product are primarily identified via email addresses, you would specify “email address” here and Heap will display “email address” on the user matching setup screen.

Here is an example of the user matching screen for an integration built by our partner, Chameleon, who uses “id” in their product to identify users.

How long does it take to review and approve my integration?

We will typically respond to your approval within 7 days. If you haven’t heard back in 7 days, please reach out to your your Heap Partner Manager or to [email protected] to check on your approval.

How do I test the integration with a larger data set?

Once you create the integration in a Heap environment, it is available to use in that environment. You can install Heap or use our server-side track APIs to import data into the Heap environment and then sync test segments to your integration. If you want to test this integration in other environments, simply create the same integration again in other environments before testing.

For any additional questions, reach out to your your Heap Partner Manager or to [email protected].