Build your first Device-level Experiment

When you cannot identify a user via their user ID, device-level experiments allow you to randomize experiments based on a consistent identifier for the user's device. While Statsig can automatically generate a stable ID, it's recommended to use 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 to Stable ID.

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, just like you would 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. Starting with a smaller rollout is often recommended until you're confident in the new variant.

   

6. Save and Start: Once everything is configured, 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, the next step is to integrate it into your client application using one of Statsig’s SDKs.

Here’s an example of how to initialize the SDK in a Javascript application. It's recommended to use your own cookie or logged-out ID as the userID when available. If you don't have any identifier, the client SDK will automatically generate a stable ID.

Example (JavaScript):

const user = {
    userID: getCookieOrLoggedOutID(), // Use your own identifier when possible
    ip: "192.168.1.101",
    appVersion: "1.0.0",
    custom: {
        promoCode: "New30Off"
    }
};

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

await client.initializeAsync();

Key points:

• User ID: Prefer using your own cookie or logged-out ID as the userID when available.
• Fallback to Stable ID: If you don't have any identifier, Statsig will automatically generate a stable ID.
• User attributes: You can pass additional attributes like ip, appVersion, and custom properties for experiment targeting.

Tip: If your app collects other relevant attributes (e.g., device type, region), pass them in the user object to improve experiment precision.

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

If a user signs in or creates an account, you can update the user info using the updateUserAsync() method. This ensures the user is bucketed into the appropriate user-based experiments without affecting their device-level experiment evaluation.

Example (JavaScript):

user.userID = realUserID;
user.email = signUpEmail;

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

Note: Updating the user with a userID will only impact user-level experiments and feature gates. Device-level experiment evaluations will remain based on the stable ID.

---