User (StatsigUser) Object

Introduction to the StatsigUser object

The StatsigUser object is the sole input you provide to SDKs to target gates and assign users to experiments. To target on an attribute, add it to your user object. Assembling this data is an important part of SDK setup. Provide as much information as practical, because each additional field can enrich your analyses and expand targeting options. Statsig also infers some information about each user from other traits (for example, Statsig resolves IP addresses into countries).

Usage example in Node.js

//Create a user object
const user = new StatsigUser({ userID: "12345", email: "vincent@statsig.com"});
//Use it in getExperiment()
const my_experiment = statsig.getExperiment(user, "my_experiment_name") //<- any attribute you pass, you can target on

I passed that attribute before: why do I need to pass it again?

Historical attributes can't be used for targeting or gate/experiment evaluation at runtime. Statsig evaluates gates and experiment buckets based only on the information you provide at the time of the check. Millisecond evaluation performance depends on having all information available at request time, rather than querying historical data or storing large amounts of state in memory.

User attributes

import { StatsigClient, StatsigUser } from '@statsig/js-client';

const user: StatsigUser = {
  userID: 'a-user',
  customIDs: {
    stableID: 'my-custom-stable-id',
  },
};

const client = new StatsigClient('client-sdk-key', user);
await client.initializeAsync();

Have sensitive user PII data that shouldn't be logged?

The StatsigUser object includes a privateAttributes field, which is a key/value dictionary for setting private user attributes. Statsig uses attributes in privateAttributes only for evaluation and targeting, and removes them from any logs before sending them to the Statsig server.

For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com" but don't want to log email addresses to Statsig, add the key-value pair { email: "my_user@statsig.com" } to privateAttributes on the user.

Time-based conditions

All SDKs (server and client-side) support Unix timestamps in milliseconds to evaluate time-based conditions (After time, Before time). Convert your DateTime field to a standard format before evaluation.

Statsig has added ISO timestamp support to some server SDKs:

• java-server SDK v1.6.0 and later: supports DateTime fields in ISO_INSTANT format
• go SDK v1.12.1 and later: supports DateTime fields in RFC3339 format
• python SDK: supports epoch time in seconds. The time.time() function may include sub-second components, so round the value to an integer.

For server SDKs supported by server core (Java, Python, PHP, Rust, Node), ISO timestamp support covers:

• DateTime fields in ISO_INSTANT format
• DateTime fields in RFC3339 format

Why is an ID always required for server SDKs?

In server SDKs, a StatsigUser with a userID (or customID) is required for checkGate, getConfig, and getExperiment. Pass the user ID whenever it's available: users get a stable experience, and events are attributed to the correct users so you can accurately measure downstream metrics.

Guidance for cases where you can't pass an ID:

1. On/off feature gates or non-percent-based rules (such as country targeting): Pass any non-empty identifier or a hardcoded string. If you do not have the actual user ID, use a random ID under 100 as a placeholder. Do not use a purely random ID, because this prevents event deduplication, inflates event volume, and increases your Statsig bill.

2. Partial rollout with regression checks before full rollout: Pass an ID in every checkGate, getConfig, and getExperiment call, as well as in any logEvent calls. Without an ID, Statsig cannot attribute logged events to the correct users or calculate metrics accurately.

3. A/B experiment to decide whether to ship a feature: Pass persistent user IDs, for the same reason as case 2.

4. No logged-in user (for example, optimizing the login flow): Set a stable identifier as a cookie or in local storage and pass it with each Statsig call. Client SDKs provide a stable ID automatically.

Pass all IDs when you have them

A common mistake is accidentally exposing users without a userID to a user-ID-based experiment. All such users are bucketed into the same group (wherever the null userID hashes to), which skews results. If you run experiments on multiple ID types, pass every available identifier.