StatsigUser Object
Introduction
You should provide a StatsigUser object whenever possible when initializing the SDK, passing as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks). Most of the time, the User ID field is needed in order to provide a consistent experience for a given user (see device-level experiments to understand how to correctly run experiments for logged-out users). If the user is logged out at the SDK init time, you can leave out the User ID field, and Statsig will use a stable device ID that the SDK creates and stores in the local storage for targeting purposes.
All of the User Attributes can be explicitly supplied to the User Object and some can be automatically inferred from a user's device or connection. Supplying a User Attribute will always override any inferred values.
Auto-inferred User Attributes can be used for both Targeting and Results Segmentation purposes.
User Attributes
| Attributes | Description | Key | Example | Client SDK Support | Auto-infer |
|---|---|---|---|---|---|
| User ID | ID 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. | userID | your_user_id | All | |
| Email of the user | email | marcos@statsig.com | All | ||
| User Agent | User 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 | userAgent | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.40 Safari/537.36 | Web | ✔ |
| IP | IP address of the user. ** We can infer IP when not supplied to User Object, but cannot target experiments/features based on IP when it's inferred | ip | 192.168.1.101 | All | ✔ ** |
| Country | 2 letter coutry code of the user. This can be supplied or inferred, and we can target based on country code in both cases. | country | US | All | ✔ |
| Locale | Locale of the user. When using the Android or iOS SDK, will be inferred if not provided | locale | en_US | Mobile | ✔ |
| App Version | Version of the app the user is using. When using the Android or iOS SDK, will be inferred if not provided | appVersion | 1.0.1 | Mobile | ✔ |
| Operating System | When using our android/ios SDKs, this will be automatically assigned, but you can also provide an explicit operating system to override | systemName | Android | All | ✔ |
| Operating System Version | When using our android/ios SDKs, this will be automatically assigned, but you can also provide an explicit OS version to override | systemVersion | 15.4 | All | ✔ |
| Browser Name | When using our Web SDK, this will be automatically assigned, but you can also provide an explicit Browser Name to override | browserName | Chrome | Web | ✔ |
| Browser Version | When using our Web SDK, this will be automatically assigned, but you can also provide an explicit Browser Version to override | browserVersion | 45.0 | Web | ✔ |
| Custom | Dictionary 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 | custom | {current_page: "/homepage", ...} | All | |
| Private Attibutes | Dictionary that can contain key/value pairs that can be used for Feature Gate targeting. The content of this dictionary will not be stored after used for targeting and will be removed from any log_event calls | privateAttributes | {sensitive_field: "sensitive_information", ...} | All | |
| Custom IDs | Dictionary 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 | customIDs | {account_id: "23456555", company_id: "company_xyz"} | All |
DateTime targeting
All SDKs support unix timestamps 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.
Cached values for a user
If the initialize request fails, the SDK will fall back to values cached for the user. The cache key for those values is important - because values related to the session can change for every initialize call, if we include the full user object as the cache key, we may never match against cached values.
We define the "user" to cache based on the set of all ids - the userID and all customIDs. This means that if another field changes in the user object, we will still load the cached values as long as the IDs are the same.
If you have critical fields which define a user uniquely and are not in the userID or customIDs field, you can override the cache key - check the documentation for your specific sdk. At the moment, this is only available in javascript based sdks (js, react, react native, expo), and android/ios native sdks.
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!
For more information, refer to the privateAttributes guide.