Identify Users

Why identify users?

When you run an experiment, roll out a feature, or log events, Statsig needs to know who the user is to determine:

• Targeting: whether a feature gate should pass or fail for a given user
• Experiment bucketing: which group a user belongs to
• Analytics: how many unique users triggered an event

Pass a User Object to Statsig SDKs to provide this information. The User Object is also required for experiment analysis: users are allocated to the test or control group by an ID, and the Statsig stats engine uses the same ID on the users' events to calculate metric differences between test and control groups.

Basic user object

Start by defining a basic user object:

{
  "userID": "u_123",       // required for most setups
  "email": "user@example.com" // optional
}

Identifying users in client SDKs

In client SDKs, the SDK is initialized for a single User Object at any one time. If you call a method like checkGate or getExperiment before the SDK is initialized, results are incorrect. You'll also see warnings in the Statsig Console on the diagnostics tab of any gate or experiment. Initialization requires a network request, which you start by calling the initialize() method, or in React, useClientAsyncInit().

In client apps with asynchronous logic, wait for initialization to complete before checking a gate. For example, in React:

export function App() {
  const { client, isLoading } = useClientAsyncInit(
    YOUR_CLIENT_KEY,
    user={ userID: "u_123"} // user object
  );

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <StatsigProvider client={client}>
      <MainApp />
    </StatsigProvider>
  );
}

If you initialize with a given user object and the user object changes (for example, the user logs in and now has a userID), call the updateUser method to refresh values from the Statsig server. For example, in React:

const { user, updateUserSync } = useStatsigUser();

return <div>
  <p>Current User: { user.userID }</p>

  <button onClick={() => updateUserSync({userID: 'some-other-user'})}>
    Update User
  </button>
</div>;

If you don't update the user before checking gates or experiments, gates and experiments evaluate using the previous user object, which can produce unexpected results.

Any attribute added to the user object is targetable in the Statsig console. To target users based on email, companyID, or other attributes, add those attributes to your user object.

Identifying users in server SDKs

In server SDKs, pass a User Object with each evaluation or event call, such as logEvent, checkGate, or getFeatureGate. The server SDK holds the necessary rules in memory for evaluation. Pass all attributes needed to evaluate your gate or experiment on every call. Statsig SDKs don't store or enrich attributes from previous calls.

Example (Node.js)

import { Statsig } from "statsig-node";

await Statsig.initialize("<YOUR_SERVER_KEY>");

const user = { userID: "u_123", custom: { plan: "premium" } };

const gate = await Statsig.checkGate(user, "beta_feature");
if (gate) {
  console.log("Gate passed");
}

Enriched attributes

Statsig enriches the user object with useful attributes to expand targeting options. Examples of what Statsig can enrich:

• stableID: an anonymous identifier which identifies a unique device on client SDKs
• country: derived from IP or device locale
• appVersion: pulled from mobile SDKs
• browser / OS: captured from user agent
• and more...