Skip to main content
Version: Config V2

User Object

The User Object is a collection of user attributes that describe the properties of a user. The User Object is necessary to evaluate Targeting Rules and Percentage Options. It allows you to pass the user attributes that are referenced in the rules of the feature flag to the ConfigCat SDK. The User Object represents a user in your application.


The User Object is essential if you'd like to use ConfigCat's Targeting feature.

The relationship between the User Object and Targeting Rules

As a product manager, you can define Targeting Rules on the ConfigCat Dashboard based on the user attributes that are provided by your application.

As a developer, User Object allows you to pass user attributes to the ConfigCat SDK, which you (or your teammates) can reference in the Targeting Rules on the Dashboard.

Security and privacy concerns

ConfigCat was designed with security and privacy in mind. The evaluation process is entirely implemented within the SDKs, meaning your users' sensitive data never leaves your system. The data flow is one-way – from ConfigCat CDN servers to your SDKs – and ConfigCat does not receive or store any attributes of the User Object passed to the SDKs. This design prioritizes the privacy and security of user data.

Anatomy of the User Object

The data that can be stored in the User Object:

IdentifierREQUIRED. We recommend adding a UserID, Email address, or SessionID.
EmailOptional. By adding this parameter, you can create Email address-based targeting. e.g.: Only turn on a feature for users with addresses.
CountryOptional. Fill this for location or country-based targeting. e.g.: Turn on a feature for users in Canada only.
CustomOptional. This parameter will let you create targeting based on any user data you like. e.g: Age, Subscription type, User role, Device type, App version number, etc.

Code example

let userObject = new configcat.User(
'#UNIQUE-USER-IDENTIFIER#', // Identifier attribute (Required)
'[email protected]', // Email attribute (Optional)
'United Kingdom', // Country attribute (Optional)
{ // Custom attributes (Optional)
SubscriptionType: 'Pro',
UserRole: 'Admin',

Identifier attribute

Unique identifier of a user in your application. This is a REQUIRED attribute which enables ConfigCat to differentiate your users from each other and to evaluate the feature flag values for Percentage Options.

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 is useful for targeting users who are not logged in to your application.

Custom attributes

To use custom attributes, you need to pass a User Object containing the custom attribute to the ConfigCat SDK.

The custom attribute's value can be multiple types. e.g.: string, number, date, array of strings, etc. Check the SDK reference for more details.


Enable a feature for most valuable customers only


Our demo company, Whisker Co. developed a new feature called Personalized Layout to enhance the user experience of their most valuable customers.


We want to enable the Personalized Layout feature but only for customers with the Pro subscription type.


To achieve this goal, we need a custom attribute named e.g. SubscriptionType, which stores the subscription type of the customer.

This allows us to define a Targeting Rule that turns on the feature for the customers whose SubscriptionType attribute is Pro. Finally, we need to make sure that the "To all others" value is OFF so the feature is turned off for the rest of the customers.


User Object example


Add the SubscriptionType custom attribute to the User Object in your application code.

const userObject = new configcat.User(userId, undefined, undefined, {
SubscriptionType: 'Pro',