Activation Strategies
Overview
An activation strategy determines who should get a feature. They allow you to enable and disable features for certain users without having to redeploy your application. For example, you can release features only to users with a specific user ID, email, IP address, and more. You can implement gradual rollouts to specific user segments, for example, those on a specific subscription plan or region. You can also use them to schedule feature releases or make features available for a limited time.
An activation strategy is assigned to one feature flag in one environment. A feature flag is enabled in a given context (for example, user or application) if at least one of its activation strategies resolves to true.
The default activation strategy is a 100% gradual rollout, enabling the flag for all users. You can refine this using rollout percentage, targeting, and variants.
Feature flags can have multiple activation strategies. Unleash evaluates each strategy independently, enabling the flag if any resolves to true. This behavior is equivalent to the OR logical operator.
For example, to roll out a feature to 75% of users while granting access to internal users, you can add two activation strategies as follows:
- Gradual rollout to 100% with a constraint on the email address.
- Gradual rollout to 75% (of all users).
Rollout percentage
The rollout percentage determines the proportion of users exposed to a feature. It uses a normalized MurmurHash of a user’s unique ID, ensuring consistent and random feature distribution. Stickiness maintains a stable user experience across sessions.
Targeting
Segmentation and constraints allow you to define conditions for your activation strategies so that they will only be evaluated for users and applications that match those criteria. Constraints are individual conditional statements, while segments are a reusable set of constraints that you can apply to multiple strategies.
Constraints
Version: 4.16+
Constraints are conditional rules that determine whether a strategy applies, based on fields from the Unleash context. Constraints can reference both standard context fields and custom context fields.
An activation strategy can have as many constraints as needed. When an activation strategy has multiple constraints, then every constraint must be evaluated to true for the strategy to be evaluated. This behavior is equivalent to the AND logical operator.
You can use Playground to experiment with different strategy and constraint configurations and how they would evaluate in a given context.
For example, if you have two constraints: one where the user email must have the domain "@mycompany.com" and one where the user must have signed up for a beta program, then the strategy would only be evaluated for users with "@mycompany.com" emails that have signed up for the beta program.
Constraint structure
A constraint has three parts:
- A context field: The context field to use for evaluation.
- An operator: One of the constraint operators.
- Values: A value or list of values to use in the evaluation of the constraint.
These parts turn the constraint into an expression that evaluates to true or false. Here are a few example constraints:
| Context field | Operator | Values | Description |
|---|---|---|---|
userId | STR_ENDS_WITH | @example.com, @mycompany.com | Evaluates to true for users whose user IDs end with @example.com or @mycompany.com. |
currentTime | DATE_AFTER | 2022-06-05 21:43:22Z | Evaluates to true if the current time is after 2022-06-05 21:43:22Z. |
plan | IN | Premium, Plus | Evaluates to true if the custom context field plan is either 'Premium' or 'Plus'. |
Constraint operators
Constraint operators help you define the conditional statements that get evaluated as part of the constraint. Basic operators are available in all versions and SDKs. All other operators require Unleash version 4.9+ and SDK compatibility.
All constraints can be negated. For example:
| Operator | Value | Context field | Result |
|---|---|---|---|
STR_ENDS_WITH | "@user.com" | "hello@user.com" | true |
NOT STR_ENDS_WITH | "@user.com" | "hello@user.com" | false |
Basic operators
| Operator | Description |
|---|---|
IN | The context field is equal to any of the provided values; case sensitive. |
NOT_IN | The context field is not equal to any of the values provided; case sensitive. |
Numeric operators
Numeric operators compare the numeric value of context fields with the provided value. Numeric operators only accept single values.
| Operator | The context field is |
|---|---|
NUM_EQ | The context field is equal to the provided value. |
NUM_GT | The context field is strictly greater than the provided value. |
NUM_GTE | The context field is greater than or equal to the provided value. |
NUM_LT | The context field is strictly less than the provided value. |
NUM_LTE | The context field is less than or equal to the provided value. |
Date and time operators
All date and time operators require the currentTime context field, and the currentTime context field can only be used with date and time operators. With these operators, you can enable a feature before or after a specified time or make it available for a specific time span by combining the two operators.
Date and time operators only support single values.
| Operator | Description |
|---|---|
DATE_AFTER | currentTime is a date after the provided value. |
DATE_BEFORE | currentTime is a date before the provided date. |
String operators
String operators accept multiple values and can be set to be case-sensitive or case-insensitive.
| Operator | Description |
|---|---|
STR_CONTAINS | The context field contains any of the provided string values. |
STR_ENDS_WITH | The context field ends with any of the provided string values. |
STR_STARTS_WITH | The context field starts with any of the provided string values. |
Versioning (SemVer) operators
SemVer operators are used to compare version numbers such as application versions or dependency versions. SemVer operators only support single values.
The value must start with and contain at least major, minor, and patch versions. For example, 1.2.3. Optionally, you can also define pre-release version information by adding a hyphen and series of full-stop separated identifiers after the patch version. For example, 1.2.3-rc.2. Values with pre-release versions are considered less than versions without a pre-release in accordance with the SemVer specification, item 11.
| Operator | Description |
|---|---|
SEMVER_EQ | The context field is equal to the provided value. |
SEMVER_GT | The context field is strictly greater than the provided value. |
SEMVER_LT | The context field is strictly less than the provided value. |
Best practices
Server-side SDKs fetch the full feature flag configuration associated with your API key from Unleash. You can use API keys scoped to specific projects or environments to optimize payload size.
However, every value that you add to your feature flag constraints, increases the payload size. We recommend avoiding large constraint value lists. For example, instead of adding many user IDs or emails to the constraint value list, consider what properties those users share. This typically helps define and use a custom context field instead.
Add an activation strategy with a constraint
To add an activation strategy with a constraint to a feature flag, do the following:
- Open the Admin UI and go to the feature flag you'd like to add a strategy to.
- Select the environment you want to configure and click Add strategy.
- In the Targeting tab, go to the Constraints section, and click Add constraint.
- Select a context field to constrain on, for example,
email. - Set your desired operator, for example,
STR_ENDS_WITH. - Enter a value that the operator should evaluate, such as
@user.com, and click Add values. Then click Done. - Click Save strategy.
Client-side implementation
Activation strategies are defined on the server but implemented client-side. The client determines whether a feature should be enabled based on the activation strategies.
All server-side client SDKs and Unleash Edge implement the default activation strategy. The front-end client SDKs do not perform evaluations themselves. Instead, they rely on Unleash Edge to handle the implementation and evaluation.
When using strategies with constraints, the client must provide the current Unleash context to the flag evaluation function for the evaluation to be done correctly. All official Unleash client SDKs support the option to pass dynamic context values to the isEnabled() function (or the SDK's equivalent).
If the constraint uses a standard Unleash context field, set the context field to the required value. If the constraint uses a custom context field, use the Unleash context's properties field. Use the name of the custom context field as a key and set the value to your desired string.
Unleash SDKs expect all context values to be strings. If you use an operator that acts on non-string values, such as numeric operators or date and time operators, the SDKs attempt to convert the string into the expected type. If the conversion fails, the constraint evaluates to false.
Predefined strategy types
Predefined strategy types, such as UserIDs, IPs, and Hosts are a legacy implementation. Please use the default strategy with constraints to achieve your desired targeting.
Custom activation strategies
Custom activation strategies are deprecated. Please use the default strategy with constraints.