Skip to main content

Rules (Targeting, Rollout, Experimentation)

Every feature has a default value that is served to all users. The real power comes when you define override rules that let you run experiments and/or change the value based on targeting attributes.

Feature override rules UI

Override rules are defined separately for each environment (e.g. dev and production). This way you can, for example, test an experiment rule in dev first before deploying it to production.

The first matching rule for a user will be applied, so order matters. If there are no matching rules, the default value will be used.

Targeting Conditions

Rules can specify conditions to limit which users the rule applies to. These conditions are evaluated against the targeting attributes in the SDK.

There is an easy-to-use UI for simple targeting conditions:

Rule conditions UI

In advanced mode, you can specify conditions using the MongoDB query syntax. This enables you to have nested logic, advanced array operators and more. Here's an example:

// Either the user's name starts with "john"
// OR they are over 65 and have a kid who's a doctor
"$or": [
"name": { "$regex": "^john" }
"age": { "$gt": 65 },
"kids": {
"$elemMatch": {
"profession": "doctor"

We use the MongoDB query syntax because it is easy to read and write and is well documented. The conditions are never actually executed against a database. Instead, our SDKs include a light-weight interpreter for this syntax that runs entirely locally.

Learn more about the attributes used for targeting here.

Forced Value

The simplest type of override rule is a "Forced Value" rule. This forces everyone who matches the targeting condition to get a specific value. For example, you could have a feature default to OFF and use force rules to turn it ON for a specific list of countries.

Force rule UI

Percentage Rollout

Percentage Rollout rules let you gradually release a feature value to a random sample of your users.

Rollout rule UI

Rollouts are most useful when you want to make sure a new feature doesn't break your app or site. You start by releasing to maybe 10% of users. Then after a while if your metrics look ok, you increase to 30% and so on.

For rollout rules, you choose a user attribute to use for the random sample. Users with the same attribute value will be treated the same (either included or not included in the rollout). For example, if you choose a "company" attribute, then multiple employees in the same company will get the same experience.


The last type of rule is an Experiment. This randomly splits users into buckets, assigns them different values, and tracks that assignment in your data warehouse or analytics tool.

Experiments are most useful when you aren't sure which value to assign yet.

Here's what an Experiment rule looks like in the GrowthBook UI:

Experiment rule UI

In the vast majority of cases, you want to split traffic based on either a logged-in user id or some sort of anonymous identifier like a device id or session cookie. As long as the user has the same value for this attribute, they will always get assigned the same variation. In rare cases, you may want to use an attribute such as company or account instead, which ensures all users in a company will see the same thing.

If the total variation percents add up to less than 100%, the remaining users will skip the rule and fall through to the next matching one (or the default value) instead.

When a user is placed in an experiment via the experiment override rule, the SDK will track the experiment assignment in your data warehouse or analytics tool, via the trackingCallback method.

You can analyze the result of an Experiment the same way you would any experiment in GrowthBook.


If you have multiple experiments that may conflict with each other (e.g. background color and text color), you can use namespaces to make the conflicting experiments mutually exclusive.

Users are randomly assigned a value from 0 to 1 for each namespace. Each experiment in a namespace has a range of values that it includes. Users are only part of an experiment if their value falls within the experiment's range. So as long as two experiment ranges do not overlap, users will only ever be in at most one of them.


Before you can use namespaces, you must configure them under SDK Configuration > Namespaces.