Our bi-directional LaunchDarkly integration allows you to send Heap segments into LaunchDarkly and send LaunchDarkly data into Heap. Read on for steps to set up both sides of this integration.

Sending LaunchDarkly data into Heap

The steps below allow you to send data from LaunchDarkly into Heap. You'll need to attach LaunchDarkly's user key and feature flags as user and event properties in Heap.

If you're using addEventProperties, be sure to double-check the length of the cookie—there is a max of 4kb for the props cookie and most servers have an 8kb cookie load limit. You can calculate the cookie size of passing all feature flags by in the browser console.

If you're noticing none values on your non-pageview events while doing your analysis in Heap, that's a good sign that you need to call clearEventProperties to ensure you're under the browser cookie limit.

encodeURIComponent(JSON.stringify(ldclient.allFlags())).length

You can also add user flags as user properties.

// get LaunchDarkly user ID and send to Heap as user property

var ldUserId = ldclient.getUser().key
heap.addUserProperties({"ldUserId": ldUserId});

/ /get LaunchDarkly feature flags and attach as properties to all events

var ldProps = ldclient.allFlags();
heap.addEventProperties(ldProps);

It's also important to note that the LaunchDarkly client initializes after Heap does, so those flags that we add are best analyzed with non-pageview events.

Sending Heap segments into LaunchDarkly

Automating the syncing of segments from Heap to LaunchDarkly lets you import users from Heap to LaunchDarkly to more efficiently target and deliver feature flags. This allows you to focus more on deploying features and less on managing end users between platforms.

Prerequisites

To sync segments, you must meet the following prerequisites:

• You must have a LaunchDarkly access token with write access for the project you want to connect to Heap. To learn more, see Configuring your access token.
• You must have a LaunchDarkly client-side ID for the environment you want to connect to Heap. To learn more, see Finding and resetting an environment's keys.
• You must have the LaunchDarkly integration enabled in Heap. For access, contact your Heap Customer Success Manager or sales@heap.io.

Step 1: Create LaunchDarkly access token

To create (or obtain) your access token, login to your LaunchDarkly account under the environment that you wish to sync with, then complete the steps below. 

1. Navigate to Account Settings
2. Select Create token
   1. Provide any Name for the token
   2. Choose Role = Writer
   3. Select API version 20220603
   4. Check the box for “This is a service token”
3. Save token

Once saved, you will be prompted to Copy and Save the token.  Save this, as you'll need it later to complete this setup.

Step 2: Copy the LaunchDarkly client-side ID

The client-side token for the LaunchDarkly environment that you wish to use also needs to be provided to the Heap team.  To retrieve this token:

1. In LaunchDarkly, Navigate to to Account Settings
2. Click the Projects tab
3. Select the desired project name
4. You should see the Environment that you wish to setup this integration for
5. For the desired environment, copy the value for Client-Side ID

Step 3: Enable this integration in Heap

If you haven't done so already, now that you have what you need to enable this integration, contact your Customer Success Manager at Heap or sales@heap.io to have them enable this integration. You should expect a response within 2 business days.  

Once this step is complete, you'll be provided with a URL to add to your Heap account. Next, login to Heap and complete the following steps:

1. Within Heap, navigate to Integrations > Developer Hub
2. Select Create New Integration
   1. Provide a Name (i.e. LaunchDarkly)
   2. In the Webhook URL field, add the URL that you were provided by Heap
   3. OAuth Redirect URL can remain empty
   4. Enter “id” in the field to identify your users in LaunchDarkly
3. Click Save

Once enabled, you'll see the LaunchDarkly integration option under all of your Heap segments.

Understanding syncing segments

By syncing segments, you can connect new or existing Heap segments to LaunchDarkly. LaunchDarkly interprets this segment as a synced segment, which makes it convenient for you to target flags to specific context groups or demographics.

Heap segments can be synced once, or at 4-hour intervals, which keeps them current with the existing segment. We recommend enabling a Recurring Sync. Steps for doing this are provided below.

By syncing segments, you can deliver flags to the right context groups precisely and on time.

Creating a segment that syncs with LaunchDarkly

Once the integration is set up, you'll be able to sync any of your segments to LaunchDarkly. To do so, select the segment and toggle on the switch to sync the segment. 

You can select either a one-time sync or to enable it as a recurring sync (every 4 hours).  Each time the segment syncs, it will send over any newly-added or newly-removed segments from the last time that the sync ran. 

The first time you sync to LaunchDarkly, you'll be prompted to select which field from Heap contains the value that you want to sync to the LaunchDarkly user. 

Be sure to choose the field in Heap that contains the LaunchDarkly user key.

Viewing synced Heap Segments in LaunchDarkly

Now that you've synced a Heap segment, you can view your synced Heap segments in LaunchDarkly. It appears on the Segments list with the Heap logo in its name

1. Login to LaunchDarkly, then navigate to to Segments
2. Search for segment name
   1. The segment name used in Heap will be used as the Segment name in LaunchDarkly.
3. Heap segments can be identified by the Heap logo under the segment name.
4. Once the segment is in LaunchDarkly, it can be used to target audiences in those Heap segments.