Heap integration: user guide

Learn how to set up and use Chameleon's Heap integration

Pulkit Agrawal avatar
Written by Pulkit Agrawal
Updated this week

Understand how your Experiences drive your product's adoption and target Heap cohorts in Chameleon.

With our Heap integration, you can ensure that essential user attributes are available in Chameleon to deliver relevant Experiences. Complement your analytics with Chameleon data to pinpoint what efforts you can improve or scale up.


Availability & Usage

🔐 Available for all plans

📍 Here for better Tours, Tooltips, Microsurveys, Launchers

⚙️ Enable from the Dashboard


With Chameleon's Heap integration, you can analyze and target Chameleon Experiences at an advanced level. By connecting Heap to Chameleon, you can set Heap as a:

  • Data Destination -- send Chameleon data to Heap (for analyzing Experiences)

  • Data Source -- get Heap data into Chameleon using Heap events or webhooks (for targeting Experiences)

Refined Segments are essential for successful product guidance; relevance breeds high engagement. And once you communicate with users, you'll want to know what drives the biggest impact.

Sync your data to Heap to analyze how your Experiences contribute to each step of your user's journey, and decide how you can improve it.


Enable the Heap integration in a few clicks. Search the integrations page in your Chameleon Dashboard for Heap to connect your Heap account.

Next, enable to toggle below to automatically begin sending data to your Heap account. This works by using the existing Heap code on your website, and data will only be sent on pages where the Heap script is present and working.

You will then see events flow into your Heap account, and you can check this in the Live data feed 👇

💡 Event properties sent as part of these events include the Experience name, URL, and others (e.g. Step number) where relevant.

⚠️ For integrations connected prior to July 2021 you will need to first "Define" these events within Heap to see them in your reports and to leverage them in any analysis. For integrations connected after July 2021, these events will automatically be defined by Heap.

To define events within Heap, you will need to click on the event, and then click Define Event:

Alternatively, you can visit the "Definitions" section of your Heap dashboard, and then define the event.

Then, you will have to name the event, which can be the same as the default Chameleon name, or as your own analytics taxonomy. You may also want to create a separate category for all the events that Chameleon sent.

Once the event is defined, you will have access to it everywhere in your Heap dashboard.


The Heap integration enables you to understand how to create a better user journey and drive your product's success further. In Chameleon, you can use a variety of filters to leverage your Heap data efficiently.

With your Chameleon data synced to Heap, you can use these events to define funnels and see this reporting within Heap 👇

You can also set up custom names for key events by editing the Event Criteria, and leveraging these custom (virtual) events in your analysis. This will help you monitor and improve your Experience performance.

With this aspect of the integration, you will see Chameleon Events under the Chameleon Source within Heap. The data includes (but is not restricted to) the following events:

  • Chameleon Started Tour / Microsurvey

  • Chameleon Completed Tour / Microsurvey

  • Chameleon Step Seen

Chameleon events are first-class events within Heap in the Chameleon Source:

For full details of all Chameleon data sent to Heap, use our schema below:

Use these events to create funnels for different stages of the user journey. This will help you analyze how your Experiences help users progress or where you should still be looking to unblock them.

You can send the events and properties you leverage across your stack to Chameleon to help you refine your Segments. This will ensure each Experience you create gets to be seen by users who can connect to it and get value out of your message.

There are three ways to get data from Heap into Chameleon and target Chameleon Experiences:

Use your Heap Segments as a data source to target different groups of users in Chameleon. You can create cohorts of users based on their past engagements or current rights. Here’s how to set it up:

❶ First, in your Heap account go to "Integrations", search, and add Chameleon to your account.

❷ Next, in your Heap account, go to the "Definitions" page.

  • From the list, select the Segment option

  • Click "New Definition -> New Segment" to create yours

  • Go to your newly created Segment in Heap and scroll down to the integrations panel. Enable the Chameleon integration from the toggle there. 👇

❸ Finally, go back to your Chameleon Dashboard. You'll see your synced Segments on the Heap integration page 👇

⚙️ This assumes you already connected your Heap account; if you didn't make sure to connect to Heap.

Your data will be available to use as a filter while creating your Segments in Chameleon, via the 'Heap Segments' option. You can pick between 'is a member of' or 'is not a member of' and select the relevant Heap Segment.

You can also forward tracked events from Heap to Chameleon. To do this, create a “snapshot” on any defined event in Heap and use that snapshot to trigger a “track event” action in Chameleon.

  1. Define an event in Heap and add a new snapshot property on the event from the events view.

  2. Set the property value to chmln.track("event name"); where event name can be replaced with any event name you want to show up in Chameleon for this event.

  3. Test performing that event on your site and see if the event appears within Chameleon. You can view all your events in your Dashboard, here.

👉 Events shown on the Data Management page within Chameleon are updated every 15 minutes.

Using Heap's Webhooks feature enables you to get data out of Heap in real time. If you have access to this feature, you will find it under the Integrations list in Heap.

To configure this feature, and have Heap and Chameleon communicate through webhooks, you'll use Chameleon's Incoming Webhooks, which are on your Heap integration page

Here, you'll find three different endpoints, user properties, company properties, and user events -- each containing a unique URL.

◾️ The setup process for events and user properties is very similar, differing only in the Data to Send section. Here's how to do it:

  • Under Basic Configuration, add the endpoint URL that corresponds to the data you're sending to Chameleon.

  • No specific Headers are required. Authentication is built into the Endpoint URL (which contains your unique Chameleon token).

◾️ To send user (or company) properties, under Data to Send, add the following properties:

  • Key: uid, type: property, value: Identity *

  • Any other fields you want to send to Chameleon

◾️ To send user events, under Data to Send, add the following properties:

  • Key: uid, type: property, value: Identity *

  • Key: name, type: constant, value: event name (replace 'event name' with the actual event name) **

  • Key: at, type: constant, value: $now ***

  • Under Triggering Events, choose the Heap event that will trigger this webhook to run.

Notes:

* You will need to make sure you are sending the same uid to both Heap and Chameleon as part of your installation.

** You will find the event in Chameleon named according to what you define here.

*** This will be the time for your event. you can also specify this differently as per your system of keeping time or the time you want to set the event to have occurred.


🔐 Available on Heap's Growth, Pro, and Premier plans

Heap has a feature that allows you to receive an email or Slack notification when an "Alert" is triggered. This is a powerful way to get real-time notifications when Chameleon Experiences may not be performing as expected.

This Alert can be based on a heuristic anomaly being detected, or results going above or below a certain threshold, including those containing Chameleon events sent to Heap.

Read more about this in Heap's docs here, or see the summary below.

To set up an Alert in Heap, first create and save a Chart. This could use the "Chameleon Step Seen" event fired each time a Step is seen. This could also be filtered to a specific Step or Tour (using an event property such as step_id, or tour_name).

Once you have your Chart, you can create your Alert from the "Actions" dropdown.

Pick how to trigger the Alert: based on an increase or a decrease in metrics. You'll then get a notification when a significant change occurs related to your event.

Did this answer your question?