Synced segments capability

Overview

This topic explains how to use the synced segments integration framework capability.

Using synced segments

In LaunchDarkly, segments are lists of contexts that are used to manage flag targeting behavior in bulk. As a partner, you can use the synced segments integration framework capability to create and synchronize resources contained in external services, such as Amplitude cohorts or Segment Audiences, with LaunchDarkly segments. To learn more about segments, read Segments.

The syncedSegment capability consists of a request parser. The properties of the parser describe the information about the segment to create or update.

Many of the parser properties are required, for example, the properties that specify the name and ID of the cohort you are updating.

Then, you have three options for how to send cohort information:

• Use a boolean property to indicate whether a member should be added or removed
• Use separate named arrays, one for members being added and one for members being removed
• Use a single action property to indicate whether the set of members should be added or removed

The combination of the the request parser's memberArrayPath, addMemberArrayPath, removeMemberArrayPath, and memberArrayParser properties describe which option you are using and where the integration framework can expect to find the cohort information.

Request parser properties

The following properties specify the requestParser:

The following properties specify the embedded memberArrayParser:

Examples

The following sections contain examples of different types of request bodies and the manifest definitions of synced segment capabilities that would successfully parse them.

Boolean property

In the request body, use a boolean property to indicate whether a member is added or removed:

{
      "environmentId": "abcd123",
      "contextKind": "organization",
      "batch": [
        {
            "userId": "user-1234",
    		"cohortName": "Segment 1234",
        	"cohortId": "segment-1234",
        	"cohortUrl":  "https://example.com",
        	"value": true
        },
        {
            "userId": "user-5678",
            "cohortName": "Segment 1235",
            "cohortId": "segment-12345",
            "cohortUrl":  "https://example.com",
            "value": false
        }
      ]
    }
COPY

Separate named arrays

In the request body, use separate named arrays containing lists of members to add and remove. In the manifest, the memberArrayParser describes how to parse the addMemberArrayPath and removeMemberArrayPath arrays:

{
      "id_token": "CustomerIdToken",
      "action_type": "segment.users.sync",
      "customer_config": {
        "fields": [
          {
            "field_id": "workspace",
            "field_display_name": "Workspace",
            "value": {
              "id": "abcd123",
              "display_name": "Workspace 1"
            }
          }
        ]
      },
      "data": {
        "segment": {
          "id": "segment-1234",
          "name": "Segment 1234"
        },
        "add": [
          {
            "id": "user-123"
          },
          {
            "id": "user-456"
          }
        ],
        "remove": [
          {
            "id": "user-789"
          },
          {
            "id": "user-101112"
          }
        ]
      }
    }
COPY

Single property

In the request body, use a single action property for the entire batch to indicate whether the batch should be added or removed:

{
  "action": "add_members",
  "parameters": {
    "integration_project_id": "abcd123",
    "integration_cohort_name": "Segment 1234",
    "integration_cohort_id": "segment-1234",
    "integration_cohort_description": "description",
    "integration_session_id": "integration_session_id",
    "members": [
      {
        "email": "user-1234@customer.com",
        "integration_distinct_id": "user-1234",
        "first_name": "John",
        "last_name": "Doe",
        "phone_number": "xxx-xxx-xxxx"
      },
      {
        "email": "user-5678@customer.com",
        "integration_distinct_id": "user-5678",
        "first_name": "Jane",
        "last_name": "Doe",
        "phone_number": "xxx-xxx-xxxx"
      }
    ]
  }
}
COPY

Response codes and custom responses

By default, LaunchDarkly returns one of the following response codes:

• 204, success
• 400, parsing problem
• 403, unauthorized
• 409, conflict
• 429, rate limited, read Rate limiting for details on the X-Ratelimit-Reset header
• 500, internal error

If you require a custom response, you can specify that with the jsonResponseBody in the syncedSegments object in your integration manifest. The jsonResponseBody supports Handlebars templating directly in the manifest.

Here is an example manifest excerpt that specifies a jsonResponseBody:

"capabilities": {
        "syncedSegment": {
          "requestParser": {
            ...
          },
          "jsonResponseBody": "{ \"environmentId\": \"{{requestBody.environmentId}}\", \"projectKey\": \"{{projectKey}}\", \"envKey\": \"{{environmentKey}}\", \"segmentKey\": \"{{segmentKey}}\", \"segmentUrl\": \"{{segmentUrl}}\", {{#if errorMessage}}\"status\":\"failure\", \"error\": {\"message\": \"{{{errorMessage}}}\", \"code\": {{statusCode}} }{{else}}\"status\": \"success\"{{/if}} }"
        }
      }
COPY

Testing

After you have an initial implementation of your synced segments capability, you can test it using LaunchDarkly's integration validation server. To learn more, read Validating an integration.