Flag evaluation
The sections outlines the algorithm FlagSync executes when evaluating a feature flag for a user context.
For more details on flag evaluation differences across SDKs, refer to the SDK types (client/server). documentation. But generally speaking, client-side SDKs offload flag evaluation to FlagSync's servers, while server-side SDKs evaluate flags locally. The logic is identical across SDKs.
Flag evaluation flow
When evaluating a flag, the following steps are taken:
Is the SDK ready?
If a flag is evaluated before the SDK is ready, the SDK will return either the defaultValue passed to the flag evaluation function, or the string control indicating the SDK is not ready.
Client-side SDKs can use LocalStorage to bootstrap the initialization process, or explicitly pass a bootstrap set of flags to the FlagSyncFactory.
In both cases, the SDK will attempt to use the bootstrapped values before using the defaultValue or control value.
Does the flag key exist?
If a flag is not found by the specified flagKey, either the defaultValue or the string control will be returned. If the flagKey was included in the bootstrapped values, the bootstrapped value will be returned.
Is the flag enabled?
If the flag is not enabled, the default "off" variant is returned, which short-circuits all further flag evaluation logic.
If the flag is enabled, the algorithm continues.
Does the flag have any individual targeting rules?
A flag can contain multiple targeting rules, which targets a specific flag variant to a set of users or user groups. If the targeting rules are found, the logic below is executed, otherwise the algorithm continues.
Within a given targeting rule, the clause values are evaluated using a logical OR.
For instance, in the rule below, the "Sign Up" variant will be served to a user context that was initialized with an
attributeof "QA Tester" or "Product Team".
If a user context is targeted within multiple rules, the first rule they are found to match against is the variant they will be served.
If a match is detected, no further flag evaluation logic is applied.
Does the flag have a percentage rollout?
If the flag does not have a percentage rollout, the the algorithm continues, otherwise the following procedure is executed.
Percentage rollout algorithm
FlagSync uses a deterministic hashing algorithm to evaluate which variant to serve for a feature flag. This is comprised of two inputs:
The user context key, which is the unique identifier of the user context, oftentimes this is the user ID of an authenticated user, an email address, or an organization ID if your application is multi-tenancy.
The feature flag seed, which is unique to a feature flag and environment. (i.e. the seed for "my-flag" will be different in Test and Production environments).
Concatenate the user context key and the feature flags seed value, and hash it using the a deterministic hashing algorithm, ensuring a consistent result each time.
The hash value is converted to a number, which is further normalized to a number between 0 - 99 via a modulo operation.
At this point, the user has been placed into one of 100 buckets. These buckets are then applied to the distribution rules set in the percentage rollout.
For example, let's say User ABC and Seed 123 hashes to a normalized value of 16. Given the 33/33/34 breakdown below, the user would be placed in the 0-32 bucket, and subsequently served the "Register" variant.
Reshuffling a percentage rollout
In the FlagSync dashboard, you can choose to reshuffle an active percentage rollout, which changes the seed of the feature flag. Given that the seed is one of the inputs to the hashing algorithm, a change in seed reflects a change to the hash, thereby reshuffling users.
Fallback logic
In the event that a flag is enabled, the user context does not match any targeting rules, and there is no percentage rollout, the default "on" variant is served.
Getting a flag value
Last updated
