Build your first Device-level Experiment

When you can't identify a user through a user ID, device-level experiments let you randomize experiments based on a consistent identifier for the user's device. Statsig can automatically generate a stable ID, but Statsig recommends using your own cookie or logged-out ID when possible.

Device-level experiments are ideal in scenarios such as:

• Anonymous or first-time users: When users haven't signed in yet or are browsing anonymously.
• Cross-device consistency: Ensuring the same experience on the same device, regardless of user sign-in status.

You can implement a device-level experiment almost exactly like a traditional user-level experiment. The key difference is setting the experiment’s ID type. This example uses stableID as the ID type, but you can substitute your own identifier if you have one.

Step 1: Create a Device-level Experiment

1. Log into the Statsig Console: Visit Statsig Console and navigate to Experiments+ on the left-hand sidebar.

2. Create a New Experiment:

   • Click on Create and fill out the name and description of your experiment.
   • Enable the Use Stable ID option during setup.
   • Click Create to proceed.

   

3. Define Experiment Metrics: Add a hypothesis, primary metrics, and secondary metrics in the Scorecard section, the same as for a user-level experiment.

4. Set Groups and Parameters:

   • In the Groups section, define the parameters for your experiment. For instance, you can experiment with a simple boolean parameter like "enabled".

   

5. Set Allocation:

   • By default, the experiment targets 100% of your user base. Adjust the allocation if needed. Start with a smaller rollout until you're confident in the new variant.

   

6. Save and Start: Once you've configured everything, click Save to finalize your experiment. When you're ready to launch, click Start to roll it out.

Step 2: Initialize the SDK in your application

After setting up your experiment in the Statsig console, integrate it into your client application using one of Statsig’s SDKs.

Important:

• Set userID only for authenticated, logged-in users.
• For logged-out or anonymous users, use stableID (Statsig’s auto-generated device ID) or your own custom deviceID to identify the device. Refer to customID types if you have your own deviceID.
• Always pass all known IDs to the SDK. Statsig uses the correct one for evaluation based on the experiment or gate’s ID type.
• If you do rely on stableID, only Statsig client SDKs (javascript, react, mobile, etc) generate it. Server SDKs can't generate this ID for you.
• User attributes: You can pass additional attributes like appVersion, and custom properties for experiment targeting.

Example (JavaScript):

const user = {
    userID: userID: isLoggedIn() ? getLoggedInUserID() : undefined,

    // Optional attributes to help with targeting
    appVersion: "1.0.0",
    custom: {
        promoCode: "New30Off"
    }
};

// Initialize the Statsig Client
const client = new StatsigClient(sdkKey, user, {
  environment: { tier: "production" }
});

await client.initializeAsync();

Step 3 (Optional): Update User Info for Logged-in Users

When a user signs in or creates an account, call the SDK’s updateUser method to attach userID and other logged-in attributes. This enables user-level experiments and gates to evaluate with the authenticated identifier.

Example (JavaScript):

const updatedUser = {
  ...user, // continue to send the deviceID!
  userID: loggedInID,
  email: signUpEmail
};

// Update the user object
await client.updateUserAsync(user);