Building a synced segments integration

Overview

This guide explains how LaunchDarkly partners can use the integration framework to build a synced segments integration.

Synced segments allow partners to sync a segment, or set of contexts, to LaunchDarkly. Contexts are people, services, machines, or other resources that encounter feature flags. LaunchDarkly members use segments to perform targeted rollouts of features. To learn more, read Contexts and Segments.

As a partner, a segment may be called a “cohort” or similar in your application. You can develop an integration that syncs cohort members from your application to LaunchDarkly, using a LaunchDarkly REST API endpoint. The endpoint receives a JSON payload with the unique identifiers of the cohort members and performs data translation using a specified parser.

With this endpoint, you can add or remove a list of contexts from a cohort, using any of three different options for a JSON payload. You will need the cohort name and ID, and configuration details, such as the LaunchDarkly client-side ID.

By the end of this guide, you as a LaunchDarkly partner should have the information you need to create a synced segments integration.

Integration requirements

To complete your integration, you will need:

• An integration framework manifest listing, that you will create as part of this guide
• Publicly hosted documentation of your integration, that includes how a LaunchDarkly member should scope their API access token
• A private Loom video or other recorded walkthrough of the integration
• A grayscale SVG logo that will be displayed in the LaunchDarkly Integrations documentation and in the LaunchDarkly user interface

Build an integration

To build an integration, make sure you meet the prerequisites. Then follow the steps outlined on the Getting started page.

The Getting started page explains many of the following steps in detail:

1. Fork the LaunchDarkly Integration Framework repository.
2. Create a new directory.
3. Determine how to send your cohort payload to LaunchDarkly, and what response you require.

• This step is unique to creating a synced segment integration. To learn more, read Methods of sending cohort payload, below.

4. Create an integration manifest and add image assets.

• Include details of your cohort request and response payload in the capabilities/syncedSegments section of the manifest. For an example of a completed manifest, read the Amplitude synced segment manifest. To learn more about the image assets, read Image assets, below.

5. Collect integration configuration data.
6. Define the integration’s capabilities.

• For this integration, define the syncedSegment capability. To learn more, read Manifest details, below.

7. Validate the integration.

• For this integration, you can test locally using the LaunchDarkly integration validation server.

8. Create end-user documentation and README.
9. Submit the integration.

• Email ecosystem@launchdarkly.com to schedule a final walkthrough.

The following sections provide configuration guidance specific to synced segments integrations.

API details

To sync cohort members from your application to LaunchDarkly, use this LaunchDarkly REST API endpoint that receives a JSON payload and performs data translation using a specified parser.

Here’s how to structure your request to sync cohort members:

Methods of sending cohort payload

As a partner, you have three options for how to send the cohort or audience payload to LaunchDarkly:

• Boolean property: send a single cohort member. Use a boolean property to indicate whether a member is added or removed. When the property is true, it means a member should be added. When the property is false, it means the member should be removed. To review an example, read Boolean property.
• Named arrays of cohort entries: send add and remove arrays containing a list of cohort members to add and remove. The same memberArrayParser will be used to parse information from both arrays. To review an example, read Separate named arrays.
• Single property: send a single action property for the entire batch of cohort members, indicating whether they should all be added or removed. To review an example, read Single property.

To learn more, read Synced segments capability.

Manifest details

Each LaunchDarkly partner integration requires an integration manifest. For general information on how to create this, read Defining an integration manifest.

When you create a synced segment integration, your manifest must also include a capabilities key with a nested object with the key syncedSegment:

1
"capabilities": {
2
    "syncedSegment": {
3
      ...
4
  }
5
}

To review an example, read the Amplitude synced segment manifest.

To learn more about the supported fields, read the Synced segments capability documentation. You can also find information on the fields supported by the requestParser directly in the Integration Framework manifest schema.

Image assets

All partner integrations have the partner logos appear in the LaunchDarkly Integrations documentation and in the LaunchDarkly user interface on the Integrations list. To learn more, read SVG logo files.

Additionally, all synced segment partner integrations have the partner logos appear in the LaunchDarkly Segments list and on the segment details page. The logo is pulled from the square key of the icons object in your integration manifest.

Conclusion

This guide describes the process of building a synced segment integration. To learn more about building your own integrations, read Building partner integrations.