Segment

Enabling the Segment integration for Statsig allows 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.

Supported Segment event types

• Track
• Page
• Group
• Screen
• Identify*

Benefits of using the Segment integration

The Segment integration has several benefits over other methods of event ingestion:

• Customers ingesting data with Segment can quickly populate Statsig with metrics and can typically get started within a day.
  • Customers only need to use Statsig's assignment SDKs (gate/experiment allocation), which simplifies code and engineering workflows.
  • Additional logging can be done through the event logging SDKs, but requires additional code orchestration and a collection window.
• With event filtering you can control which events are ingested and make billing more predictable.
• If you have Segment Replay, you can forward up to 7 days of historical events to Statsig for analysis.

Configuring inbound events into Statsig

To send events collected from Segment into Statsig, you must configure the Statsig Destination within your Segment account:

Using OAuth

The easiest way to connect Statsig to Segment is through OAuth.

1. To get started, within the Statsig Console, go to project settings → integrations → Segment → Enable

2. Click “Configure Segment OAuth”

   

3. Select the workspace and source that will send data to Statsig. Click “Allow”:

   

4. After the integration is enabled, you can configure event filtering and map additional identifiers. This is useful for mapping device-level identifiers and anonymousIds generated from Segment. Statsig recommends creating a custom ID called segmentAnonymousId and mapping the anonymousId from Segment to it.

   

Manual configuration

If you are unable to connect to Segment through OAuth, you can manually connect Statsig to Segment by configuring the following:

1. Within the Segment App, navigate to your Destinations, and select "Add Destination"

2. Search for “Statsig” and select the destination

   

3. Select "Statsig" from the list of available integrations, and then select sources that will send data to Statsig.

   

4. You must provide a Statsig Server SDK key. You can copy an existing server key or create a new one from the Statsig console settings.

   • Create or copy a server SDK key

     

     

   • Put your Server Secret Key in the “API Key” field in the Statsig Destination

     

5. To set up mappings, you must enable the Segment Integration in Statsig. Go to the Statsig Console, then Project Settings, then the Integrations tab, then Segment, and click Enable:

   

   • After the integration is enabled, you can configure event filtering and map additional identifiers. This is useful for mapping device-level identifiers and anonymousIds generated from Segment.

     

6. Verify that Statsig is receiving events using the Segment Event Tester.

   • In the event tester, send a test event to verify any filtering and mapping you have set up:

     

   • In the your Statsig Console Events Explorer, click on the test event in the log stream and verify the event:

     

   • In this example, the anonymousId is mapped to Statsig’s segmentAnonymousId based on the above mapping. Statsig infers the User ID from the Segment userID field.

     

7. As your Segment events flow into Statsig, you see a live Log Stream in the Metrics tab in the Statsig console. You can click one of these events to see the details logged as part of the event.

   

Working with users

User IDs and custom IDs

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

Anonymous users

Mapping anonymous users

Experimenting on anonymous traffic

import { StatsigClient } from '@statsig/js-client';

await Statsig.initialize(
  "client-sdk-key",
  
);
const client = new StatsigClient(sdkKey,
  {
    userID: "some_user_id",
    customIDs: {
      segmentAnonymousId: analytics.user().anonymousId()
    }
  },
  { environment: { tier: "production" } }
);

Example mapping flow

Refer to the following diagram for an overview of mapping anonymousIds in Segment to a custom ID representing anonymous users in Statsig:

1. Initialize the Statsig SDK with your Statsig User, which contains an optional userID value and a customID that you've created in the Statsig UI - segmentAnonymousId in this example.
2. As you orchestrate features/experiments, Statsig associates this user to a variant using the unit of randomization chosen. For anonymous users, Statsig uses segmentAnonymousId.
3. Your existing Segment implementation tracks user traffic and associates anonymous users to the top-level field anonymousId.
4. This anonymousId is mapped in Statsig (to segmentAnonymousId), properly associating the identifier used in experiment exposures to the same identifier used to track user actions.

Syncing Statsig Segment ID lists with Segment Engage Audiences

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.

After you complete these steps, Statsig syncs your Segment Audience, and you can target those users for features you develop or experiments you run.

Custom properties

{
  ...
  properties: {
    "statsigCustom": [ "isVIP", "true", "marketing_campaign", "abx343", ...]
  }
}

Configuring outbound events to Segment

To export your Statsig events to Segment,

1. In your Segment app, add a new source → search for Statsig → click Next

2. Name your source → Create Source → click Done:

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,
  },
},

Environments

By default, all events are treated as "production" events, but you can differentiate your event traffic by specifying the environment the events are coming from. This prevents non-production data from appearing in your production metrics.

To include the environment tier, add it to the properties object of your event. The required format is below:

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

Working with Segment metrics in the Statsig UI

Segment events are piped into Statsig and are accessible in the metrics console like any other event. These metrics are also available as monitoring metrics in your feature gates and experiments, so you can use your existing metric collection through Segment with Statsig's experimentation platform.

These metrics appear in pulse results among other monitoring metrics:

Filtering events