The User Object is an optional parameter when getting a feature flag or setting value from ConfigCat. It allows you to pass potential Targeting rule variables to the ConfigCat SDK. And represents a user in your application.
The User Object is essential if you'd like to use ConfigCat's Targeting feature.
Also, it contains user-specific information as a basis to evaluate what Feature Flag state or setting value should be returned by ConfigCat.
The relationship between User Object and Targeting rules
Let's say in the Admin Console you'd like to have the following targeting rule:
@example.com, otherwise it is
The ConfigCat SDK will return
true for a User Object with an email address of
email@example.com, and it will return
false for a User Object with an email address of
To achieve this, your application needs to pass the email address of your user to the ConfigCat SDK via User Object.
Keeping your user data safe was one of our main goals when designing ConfigCat. The main concept here is that the ConfigCat SDK which connects your application to our servers never pushes any data to the ConfigCat servers. It pulls only configs and targeting rules.
Feature Flag and Setting evaluation is on the Client side within the ConfigCat SDK. This means that your user data will never leave your system.
This allows you to create targeting rules based on sensitive data. You can double check the above since all the ConfigCat SDKs are open source and on GitHub.
User Object's structure
The data that could and should be passed to the User Object.
|Identifier||REQUIRED Please see description below the table.|
|OPTIONAL Email address of your user. By adding this parameter you will be able to create Email address based targeting. e.g: Turn on a feature for only users with @example.com addresses.|
|Country||OPTIONAL Fill this for location or country based targeting. e.g: Turn on a feature for users in Canada only.|
|Custom||OPTIONAL This parameter will let you create targeting based on any user data you like. e.g: Age, Subscription type, User role etc.|
Despite it's name, a User Object can contain non-user related information as well, that could be important for targeting like your application's version number or the device type/OS your application is running on.
Unique identifier of a user in your application. Required. Enables ConfigCat to differentiate your users from each other and to evaluate the setting values for percentage based targeting.
Our recommendation as an identifier:
- User ID - If you have one in your application you can use the same User ID with ConfigCat.
- Email address - In most cases adding an email address works perfectly here. As long as it is unique.
- SessionId - This comes useful when you'd like to target users who aren't logged in your application.