Target with custom attributes – Split Help Center

With custom attributes, you can create dynamic and targeted feature rollout plans using any criteria or dimension of your customers. Attributes are recommended when you need to target customers in real time, such as:

Temporal or fast moving data (for example, time since last login, customer creation date, browser type, or machine)
Sensitive information (for example, customer deal size or customer status)

When deciding whether to use segments or attributes, segments are best when customers in a segment do not change multiple times in a day or the grouping of customers needs to be standardized across your organization (for example, key accounts, internal or outsourced QA teams, company employees).

Using custom attributes

This section explains how to create attributes and use them when you create targeting rules in the Split user interface. To understand the proper syntax for using attributes with the SDK in your code base, refer to the relevant language-specific article in our SDK documentation.

Creating a custom attribute

You can create custom attributes and suggested values that are available for a traffic type in the user interface. This allows you to provide a list of custom attributes that are needed by development teams to reduce the number of mismatches between custom attributes used in code and targeting rules. To create a custom attribute, do the following:

From the left navigation, click the top and then Admin settings. The Workspaces page appears.
Select the desired workspace. The All environments page appears.
Click the Traffic types tab and then the View/edit attributes selection. The Attributes page appears.
To create a custom attribute, click the Actions button, then the Create an attribute selection. The Create attribute page appears.
In the ID field, enter a unique ID (e.g., my_new_attribute). The Attribute ID must start with a letter followed by a combination of dashes(-), underscores(_), letters(a-z A-Z), or numbers(0-9).

Note: Once you create an ID, it cannot be changed.
In the Name field, enter a human recognizable name (e.g., my new attribute).
In the Description field, optionally enter a description of the attribute.
In the Type field, select a type from the list (e.g., String).

Note: When you use the String type, you can create a list of suggested values for a String custom attribute. Suggested values need to be comma separated.
Click the Create button. A new custom attribute is created and displays in the Attributes page.

Creating multiple attributes

You can create multiple custom attributes by performing a bulk upload of custom attributes from a CSV file. To create multiple custom attributes, do the following:

Note: If you already have an attribute ID in your user attributes (e.g., the attribute ID is plan) and your CSV file has an attribute with the same ID but has different values (e.g., Number rather than String), that attribute gets upserted (updated) to the new value.

From the left navigation, click the top and then Admin settings. The Workspaces page appears.
Select the desired workspace. The All environments page appears.
Click the Traffic types tab and then the View/edit attributes selection. The Attributes page appears.
To create a custom attribute, click the Actions button, then the Create multiple attributes selection. The Create multiple attributes page appears.
Import your CSV file by either dragging and dropping your CSV file in or click the select a CSV file to upload link to upload it. The CSV file must be formatted as follows:
- ID. Unique identifier of the attribute that displays in targeting rules and is used in code. The identifier can't be changed.
- Name. Name of the attribute.
- Description. Description of the attribute.
- Type. What the attribute is. Use String, Number, Boolean, Datetime, and Set.
- SuggestedValues. Values you're uploading. These must be comma delimited and in double quotes. The admin can add up to 100 suggested values, each of which can be up to 50 characters long.
Once you upload the file, click Save. The new attributes are uploaded to the User attributes page.

Creating a custom attribute using API endpoints

You can create custom attributes by using the following API endpoints:

Save attribute. Allows you to save an attribute for a traffic type ID. The attribute is created if it does not exist and is overwritten completely if it does.
Save identity. Allows you to create or overwrite a single key for a given traffic type and environment.

Selecting a custom attribute

You can customize the attributes you use in your treatment evaluation. When defining your targeting rules, you can target based on any custom attribute that is available for the Split’s traffic type. To do this, do the following:

In the Targeting rules area, click the Add attribute based targeting rules button. A list of attributes displays. The Matcher field appears.

Select a matcher. To add a new matcher, click the Add new matcher button. Select the desired matcher. For more information about matchers, refer to the Supported types and matchers section later in this guide.
Either select the suggested values for the attribute you want matched or enter the ones you want.
Select how you want to serve your treatment. Either select:
- On to serve to everyone or Off to serve a default treatment
- Distribute treatments as follows. This allows you to select a percentage of customers who are served this treatment.

Adding an attribute

You can completely customize the attributes you use in your treatment evaluation. When defining your targeting rules, you can amend your traffic type to target based on any custom attribute you provide. To do this, add an attribute in the field provided.

Selecting a matcher

When you use a custom attribute, you are prompted to select a matcher. Read more about the available matchers below.

Setting an attribute value

After you select a matcher, select the values for the attribute that you want Split to match. The following examples show the settings of different attribute values.

Show the on treatment for users with custom attribute plan_type equal to premium.
Show the on treatment for users with custom attribute registered_data on that are or after a specified date.
Show the on treatment for users with custom attribute age greater than or equal to 20.
Show the on treatment for users with custom attribute deal_size between 500,000 and 10,000,000.

Additional considerations

A feature flag uses an attribute whose value is not provided in code. For example, refer to the following feature flag definition:

if user.age <=60 then feature flag 100% on

else

if user is in segment all then feature flag 100% :off

If the value for the age attribute is not provided in the attributes map passed to the getTreatment call, the matcher in the first condition user.age <=60 does not match. The user gets the evaluation of the second condition if user is in segment all then feature flag 100% :off , which is off.

A feature flag uses an attribute whose value in code is not of the correct type. For example, refer to the following feature flag definition:

if user.plan_type is in list ["basic"] then feature flag 100%:on

else

if user is in segment all then feature flag 100%:off

Let's say the value provided for plan_type is an int instead of a string. The value for plan_type should be a string; however, the passed in value is a number. In this scenario, the matcher in the first condition if user.plan_type is in list ["basic"] does not match. The user gets the evaluation of the second condition if user is in segment all then feature flag 100%:off, which is off.

Types and matchers

As you design your rollout plans using custom attributes, be aware of the different types of attributes that we support and the matchers that can be used for each type.

String literal attributes

String literal attributes capture the concept of a character string. Use this attribute to do standard string to string comparisons, but also to target your customers with any list or pick list dimension that you track. Use this matcher type to target using a regular expression. Use string attributes with the following matchers:

is in list
is not in list
starts with
does not start with
ends with
does not end with
contains
does not contain
matches (regular expression)
does not match (regular expression)

For example, use an attribute subscription_plan of type String to give accounts that are on the Business or Enterprise plan a certain variant of a flag.

Set attributes

Set attributes capture the concept of a list of strings. Use set attributes with the following matchers:

is equal to
is not equal to
has any of
does not have any of
has all of
does not have all of
is part of
is not part of

For example, use an attribute us_states_visited of type Set to show a survey to users who have visited at least one state of the US West Coast.

Numeric attributes

Numeric attributes capture the concept of signed integers. Negative numbers are allowed. Floating point numbers are not supported. Use numeric attributes with the following matchers:

is =
is >=
is <=
is between (inclusive)
is not between (inclusive)

For example, use an attribute orders_last_quarter of type Number to provide a new premium shopping feature to customers who had at least 20 orders in the last quarter.

DateTime attributes

DateTime attributes capture the concept of a date, with optional time. Express the value of these attributes in milliseconds or seconds since epoch, depending on the SDK you use. Use DateTime attributes with the following matchers:

is on
is not on
is on or after
is on or before
is between (inclusive)
is not between (inclusive)

For example, use an attribute contract_signed of type DateTime to keep a legacy feature available for customers who signed up before 1/1/2015.

Boolean attributes

Boolean attributes capture the concept of true or false. Use boolean attributes with the following matcher:

For example, use an attribute homeowner of type Boolean to test the demand of a potential new feature among customers that don't own a home.