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,
- In the Segment App, click Add Destination in the Destinations catalog page.
- Search for “Statsig” in the Destinations Catalog, and select the “Statsig” destination.
- Choose which Source should send data to the “Statsig” destination.
- From the Statsig dashboard, copy the Statsig "Server Secret Key”.
- Enter the Statsig “Server Secret Key” in the “Statsig” destination settings in Segment.
- On the Statsig Integration page enable the Segment integration.
- 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.
{
...
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:
- Create a Statsig ID List Segment on the Statsig Console.
- Follow the Segment guide for Audiences to create a new Audience and choose
Statsig
as a Destination. Theaudience_key
must match the ID of theStatsig 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,
Create an HTTP API source on the Segment dashboard.
Select your HTTP API source and select the 'Settings' tab, then on the side bar, select API Keys.
Locate your Write Key and copy it.
Log into the Statsig console and navigate to the Integrations page.
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