Targeting

GrowthBook lets you target a specific feature value or experiment to a subset of your users. This is accomplished with Attributes, Conditions, Saved Groups, and Prerequisites.

Attributes

In order for targeting to work, you must pass attributes into the GrowthBook SDK and also list them in the GrowthBook App.

Attributes are passed into your SDKs as key-value pairs. The keys you use are completely custom and there are no requirements or restrictions. Use whatever makes sense for your application.

Here's an example from our JavaScript SDK:

growthbook.setAttributes({
  id: "123",
  email: "[email protected]",
  country: "US",
  url: window.location.href,
  userAgent: navigator.userAgent,
  admin: true,
  age: 50,
});

In addition to passing attributes into the SDK, you also must update the GrowthBook App with these same attribute keys. You can do this under SDK Connections → Attributes:

note

The actual values of the targeting attributes (e.g., the user IDs, emails, etc.) are never sent to GrowthBook. They are only stored in memory locally within the SDK. This architecture eliminates huge potential security holes and keeps your user's PII safe and secure.

Each attribute has 4 parts:

• The attribute name itself. This is how the attribute will be referenced in the SDK.
• The data type of the attribute
• Whether it's an identifier. Identifiers are attributes which uniquely identify something—typically either a person, account, company, or device—and are used for experiment assignments.
• The projects that the attribute is associated with. This is useful if some attributes are only relevant to certain projects. If no projects are selected, the attribute will be available for all projects.

Attribute Data Types

GrowthBook supports the following attribute data types:

• Boolean: True or false
• Number: Floats or integers
• String: Freeform text
• Enum: Short list of pre-defined values
• Secure String: Like a string, but the values will be hashed before passing to the SDK
• Array of Strings: Useful for data like tags
• Array of Numbers: Useful anytime you have multiple numeric values
• Array of Secure Strings: Useful for passing multiple values that you want to keep secure

Semantic Version Targeting

In version 2.2, we introduced support for semantic version string comparisons. Without this, the string 1.0.9 will be seen as "greater" than 1.0.10.

To leverage this feature, you first need to create a version string attribute. Navigate to SDK Configurations → Attributes and create or edit a String attribute. In the format dropdown, select: Version string.

After saving, the targeting operators (e.g. is greater than) will automatically start using a version-safe comparison function.

note

This is only supported in some of our SDKs. Check the release notes for the specific SDK you are using to make sure you have a compatible version installed.

Date Targeting

In version 3.1, we introduced a new Date format for string attributes that makes it easier to target by date.

To leverage this feature, you first need to create a date string attribute. Navigate to SDK Configurations → Attributes and create or edit a String attribute. In the format dropdown, select: Date string.

After saving, certain targeting operators (e.g. is after or on or is equal to) will display a date picker input. Dates entered with the date picker will be saved as an ISO-formatted Date string (e.g. 2024-07-23T20:06).

Country Code Targeting

Use 2-character ISO country codes to simplify targeting by country.

How to implement country code targeting:

• Create an attribute and set the Data Type to String
• Change the String Format to ISO Country Code (2 digit)
• Save the attribute

Now, when setting targeting rules, you'll get a dropdown to directly select a country to target.

Targeting Conditions

GrowthBook provides a nice UI for defining simple targeting conditions using your attributes.

Advanced Mode

If you need support for something more advanced you can enter targeting conditions with JSON instead by clicking the "Advanced Mode" link.

The JSON structure is inspired by the MongoDB Query syntax. Multiple conditions are always joined with AND (except when explicitly using $or/$nor). Below are all of the supported operators with examples.

• Key/value pairs for simple equality

  {
    "attribute1": "value1",
    "attribute2": 123,
    "attribute3": false
  }
• Basic comparison operators for string/number attributes
  • $eq (equals)
  • $ne (not equals)
  • $lt (less than)
  • $lte (less than or equal to)
  • $gt (greater than)
  • $gte (greater than or equal to)
  • $regex (regular expression match, string attributes only)
  • $in (in array)
  • $nin (not in array)

  {
    "foo": {
      "$gt": 10,
      "$lte": 99
    },
    "bar": {
      "$in": ["a","b","c"]
    },
    "baz": {
      "$regex": "^test-([0-9]+)$"
    }
  }
• Comparison operators for semantic version strings (semver):
  • $veq (equals)
  • $vne (not equals)
  • $vlt (less than)
  • $vlte (less than or equal to)
  • $vgt (greater than)
  • $vgte (greater than or equal to)

  {
    "appVersion": {
      "$vgt": "1.5.6",
      "$vlte": "5.4.0"
    }
  }
• Operators for array attributes
  • $elemMatch (at least one element must match the specified condition)
  • $all (all of the specified values must exist in the array)
  • $size (array length must match the specified condition)

  {
    "emails": {
      "$elemMatch": {
        "$regex": "@gmail.com$"
      }
    },
    "hobies": {
      "$all": ["hiking","tennis","chess"]
    },
    "tags": {
      "$size": {
        "$gt": 5
      }
    }
  }
• Misc operators
  • $exists (tests if the attribute value is null or not)
  • $type (tests if the attribute's type matches the type specified)
  • $not (inverts a nested condition)

  {
    "alternateEmail": {
      "$exists": true
    },
    "foo": {
      "$type": "string"
    },
    "name": {
      "$not": {
        "$regex": "^J"
      }
    }
  }
• Logical operators with arbitrary nesting levels
  • $or
  • $nor
  • $and
  • $not

  {
    "$or": [
      {
        "$not": {
          "foo": "abc"
        }
      },
      {
        "$and": [
          {"bar": true},
          {"baz": 123}
        ]
      }
    ]
  }

note

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.

Saved Groups

Target the same group of users across multiple features and experiments with Saved Groups, ensuring consistent user targeting across your projects. For instance, easily manage beta testers or high-value customers by defining a group once and reusing it everywhere.

Types of Saved Groups

Condition Groups

Define advanced targeting rules based on user attributes. For example, target users who are located in the US and on a mobile device.

ID Lists

Manually define targeted users via text input or by uploading a CSV. For example, create a beta testers saved group by uploading a CSV of user IDs.

ID Lists are limited to 1 MB. Using multiple, large ID Lists may impact performance as it increases the SDK payload. It's recommended to keep ID Lists as concise as possible.

ID Lists accept the following types of attributes: string, secureString, or number. For targeting other types of attributes, use Condition Groups.

note

Enterprise users can use optimized ID lists to reduce payload size. Enable this feature by editing your SDK connection and toggling on Pass ID Lists by reference. If the the toggle isn't visible, your SDK is not compatible with this feature.

Prerequisite Targeting

You can add prerequisite targeting to any feature or experiment. For more information, see the Prerequisite Features page.