Skip to main content

User (StatsigUser) Object

Introduction to the StatsigUser object​

The user(StatsigUser) object is the sole input you provide to SDKs to target gates and assign users to experiments. If you'd like to target on an attribute, you'll need to add it to your user object, so assembling the data is an important part of SDK setup. We recommend providing as much info as practical, as every additional field can enrich your analyses and expand targeting possibilities. Statsig also infers some information about each user based on other traits (for example, we resolve IP Addresses into countries), read on for more details.

Usage Example in Node:​

//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?​

If you want to see a specific user's historical attributes for analytics purposes, you can see that in the statsig console via User Profiles.

However, you cannot use a user's historical attributes for targeting or gate/experiment evaluation at runtime. Statsig evaluates gates and experiment buckets based only on the information you provide when you check something. Statsig's promise of evaluating every gate or experiment in milliseconds is dependent on having all information available at request time, rather than querying previous data, or storing massive amounts of historical data in memory.

User Attributes​

All user attributes can be explicitly supplied, and some can be inferred from a user's device or connection. Supplying one will always override an inferred value.

KeyDescriptionExampleClient SDK SupportAuto-infer
userIDID representing a unique user. This ID will be used to guarantee consistency of targeting for Feature Gates and Experiments and will be used to evaluate experiment results. If User ID doesn't exist yet, leave this empty; a Stable ID persisted locally will be used for evaluations.your_user_idAll
emailEmail of the user.marcos@statsig.comAll
userAgentUser agent of the browser. This will be decoded to determine the Browser and Operating System of the user's context. Will be inferred if not provided.Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.40 Safari/537.36Web✔
ipIP address of the user. Inferred from the request to /initialize if not provided192.168.1.101All✔
country2-letter country code of the user. This can be supplied or inferred, and we can target based on the country code in both cases. When inferred, the country code follows ISO-3166.USAll✔
localeLocale of the user. When using the Android or iOS SDK, this will be inferred if not provided.en_USMobile✔
appVersionVersion of the app the user is using. When using the Android or iOS SDK, this will be inferred if not provided.1.0.1Mobile✔
systemNameWhen using our Android/iOS SDKs, this will be automatically assigned, but you can also provide an explicit operating system to override.AndroidAll✔
systemVersionWhen using our Android/iOS SDKs, this will be automatically assigned, but you can also provide an explicit OS version to override.15.4All✔
browserNameWhen using our Web SDK, this will be automatically assigned, but you can also provide an explicit Browser Name to override.ChromeWeb✔
browserVersionWhen using our Web SDK, this will be automatically assigned, but you can also provide an explicit Browser Version to override.45.0Web✔
customDictionary that can contain key/value pairs that can be used for Feature Gate targeting. The content of this dictionary will be stored and available after targeting.{subscriber: "yes", ...}All
privateAttributesDictionary that can contain key/value pairs that can be used for Feature Gate targeting. The content of this dictionary will not be stored after being used for targeting and will be removed from any log_event calls.{sensitive_field: "sensitive_information", ...}All
customIDsDictionary that can contain key/value pairs used as the randomization unit ID for experiments that are set up using these IDs instead of the User ID.{account_id: "23456555", company_id: "company_xyz"}All

Have sensitive user PII data that should not be logged?​

On the StatsigUser object, there is a field called privateAttributes, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in privateAttributes will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.

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

Time-based conditions​

All SDKs (both server and client-side) support unix timestamps in milliseconds to evaluate time based conditions (After time, before time). Without knowing all possible variations of DateTime formats, we have to normalize on something, so its best to convert your DateTime field into a standard format for evaluation.

We have added support for ISO timestamps to some server SDKs.

We have added support for ISO timestamps to server SDKs supported by server core (Java, Python, PHP, Rust, Node).

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. In short, its always better to pass the user ID if it's available: users will get a stable experience, and any events will be attributed to the correct users so you can accurately measure downstream metrics.

Still don't want to pass an ID? Here are our suggestions for different use cases:

  1. If you plan to only use one/off feature gates, or non-percent-based rules (like countries) While you're still losing functionality, you can pass any non-empty identifier, hard coded string, or a random ID less than 100 if you do not have the actual user ID. Don't pass a purely random ID - as we won't be able to dedupe your events, you'll explode your event usage, and your Statsig bill.

  2. If you want to rollout a feature partially, check for regressions, then roll out to everyone, you must pass an ID in your checkGate/getConfig/getExperiment calls, as well as any logEvent calls you make. Otherwise, we're not able to attribute the events you log to the correct users who saw or didn't see your new feature, or calculate metrics correctly to help you see any regressions.

  3. If you want to run an A/B experiment to decide whether to ship a new feature, you should also pass the persistent user IDs, for the same reason mentioned in 2, above.

  4. If you want to pass a userID for the above reasons, but don't have a logged in user (e.g. you are optimizing the login flow), set a stable identifier (we provide one in client SDKs!) as a cookie or in local storage and use that with each call to Statsig.

We hope this is helpful. If you have a use case that is not covered in these scenarios, or have any question at all, feel free to join our Slack community and drop a question/comment there!

Pass all IDs when you have them​

A common mistake is to accidentally expose users without a userID to a user-ID based experiment. All of them will be bucketed into one group (whichever the "null" userID goes to), polluting your results. If you run experiments on multiple ID types (or you might one day), its best to pass every identifier available.