Target with custom attributes

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 how to use them when you create targeting rules in the Split web console. 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:

1. From the left hand navigation, click the icon at the top and then Admin settings. The Workspaces page appears.

2. Select the desired workspace. The All environments page appears.

3. Click the Traffic types tab and then the View/edit attributes selection. The Attributes page appears.

4. To create a custom attribute, click the Actions button, then the Create an attribute selection. The Create attribute page appears.

5. 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.

6. In the Name field, enter a human recognizable name (e.g., My new attribute).

7. In the Description field, optionally enter a description of the attribute.

8. 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.

9. 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.

1. From the left hand navigation, click the icon at the top and then Admin settings. The Workspaces page appears.
2. Select the desired workspace. The All environments page appears.
3. Click the Traffic types tab and then the View/edit attributes selection. The Attributes page appears.
4. To create a custom attribute, click the Actions button, then the Create multiple attributes selection. The Create multiple attributes page appears.
5. 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.
6. 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:

1. In the Set targeting rule, click the attribute field. A list of attributes displays.
2. Either select the desired attribute or enter a desired attribute.
3. Select a matcher. For more information about matchers, refer to the Supported types and matchers section below.
4. Either select the suggested values for the attribute you want Split to match or enter the ones you want.
5. Select how you want to serve your 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 have input a custom attribute, you are prompted to choose 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_date on 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 split uses an attribute whose value is not provided in code. For example, refer to the following split definition:

if user.age <= 60 then split 100%:on
else 
if user is in segment all then split 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 split 100%:off, which is off.

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

if user.plan_type is in list ["basic"] then split 100%:on
else
if user is in segment all then split 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 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 split 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 picklist 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:

• is

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.