Segment

Overview

Enabling the Segment integration for Statsig will allow Statsig to pull in your Segment events. This allows you to run your experiment analysis on Statsig with all of your existing events from Segment without requiring any additional logging.

When Statsig receives events from Segment, these will be visible and aggregated in the Metrics tab in the Statsig console. These events will automatically be included in your Pulse results for A/B tests with Statsig's feature gates as well as all your Experiment results.

Configuring Incoming Events

To ingest your events from Segment,

1. In the Segment App, click Add Destination in the Destinations catalog page.
2. Search for “Statsig” in the Destinations Catalog, and select the “Statsig” destination.
3. Choose which Source should send data to the “Statsig” destination.
4. From the Statsig dashboard, copy the Statsig "Server Secret Key”.
5. Enter the Statsig “Server Secret Key” in the “Statsig” destination settings in Segment.
6. On the Statsig Integration page enable the Segment integration.
7. As your Segment events flow into Statsig, you'll see a live Log Stream in the Metrics tab in the Statsig console. You can click one of these events to see the details that are logged as part of the event.

User IDs and Custom IDs

Statsig automatically detects the event and userId fields that you log through your Segment track event. If you're running an experiment with the user as your unit type, this userID should match the user identifer that you log with the Statsig SDK, for example when you expose the the user to a Statsig feature gate or experiment.

If you're using a custom ID as the unit type for your experiment, you can provide this identifier using the key statsigCustomIDs as part of the Segment properties field as shown below.

JSON Body

{
  ...
  properties: {
    "statsigCustomIDs": [ "companyID", "<this_company_id>"]
  }
}

The statsigCustomIDs field in properties should be an array, where the even index is the name of the user ID type and the odd index is the value of the previous element in the array. Assuming you've created this custom ID type on Statsig (under ID Type Settings in your Project Settings), Statsig will automatically recognize these custom identifiers to compute your experiment results appropriately.

Custom ID Mapping

The Segment integration also allows the mapping of top level fields to Statsig Custom IDs. To do this, visit the Segment panel on the Statsig Integrations page and look for the "Map Identifier" section. Here you can choose fields you would like mapped to a Custom ID.

For example, if you're running experiments on anonymous users, you can use Segment's anonymousId as the unit of randomization. First, you will want to add a new customer identifer to Statsig. For this example, we'll call our new custom ID segmentAnonymousID. Then, when initializing the Statsig SDK, if you have access to the Segment anonymousId you will want to pass it to Statsig as a custom ID. For example, your Statsig initialization may look like this:

const Statsig = require("statsig-js");

await Statsig.initialize(
  "client-sdk-key",
  { userID: "some_user_id" },
  { customIDs: { segmentAnonymousID: "some_segment_anonymous_id" } } 
);

You can access Segment's anonymousId using analytics.user().anonymousId() as outlined in the Segment docs here. It's important to note, that the Segment SDK may initialize after Statsig SDK, and the anonymousId may not be available in that scenario. It's important to check this in your specific implementation. If you're using vanilla javascript, you may want to wait for the anonymousId from the Segment SDK after initialization and call the updateUser() method on the Statsig SDK to update this ID.

Then, you will map the anonymousId to the stableId (or another CustomID you're using) in the Segment integration modal in Statsig.

⚠️ Warning: values passed in properties.statsigCustomIDs will take precedence over mapped identifiers below.

Environments

By default, all events are treated as "production" events, but you can also differentiate your event traffic by specifying the environment that the events are coming from. This allows you to avoid non-produciton data making it into your production metrics.

If you would like to include the environment tier, you can add it to the properties object of your event. The required format is below:

{
  ...
  "properties": {
   "statsigEnvironment": {
        "tier": "staging"
    }
  }
}

To learn more about environments see Using Environment.

Syncing Statsig Segment ID Lists with Segment Personas Audiences

By using Segment Personas Audiences you are able to maintain a list of users that can be used for targeting using Statsig Feature Gates. To configure this:

1. Create a Statsig ID List Segment on the Statsig Console.
2. Follow the Segment guide for Audiences to create a new Audience and choose Statsig as a Destination. The audience_key must match the ID of the Statsig ID List Segment created.

Once these steps have been completed, your Segment Audience will be synced, and you will be able to target those users for features you develop or experiments you run.

Configuring Outbound Events

To export your Statsig events to Segment,

1. Create an HTTP API source on the Segment dashboard.

2. Select your HTTP API source and select the 'Settings' tab, then on the side bar, select API Keys.

   

3. Locate your Write Key and copy it.

4. Log into the Statsig console and navigate to the Integrations page.

5. Click on the Segment card and switch to the Outbound tab, paste the Write Key into the API Key text box shown below, and click Enable.

Outbound event schema

Statsig exports log events and exposure events to segment as track events:

{
    type: 'track',
    userId: event.userID,
    timestamp: Number(event.timestamp),
    event: event.eventName,
    context: {
      user: event.user,
      value: event.value,
      metadata: event.metadata,
      library: {
        name: 'statsig',
        version: '1.0',
      },
      stableID: event.statsigMetadata.stableID // stableID, if you are relying on that for anonymous users
    },
    properties: {
      value: event.value,
      metadata: event.metadata,
    },
  };
}

Config Change events follow this schema:

{
  userId: statsigUserID,
  timestamp: Date.now(),
  event: 'statsig::config_change',
  context: {
    library: {
      name: 'statsig',
      version: '1.0',
    },
  },
  properties: {
    author: author,
    configName: configName,
    description: changeDescription,
    environment: environment,
  },
},

Filtering Events

You can customize which events should be sent and received via Segment using Event Filtering