• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""
EXPAND ALL

EDIT ON GITHUB

Syncing segments from Amplitude cohorts

Read time: 4 minutes
Last edited: Oct 21, 2021
Syncing segments is an Enterprise feature

Syncing segments from Amplitude cohorts is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

Overview

This topic explains how to create Big Segments that sync with an Amplitude cohort. Syncing segments let you import audiences from Amplitude to LaunchDarkly to more efficiently target and deliver feature flags.

The benefits of syncing segments with Amplitude is the automatic syncing between Amplitude and LaunchDarkly. This lets you concentrate more on deploying features and less on managing users between platforms.

The prerequisites for Big Segments apply to syncing segments. To learn more, read Using Big Segments.

Prerequisites

In order to sync segments, you must meet the following prerequisites:

  • You must have an Amplitude account with the LaunchDarkly integration enabled. Contact your Amplitude Customer Success Manager to enable the LaunchDarkly integration.
  • You must have a LaunchDarkly access token with write access for the project you want to connect to Amplitude. To learn more, read Configuring your access token.
  • You must have a LaunchDarkly client-side ID for the environment you want to connect to Amplitude.
  • If you are using server-side SDKs, or client-side SDKs with the Relay Proxy, there are additional prerequisites. To learn more, read Using Big Segments.

Understanding syncing segments

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

In the past, the only option to import a user segment from a third-party tool was to manually upload a CSV file or configure users through the LaunchDarkly API.

You can configure segments to sync automatically in LaunchDarkly at regular intervals, which keeps them current with the existing cohort. We recommend setting up your segment to sync every hour. The process for doing this is documented below.

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

Creating a Big Segment that syncs with Amplitude

To configure a Big Segment that syncs with an Amplitude cohort, you must choose a cohort in Amplitude and tell it to send data to LaunchDarkly. When you do this correctly, the cohort appears as a user segment in LaunchDarkly.

To do this, first add LaunchDarkly as a destination and then sync the cohort to the LaunchDarkly destination.

Configuring your access token

To add LaunchDarkly as a destination in Amplitude, you need an access token from your LaunchDarkly project. To learn how to create an access token, read Creating API access tokens.

Your access token must have either a writer or custom role:

An access token with the Writer role called out.
An access token with the Writer role called out.

If your access token has a custom role, it must have the actions createSegment and updateIncluded to sync a segment from Amplitude.

Below is an example of the permissions needed for your custom role:

1[
2 {
3 "resources": [
4 "proj/*:env/*:segment/*"
5 ],
6 "actions": [
7 "createSegment",
8 "updateIncluded"
9 ],
10 "effect": "allow"
11 }
12]

To learn more, read Custom roles and Segments actions.

Adding LaunchDarkly as a destination

To create a destination in Amplitude, you must have Admin or Manager credentials.

To add LaunchDarkly as a destination:

  1. Log in to Amplitude and navigate to Data Destinations:

The Amplitude dashboard with the "Data Destinations" button called out.
The Amplitude dashboard with the "Data Destinations" button called out.

  1. Scroll to the "Add More Destinations" section and click View All Destinations:

The Add More Destinations section with the "View All Destinations" button called out.
The Add More Destinations section with the "View All Destinations" button called out.

  1. Select the LaunchDarkly Destination:

The Add Destination list with LaunchDarkly called out.
The Add Destination list with LaunchDarkly called out.

If you don't see LaunchDarkly on the destinations list, contact your Amplitude Customer Success Manager to enable the LaunchDarkly integration. If you do not have Admin or Manager credentials Amplitude displays an error message:

A permission error message in Amplitude.
A permission error message in Amplitude.

  1. Enter a destination name and add the access token and client-side ID for your LaunchDarkly project and environment.

  2. Select a matching user property in Amplitude to map to LaunchDarkly's User Key. This will most likely be your Amplitude user ID but it depends on your Amplitude configuration:

The Connect to LaunchDarkly screen.
The Connect to LaunchDarkly screen.

Users in Amplitude must have a value in the field you map to the LaunchDarkly User Key to be included in a LaunchDarkly segment.

  1. Click save.

  2. Verify that LaunchDarkly shows as "Connected":

The Cohort Destinations screen.
The Cohort Destinations screen.

LaunchDarkly is now an Amplitude data destination.

Sync cohort to LaunchDarkly

To connect a cohort to LaunchDarkly:

  1. Navigate to the cohort you wish to connect to LaunchDarkly.
  2. Click Sync to... to open a new tab with a modal:

The SuccessCohort screen with the "Sync to..." button called out.
The SuccessCohort screen with the "Sync to..." button called out.

  1. Select Experiment then LaunchDarkly. If you don't see the LaunchDarkly destination, make sure you have added LaunchDarkly as a destination:

The "Select Sync Type" screen.
The "Select Sync Type" screen.

  1. Click next. The destination configuration screen appears.

  2. Select your LaunchDarkly destination and set the scheduled sync frequency. An hourly sync frequency ensures your segments are kept up to date with your Amplitude cohorts. A one-time sync exports the cohort into a Big Segment once:

The Amplitude destination configuration screen.
The Amplitude destination configuration screen.

  1. Click Sync.

  2. The sync process begins and might take a few minutes to complete:

The Amplitude cohort destinations screen.
The Amplitude cohort destinations screen.

When the sync finishes Amplitude sends you an email and LaunchDarkly appears in the list of Destinations connected to that cohort.

Checking for missing user IDs

Users missing a user ID in Amplitude are not included in the segment

Users in Amplitude must have a value in the field you map to the LaunchDarkly User Key, typically the user ID, to be included in a LaunchDarkly segment. Any Amplitude users missing a value in the mapped field are not included in the LaunchDarkly segment. To learn how to view the users in a segment synced with Amplitude, read Viewing synced Amplitude cohorts in LaunchDarkly.

To check for users in your Amplitude cohort missing user IDs, you can download a CSV file with user ID information. Here's how:

  1. While viewing your cohort in Amplitude, click on the export CSV button:

The Amplitude top menu with the export CSV button called out.
The Amplitude top menu with the export CSV button called out.

  1. Open the file. The second column is user_id. If you mapped user_id to the LaunchDarkly User Key, any user without a value in this column is not included in the LaunchDarkly segment.

Viewing synced Amplitude cohorts in LaunchDarkly

You can view your synced Amplitude cohort as a segment in LaunchDarkly. It appears in the Segments tab with the Amplitude logo in its name:

The Segments dashboard with the Amplitude-driven segment called out.
The Segments dashboard with the Amplitude-driven segment called out.

Click into that segment to see details about its targeting:

The synced segment's details screen.
The synced segment's details screen.

You can't edit rules for a Big Segment synced with an Amplitude cohort because they are managed by Amplitude.