User Condition
What is a User Condition?
A User Condition is a condition that is based on the comparison of a user attribute (comparison attribute) and a preset value (comparison value).
It allows you to define Targeting Rules which target users based on their properties.
How does the User Condition work?
The comparison attribute's value from the User Object is compared to the comparison value you set on the Dashboard. The comparison is done according to the selected comparator and will result in true or false. This will be the result of the condition.
For more details on the evaluation of User Conditions, please refer to Feature Flag Evaluation.
How to set a User Condition?
You can add a User Condition to a feature flag by clicking the +IF ("Add targeting rule") button on the Dashboard. To add more conditions, click the +AND ("Add AND condition") button.
Anatomy of a User Condition
A User Condition consists of three parts:
- Comparison attribute: The user attribute on which the condition is based. Can be Identifier (user ID), Email, Country, or any custom attribute.
- Comparator: The comparison operator that defines the relation between the comparison attribute and the comparison value. See the available comparators here.
- Comparison value: The preset value to which the comparison attribute is compared. Depending on the comparator, can be a string, a list of strings, a number, a semantic version, a list of semantic versions or a date.
Comparison attribute
A property of your user (e.g. email address, geographic location). Your application should pass the attribute values (e.g. '[email protected]', 'Europe') to the ConfigCat SDK as a User Object.
There are 3 predefined attributes. Additionally, you can define your custom attributes as well:
| Comparison attribute name | Description |
|---|---|
| Identifier | Usually, it is a unique user identifier in your application. |
| The e-mail address of your user. | |
| Country | The location of your user. Might be useful for testing a new feature in specific countries only. |
| Custom | Any additional attribute (e.g. OS version). Can be defined by typing its name into the textbox. |
Comparison value
A string, a list of strings, a number, a semantic version, a list of semantic versions or a date value. Will be compared to the selected comparison attribute using the comparator. The length of the comparison value is limited, and the limit depends on your subscription plan. See the Subscription Plan Limits page for more details.
Comparator
Confidential text comparators
We recommend using confidential text comparators when targeting users based on their sensitive data (like email address, name, etc.) In this case, the feature flag evaluation is performed using the SHA256 hashes of the values to ensure that the comparison values are not exposed. This can cause an increase in the size of the config JSON file and the overall network traffic. Yet it is not recommended to use the cleartext version of the confidential comparators unless the increased network traffic becomes an issue.
The following comparators expect the comparison attribute to be a string value and the comparison value to be a string or a list of strings. The comparison is case-sensitive.
| Comparator | Description |
|---|---|
| EQUALS (hashed) | Checks whether the comparison attribute is equal to the comparison value. |
| NOT EQUALS (hashed) | Checks whether the comparison attribute is not equal to the comparison value. |
| IS ONE OF (hashed) | Checks whether the comparison attribute is equal to any of the comparison values. |
| IS NOT ONE OF (hashed) | Checks whether the comparison attribute is not equal to any of the comparison values. |
| STARTS WITH ANY OF (hashed) | Checks whether the comparison attribute starts with any of the comparison values. |
| NOT STARTS WITH ANY OF (hashed) | Checks whether the comparison attribute does not start with any of the comparison values. |
| ENDS WITH ANY OF (hashed) | Checks whether the comparison attribute ends with any of the comparison values. |
| NOT ENDS WITH ANY OF (hashed) | Checks whether the comparison attribute does not end with any of the comparison values. |
Text comparators
The following comparators expect the comparison attribute to be a string value and the comparison value to be a string or a list of strings. The comparison is case-sensitive.
Consider using confidential text comparators if you plan to target users based on their sensitive data, e.g. email address or company domain.
| Comparator | Description |
|---|---|
| EQUALS (cleartext) | Checks whether the comparison attribute is equal to the comparison value. |
| NOT EQUALS (cleartext) | Checks whether the comparison attribute is not equal to the comparison value. |
| IS ONE OF (cleartext) | Checks whether the comparison attribute is equal to any of the comparison values. |
| IS NOT ONE OF (cleartext) | Checks whether the comparison attribute is not equal to any of the comparison values. |
| STARTS WITH ANY OF (cleartext) | Checks whether the comparison attribute starts with any of the comparison values. |
| NOT STARTS WITH ANY OF (cleartext) | Checks whether the comparison attribute does not start with any of the comparison values. |
| ENDS WITH ANY OF (cleartext) | Checks whether the comparison attribute ends with any of the comparison values. |
| NOT ENDS WITH ANY OF (cleartext) | Checks whether the comparison attribute does not end with any of the comparison values. |
| CONTAINS ANY OF (cleartext) | Checks whether the comparison attribute contains any comparison values as a substring. |
| NOT CONTAINS ANY OF (cleartext) | Checks whether the comparison attribute does not contain any comparison values as a substring. |
Semantic version comparators
The following comparators expect the comparison attribute to be a string containing a valid semantic version and the comparison value to be a semantic version or a list of semantic versions.
Comparison is performed according to the Semantic Versioning specification.
| Comparator | Description |
|---|---|
| IS ONE OF (semver) | Checks whether the comparison attribute interpreted as a semantic version is equal to any of the comparison values. |
| IS NOT ONE OF (semver) | Checks whether the comparison attribute interpreted as a semantic version is not equal to any of the comparison values. |
| < (semver) | Checks whether the comparison attribute interpreted as a semantic version is less than the comparison value. |
| <= (semver) | Checks whether the comparison attribute interpreted as a semantic version is less than or equal to the comparison value. |
| > (semver) | Checks whether the comparison attribute interpreted as a semantic version is greater than the comparison value. |
| >= (semver) | Checks whether the comparison attribute interpreted as a semantic version is greater than or equal to the comparison value. |
Number comparators
The following comparators expect the comparison attribute and the comparison value to be numbers.
| Comparator | Description |
|---|---|
| = (number) | Checks whether the comparison attribute interpreted as a decimal number is equal to the comparison value. |
| <> (number) | Checks whether the comparison attribute interpreted as a decimal number is not equal to the comparison value. |
| < (number) | Checks whether the comparison attribute interpreted as a decimal number is less than the comparison value. |
| <= (number) | Checks whether the comparison attribute interpreted as a decimal number is less than or equal to the comparison value. |
| > (number) | Checks whether the comparison attribute interpreted as a decimal number is greater than the comparison value. |
| >= (number) | Checks whether the comparison attribute interpreted as a decimal number is greater than or equal to the comparison value. |
Date and time comparators
The following comparators expect the comparison attribute to be a date value (a second-based Unix timestamp or a platform-specific date object) and the comparison value to be a date.
| Comparator | Description |
|---|---|
| BEFORE | Checks whether the comparison attribute interpreted as a second-based Unix timestamp is less than the comparison value. |
| AFTER | Checks whether the comparison attribute interpreted as a second-based Unix timestamp is greater than the comparison value. |
Array comparators
The following comparators expect the comparison attribute to be an array of strings (or an array of strings serialized to JSON) and the comparison value to be a list of strings. The comparison is case-sensitive.
| Comparator | Description |
|---|---|
| ARRAY CONTAINS ANY OF | Checks whether the comparison attribute interpreted as an array of strings contains any of the comparison values. |
| ARRAY NOT CONTAINS ANY OF | Checks whether the comparison attribute interpreted as an array of strings does not contain any of the comparison values |
Examples
Black Friday sale
Context
Black Friday is coming and we want to offer a special discount to our users.
Goal
The deals should become available at midnight on Black Friday. We want to make sure that the users can't access the deals before that. Also, the deals should be available for the whole weekend.
Solution
Let's use the AFTER comparator to check whether the current time is after midnight on Black Friday AND the current time is BEFORE midnight on Sunday.
On the Dashboard:
In the code:
const userObject = {
identifier: userId,
email: userEmail,
custom: {
// In case this code runs on the customer's device, we should consider getting the current time
// from a time server since customers are free to set the system clock on their devices.
Date: new Date()
},
};
const value = await configCatClient.getValueAsync("enableBlackFridayDeals", false, userObject);
Confidential CONTAINS and NOT CONTAINS workaround
Context
We use ConfigCat in our Angular frontend application to control the availability of a feature.
Goal
We want to enable this feature for users from certain companies. To do the job, we would need to use the CONTAINS or NOT CONTAINS comparators.
However, there is no confidential version of these comparators and we are well aware that, for privacy reasons, it's not a good idea to use cleartext comparators for applications running in the browser.
How can we solve this?
Solution
Let's work around the problem by extracting the domain part of the email and passing it as a custom attribute named Domain to the ConfigCat SDK.
This way we can define the desired Targeting Rule using confidential comparators only.
On the Dashboard:
In the code:
const userDomain = userEmail.split('@').pop();
const userObject = {
identifier: userId,
email: userEmail,
custom: {
Domain: userDomain
},
};
const value = await configCatClient.getValueAsync(key, defaultValue, userObject);
Since the introduction of Config V2, this workaround is no longer needed: in a V2 config, you can simply use the hashed version of the ENDS WITH ANY OF comparator.