Skip to main content

Experiment on custom Unit ID types

Sometimes you may want to randomize experiment bucketing based on a Unit ID other than the user ID, or the Statsig generated Stable ID. For example, say your company builds tasks management tools for other companies to use - you need to run an experiment to test different experiences for a tool, but you want to make sure everyone in the same company gets the same experience, so that you can understand how the different experiences differ in improving overall productivity for a company. In this case, you want the Unit ID on your experiment to be companyID instead of userID, so that every user with the same companyID is in the same group for the experiment.

It takes just 3 easy steps to set up an experiment like this. Below we will use companyID as an example, but you can replace it with any name that suits your use case.

Note that the same steps also work for feature gates, and doing so on feature gates allow you to partially rollout a feature using custom Unit IDs.

Step 1 - Add companyID as a new custom Unit ID in your project settings​

Log into the Statsig console at https://console.statsig.com/ and navigate to Project Settings in top-right panel, and then find "Custom Unit IDs" section under the "Basic Settings" tab.

Screen Shot 2022-06-26 at 10 53 06 AM

By default, every project has "User ID" and "Stable ID" types, but you can add additional ID types by clicking "Edit" and adding the new ID type and description:

Screen Shot 2022-06-26 at 10 56 17 AM

Once the new ID type is added, you can use it for all new experiments going forward - no need to repeat this step again!

Step 2 - Select companyID as the ID Type for your new experiment​

When you create the experiment, simply select companyID under the "ID Type" dropdown:

Screen Shot 2022-06-26 at 10 58 11 AM

Now go ahead and finish the rest of the set up as you would for any user-level experiment.

Step 3 - Provide companyID on the user object when using Statsig SDK​

Now all you need to do is making sure companyID is provided when initializing any client SDK, or when getting the experiment configs and logging events if using a server SDK. The Statsig user object has a top level field customIDs that is a dictionary of key-value pairs representing the ID type and value for the user:

var user = {
    userID: "some_user_id",
    customIDs: {
        companyID: "some_company_id",
        ...
    },
    ...
}

That's it! Now go ahead and start your experiment!