Skip to main content

Feature Flag Conditions

note

Usually referred to online as feature flags, the Statsig UI and SDKs call them feature gates.

Introduction

Statsig feature gates contain a list of rules that are evaluated in order from top to bottom. The page describes in more detail how these rules are evaluated and lists all currently supported conditions.

Rule Evaluation

The rules that you create are evaluated in the order they're listed. For each rule, the criteria or conditions determine which users qualify for the Pass/Fail treatments. The Pass percentage further determines the percentage of qualifying users that will be exposed to the new feature. The remaining qualifying users will see the feature disabled.

Suppose you set up your rules as shown below, the following flow chart illustrates how Statsig evaluates these rules.

image

image

Note that as soon as a user qualifies based on the condition in a given rule, Statsig doesn't evaluate subsequent rules for this user. Statsig then picks the qualifying user to be in either the Pass or Fail group of that rule.

Also note that in the example, the third rule for Remaining Folks captures all users who don't qualify for previous two rules. If we were to remove this third rule, then only a subset of your users (users in pools 1 and 2) would qualify for this feature gate and for further analysis, not your total user base.

Client vs Server SDKs

All of the following conditions work on both client and server SDKs. Client SDKs handle these conditions a bit more automatically for you - if you do not provide a userID, client SDKs rely on an auto-generated "stable identifier" which is persisted to local storage. In addition, if you do not automatically set an IP or User Agent (UA), the client SDK will infer these attributes from the request IP and UA. Similarly, on mobile, the client SDK will automatically pass your app version and locale to the server so conditions using these attributes can be evaluated without having to set them explicitly.

Stability

Evaluations at a given percentage are stable with respect to the unitID. For example, if the gate/config/experiment/layer has a unit type of "userID", and userID = 4 passes a condition at a 50% rollout, they will always pass at that 50% rollout. The same applies for customIDs, if the unit type of the entity is that customID. Want to reset that stability? See Resalting.

Resalting

Gate evaluations are stable for a given gate, percentage rollout, and user ID. This is made possible by the salt associated with a feature gate. If you want to reset a gate, triggering a reshuffle of users, you can "resalt" a gate from the dropdown menu in the top right of the feature gate details page.

Resalt UI

Partial Rollouts

While 0% or 100% rollouts for gates are simply "on for users matching this rule"/"off for users matching this rule", each rule allows you to specify a percentage of qualifying users who should pass (see the new feature). If you want to get Pulse Results (metric movements caused by a feature), simply specifying a number between 0% and 100% will create a random allocation of users in Pass/Fail or "test"/"control" groups for a simple A/B test. You can use this to validate that a new feature does not regress existing metrics as you roll it out to everyone. Statsig suggests a 2% -> 10% -> 50% -> 100% roll out strategy. Each progressive roll out will generate its own Pulse Results as shown below.

image

Supported Conditions

User ID

Usage: Simple lists of User IDs to explicitly target or exclude from a gate.

Supported Operators: Any of, none of

Example usage: Add yourself (or a small group like your team) when you just start building a new feature. Or exclude your designer until it's ready for their eyes.

Small user id allowlist example

Email

Usage: Target based on the email of the user

Supported Operators: any of, none of, contains any of, contains none of

Example: Show new feature to people in the Statsig company with an authenticated @statsig.com email address

Email condition example

Everyone

Usage: Percentage rollout on the remainder of users that reach this condition. Think of it as "everybody else" - there could be a dozen other rules/conditions above it, but for everyone else, what percentage do you want to pass?

Supported Operators: None. Percentage based only.

Example usage: 50/50 rollout to A/B test a new feature. Or 0% to hide the feature for all people not matching a set of rules. Or 100% to show the feature to the remaining users who did not meet a condition above.

Everyone 50/50 condition example

App Version

Usage: User's on a particular version of your app/website will pass. Particularly useful for mobile app development, where a feature may not be fully ready (or maybe be broken) in a particular app version.

Supported Operators: >=, >, <, <=, any of, none of

Example: Turn off a feature for all users on app versions 3.0.0 through 3.1.0 as it was broken.

App version Example

Browser Version

Usage: A particular version of a browser, parsed from the user agent. Should likely be combined with the browser name condition.

Supported Operators: >=, >, <, <=, any of, none of

Example: Turn off a feature for old versions of chrome which don't support a certain API

Browser Name and Version example

Browser Name

Usage: A particular browser, parsed from the user agent: ('Chrome', 'Chrome Mobile', 'Edge', 'Edge Mobile', 'IE', 'IE Mobile', 'Opera', 'Opera Mobile', 'Firefox', 'Firefox Mobile', 'Mobile Safari', 'Safari'). Often combined with the Browser Version condition.

Supported Operators: >=, >, <, <=, any of, none of

Example: Turn off a feature for old versions of chrome which don't support a certain API

To test: The Browser Name is inferred from the userAgent, but if you need to set it explicitly, you can set browserName in the user object.

Browser Name and Version example

OS Version

Usage: A particular os version the user is on, parsed from the user agent. Should likely be combined with the Operating System condition.

Supported Operators: >=, >, <, <=, any of, none of

Example: Turn off a feature for versions of macOS which don't support a certain API

Operating System example

Operating System

Usage: A particular operating system, parsed from the user agent: ('Android', 'iOS', 'Linux', 'Mac OS X', 'Windows'). Often combined with the OS Version condition.

Supported Operators: any of, none of

Example: Turn off a feature for versions of macOS which don't support a certain API

To test: The OS is inferred from the userAgent, but if you need to set it explicitly, you can set deviceOS in the user object.

Operating System example

Device Model

Usage: The device model of the mobile device the user is on.

Supported Operators: any of, none of, is null, is not null, contains any of, contains none of, regex

Example: Turn off a feature for older device models that your app does not support.

To test: The Device Model is automatically inferred by the SDK, but if you need to set it explicitly, you can set deviceModel in the user object.

Device Model example

Country

Usage: A 2 letter country code, either passed as the user's country or determined by the IP address.

Supported Operators: any of, none of

Example: Show a cookie consent banner for users accessing your service from the EU.

EU Countries example

IP address

Usage: An IP address string

Supported Operators: any of, none of

Example: Show a different about us page on www.statsig.com to people in a certain IP address range

Matching IP Addresses example

Passes Target gate

Usage: The condition passes if the referenced gate passes for the given user

Supported Operators: gate_id

Example: Only show feature X to people who also see feature Y: Only show a toggle to turn off ranking to people who also pass the new ranking algorithm gate.

Passes target gate example

Fails Target gate

Usage: Inverse of passes target gate: the condition passes if the referenced gate returns false for the given user

Supported Operators: gate_id

Example: Only show a new UI element to people who are not using the redesigned UI.

Fails target gate example

User in Segment

Usage: The condition passes if the user passes the rules defining the referenced segment. See the segments guide for more information on segments.

Supported Operators: segment_id

Example: Only show a new UI element to people who are not using the redesigned UI.

In segment example

User not in Segment

Usage: The condition passes if the user fails the rules defining the referenced segment. See the segments guide for more information on segments.

Supported Operators: segment_id

Example: Only show a feature to people who are not in the premium/paid tier.

Not in segment example

Environment Tier

Usage: The condition passes if the evaluation is happening in the given environment tier (development/staging/prod). See the environments guide for more information on environments.

Supported Operators: development/staging/prod/(other)

Example: Only show a feature on development builds

Environment tier example

Custom Field

Usage: Specify the key in the custom object to fetch the value use on the left hand side of a comparison

Supported Operators:

  • string: any of, none of, contains any of, contains none of
  • number: any of, none of, less than, greater than
  • version: any of, none of, less than, greater than, less than or equal to, greater than or equal to
  • date: before, after

Example: Only show a feature to user's who have turned on dark mode, as marked by the custom object having "darkmode": true.

Custom example

Unit ID

Usage: Select custom ids to explicitly target or exclude from a gate.

Supported Operators: any of, none of, is null, is not null, contains any of, contains none of, regex

Example: Add yourself (or a small group like your team) when you just start building a new feature.

Unit id example

Time

Usage: Evaluate a gate relative to the current time

Supported Operators: after time, before time

Value: time (displayed and input on Console in your browser's local time, but converted to a unix timestamp for evaluation)

Example: Show the labor day sale banner on labor day

Time example

Private Attributes

Usage: Any user field conditions, or custom field conditions, can be used via a private attribute. If you are targeting an email, but don't want it to be logged, create an email condition, but put "email": "xyz@email.com" in the privateAttributes dictionary. For custom fields, create a custom field condition, but put the key/value pair in privateAttributes instead. Remember that privateAttributes are used for evaluation only, and are not stored or kept on logEvents.

Supported Operators: dependent on the condition

Example: Only show a feature to 20 somethings, as marked by the privateAttributes object having "age": "20-29".

Private attributes example

FAQs

1. Could users switch between control (fail) and test (pass) groups? Once a user is exposed, they will be included in the analysis going forward. They saw the new feature and were affected. If the feature gate rules are modified or the user's attributes change in a way that the user no longer qualifies, they will stop receiving the new feature. However, they will continue to be counted for analysis. Once you roll out the feature, all users will see the new feature; alternatively, if you turn off the feature gate, all users will see the control (feature disabled). In either case (roll out or turn off), Statsig performs no further analysis.

2. How do overrides work? Are users included in overrides also included in the analysis? When you add user IDs in the Pass or Fail lists of your feature gate, these users will see the appropriate treatment but will not be included in the analysis.