Experiment on custom Unit ID types

In some cases, you may want to randomize experiment bucketing using a custom Unit ID instead of the default userID or Statsig-generated Stable ID. For example, if you run a task management tool for companies and want to experiment on company-wide behaviors, you might use companyID as the Unit ID. Using companyID ensures all users from the same company get the same experience, so you can measure overall productivity impacts at the company level.

Custom ID types allow for this flexibility in your experiments and feature gates, enabling you to randomize and control rollouts based on any identifier you need.

When to use custom Unit IDs

• Organization-wide experiments: Group users by companyID for company-wide consistency.
• Session-based experiments: Use a session or device ID to control the experiment within a specific session.
• Group-level rollouts: Target teams, regions, or other specific cohorts using a relevant ID type.

Follow these three steps to set up an experiment with a custom Unit ID. The following examples use companyID, but you can replace it with any ID relevant to your use case.

Step 1: Add companyID as a Custom Unit ID

1. Log into the Statsig Console: Head over to Statsig Console and navigate to Project Settings.

2. Find Custom Unit IDs: Under Manage Account > Info, look for the Custom Unit IDs section.

   

3. Add a New Custom Unit ID:

   • Click the Edit button.
   • Enter companyID as the new ID type and provide a description.
   • Save the changes.

   

After adding a custom Unit ID, you can use it across all Statsig configurations: experiments, gates, layers, dynamic configs, and autotunes. You only need to configure it once per project. Statsig then makes the custom Unit ID available for targeting and analysis across experiments, feature flags, and dynamic configs.

Step 2: Select companyID as the ID Type in Your Experiment

1. Create a New Experiment:

   • Navigate to Experiments+ in the Statsig Console.
   • When setting up a new experiment, find the ID Type dropdown and select companyID.

   

2. Complete Experiment Setup:

   • Finish configuring your experiment as you would for any user-level experiment.
   • Define your hypothesis, metrics, and target audience.

   After completing the setup, click Save.

Choosing the right custom Unit ID ensures Statsig places all users with the same companyID in the same experiment group, making it easier to measure performance at the group level.

Step 3: Provide companyID in the Statsig SDK

To use the custom Unit ID in your application, provide it when initializing the Statsig SDK. The customIDs field in the Statsig user object lets you pass the companyID (or any other custom ID) along with the usual user information.

Example (JavaScript):

var user = {
    userID: "some_user_id",       // Standard user identifier
    customIDs: {
        companyID: "some_company_id"  // Custom ID for grouping
    },
    // Other attributes (optional)
    email: "user@example.com",
    appVersion: "1.0.0"
};

// Initialize the Statsig Client
const client = new StatsigClient(sdkKey, user);

await client.initializeAsync();

• customIDs field: This allows you to pass a dictionary of custom IDs, including companyID, to ensure the experiment targets users based on that ID.

After providing the necessary IDs in the SDK, you can start logging events and fetching experiment configurations based on the custom Unit ID.