Segments synced from external tools

Read time: 4 minutes

Last edited: Oct 31, 2023

Syncing segments is an Enterprise feature

Syncing segments from external tools 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 segments that sync with an external tool.

A synced segment is a segment that is backed by an external data store. Synced segments can support massive numbers of targets. The exact number is only limited by the data store you configure.

All of the contexts within a synced segment must be of the same context kind. All of the segment's included targets will be associated with that context kind.

Big Segments include synced segments and some list-based segments

You may be familiar with the concept of a "Big Segment," which is a term we previously emphasized in the LaunchDarkly documentation and user interface to describe some segments.

A Big Segment is a segment that is either a synced segment, or a list-based segment with more than 15,000 entries that includes only one targeted context kind. LaunchDarkly uses different implementations for different types of segments so that all of your segments have good performance.

Most of the time, you don't need to keep track of whether your segment is a Big Segment or not. However, you may need to monitor this if you are working with the REST API. Some of the REST API endpoints are specific to Big Segments. To learn more, read Segments in the API documentation.

Prerequisites

To use synced segments, you must meet the following prerequisites:

Configure server-side SDKs to use synced segments

How you need to configure your SDKs depends on what kinds of SDKs you use:

Server-side SDKs: You must use an SDK version that supports synced segments.
Client-side SDKs: All client-side SDKs support synced segments by default. No additional setup is required.

Configure your SDK: Big Segments

Configure the Relay Proxy to use synced segments with server-side SDKs

How you need to configure the Relay Proxy depends on what kinds of SDKs you use:

Server-side SDKs: You must use the Relay Proxy and it must be configured to use synced segments.
Client-side SDKs: The Relay Proxy is not required. However, if you do use the Relay Proxy, you must configure it to use synced segments. To learn more, read Using the Relay Proxy.

Configure an access token

For segments that are synced with external tools, in most cases you must provide the external tool with a LaunchDarkly access token that has appropriate permissions in 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.

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

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

[
  {
    "effect": "allow",
    "actions": [
      "createSegment",
      "updateIncluded"
    ],
    "resources": ["proj/*:env/*:segment/*"]
  }
]

To learn more, read Custom roles and Segment actions.

Updating synced segments

Synced segments are created by external tools prior to the first sync. After they are created, you can update the synced segment targets only in the external tool. You can update details such as name and description directly in LaunchDarkly.

Updating synced segment targets

To change the contexts that a synced segment is targeting, update the segment membership in the external tool. For example, if your segment is synced from an Amplitude cohort, update the segment membership in Amplitude.

Updating the segment, cohort, or audience in the external tool might be something you do manually in that tool. Or, it might happen when a customer performs an action in your application, for example, if your customer clicks an "Enroll in beta" button.

After the segment is updated in the external tool, the changes automatically sync to LaunchDarkly, and any flags in LaunchDarkly that use this synced segment in their targeting rules automatically use the updated segment. The exact length of time from when a customer is added to a segment, cohort, or audience in the external tool to when the segment is synced with LaunchDarkly varies depending on the external tool. We have found that this typically takes around 30 seconds, but is dependent on the external tool, as well as other factors such as network conditions.

Updating synced segment details

When you create a synced segment, the external tool provides the segment's name, key, and description. In some cases, you may want to update the name and description to something more meaningful to your team. Additionally, you may want to add one or more tags to the synced segment.

To update a synced segment's name or description:

Navigate to the segment detail page for the synced segment you want to update.
Select the Settings tab.
Edit the Name, Description, and Tags.
Click Save.

Subsequent targeting syncs will not override any manual changes to the synced segment's name, description, or tags. As with all segment types, you cannot modify a synced segment's key.

Supported external tools

LaunchDarkly supports syncing segments from the following tools: