# 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. Statsig also requires the User Object for experiment analysis. Statsig allocates users to the test or control group by an ID. The Statsig stats engine then uses the same ID on the users' events to calculate metric differences between the test and control groups.

## Basic user object

Start by defining a basic user object:

{% codetabs %}
```jsx Basic User Object
{
  "userID": "u_123",       // required for most setups
  "email": "user@example.com" // optional
}
```
{% /codetabs %}

Add more attributes when you need finer targeting. Refer to [Enriched attributes](#enriched-attributes) for details.

## Identifying users in client SDKs

In client SDKs, you initialize the SDK for a single User Object at any one time. If you call a method like `checkGate` or `getExperiment` before you initialize the SDK, results are incorrect. You 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:

{% codetabs %}
```jsx React Example
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>
  );
}
```
{% /codetabs %}

The user object can change after initialization: for example, the user logs in and now has a `userID`. When the user object changes, call the `updateUser` method to refresh values from the Statsig server. For example, in React:

{% codetabs %}
```jsx Update User
const { user, updateUserSync } = useStatsigUser();

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

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

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)

{% codetabs %}
```jsx Node.js Example
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");
}
```
{% /codetabs %}

## 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...

To learn about all available fields (including `custom` attributes, `customIDs`, and `privateAttributes`), go to the [StatsigUser object](https://docs.statsig.com/sdks/user) docs.