# Build your first Device-level Experiment

> For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

Device-level experiments randomize assignment on a consistent identifier for the user's device instead of a user ID, so you can test users you can't identify through a login. Statsig generates a stable ID automatically, though it recommends using your own cookie or logged-out ID when possible. Use device-level experiments for anonymous or first-time users and to keep the same experience on a device regardless of sign-in status.

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](https://console.statsig.com/) 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.

   ![Stable ID Setup](https://docs.statsig.com/images/tutorials/device-level-experiment/device-level-stable-id.png)
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"`.

   ![Experiment Groups](https://docs.statsig.com/images/tutorials/device-level-experiment/device-level-groups.png)
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.

   ![Allocation Panel](https://docs.statsig.com/images/tutorials/device-level-experiment/device-level-allocation.png)
6. **Save and Start**: After 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](https://docs.statsig.com/guides/experiment-on-custom-id-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)

```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();
```

> **Info:**
>
> 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

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)

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

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

> **Note:**
>
> When you add userID after login, user-level experiments and gates can target and evaluate using userID. _Device-level_ experiment evaluations remain based on stableID (or deviceID) and don't change when you add userID, as long as you continue to pass that identifier as well! This preserves consistency of device-level bucketing.

---