Set up list attributes

List attributes are a type of external attribute segments visitors that are part of an audience you have already defined somewhere outside of Optimizely Web Experimentation. You can import custom lists of users, and then create audience conditions based on those lists.

Some common uses for list attributes include:

• Target your premium subscribers by uploading a list of cookies for each subscriber that you identified offline.
• Target VIP members in your loyalty program by uploading a list of cookies for loyal customers from your data warehouse or business intelligence platform.
• Query your analytics tool to target users who have signed up for your newsletter but have not purchased anything.
• Upload a list of cookies or query parameters from your email service provider for users who qualify for an upcoming promotion.
• Target users who live in ZIP codes with particular demographic traits or political affiliations.

How list attributes work 

Imagine your data warehouse team provided you with a list of customer account IDs in a CSV file. These accounts are identified as having “high upsell potential,” and your goal is to target visitors from these accounts in an experiment with various upsell options, so you can determine which options are most likely to drive conversions.

The first thing you do is match visitors to your site with their account IDs with the use of a cookie. (If you are not sure how this process works for your site, ask your web development team for help.)

Next, configure a list attribute with the following information:

• The name of the list (such as high-upsell-potential)
• The name and type of the on-site identifier for this list (such as customer_id)

After uploading the CSV containing your list of account IDs to Optimizely Web Experimentation, you will build a segmented audience and launch an experiment targeted with that audience.

When a visitor logs in and your website creates a customer_id cookie, the Optimizely Web Experimentation snippet reads it and send the cookie's value to the list attributes targeting service. If the account ID matches any of your lists, the targeting service responds with that information. Then the Optimizely Web Experimentation snippet reads the response to determine if your visitor matches your Optimizely Web Experimentation audience.

Create a list attribute

To create a list attribute:

1. Open the project where you want to use list attributes for targeting (list attributes are defined at the project level).
2. Go to Audiences > Attributes.
3. Click Create New Attribute > External Attribute.
   
4. Select List Attribute and click Create List Attribute to start the configuration wizard.
5. Enter a List Attribute Name, restricted to alphanumeric, hyphens (-), and underscores (_) only.
6. Select the list type to reflect the type of data your list will contain:
   • Cookies
   • Query parameters
   • Global JS variables
     When using the JS variable option, ensure that the variable is global. You cannot refer to embedded properties using dot notation, such as object.locator_name.
   • ZIP codes
7. Enter the name (such as Cookie Name) of the object selected in the previous step as it occurs in your website environment. Optimizely Web Experimentation will use this information to match visitors who are active on your website with the contents on your list attribute.
8. Click Next.
   
9. Click Done.

If you need to edit these settings later, return to the attributes dashboard and click on the name of your list.

Upload data 

After you create a list attribute, populate the list with data with one of the following upload methods.

• Direct upload lets you upload small lists (5mb or less) via your browser.
• Amazon S3 is a good option for larger lists.
• REST API may be suitable for some code-level integrations.

When formatting a list file, there are several best practices you should consider:

• Format files as a CSV or TSV file.
• Each row should contain a single ID.
• The file should contain one column of data (the first column populated with IDs).
• The file should have no header row (the first row should contain an ID).

A properly-formatted CSV file containing UUID-style IDs looks something like this:

Upload directly

If you have a small amount of data to upload (less than 5 MB), you can upload it directly in the Optimizely Web Experimentation web interface via direct upload:

1. In the project where you created your list attribute, go to the Attributes dashboard under Audiences > Attributes. 
2. Click More actions to the right of the modified date and select Data Upload.
   
3. In the direct upload tab, click Choose a file to upload. This opens a file browser where you can select the file which contains your list data.
   

Upload from Amazon S3

If your list is larger than 5 MB or you want to programmatically upload list data (useful when you want to write a script to automatically keep your list data fresh), S3 is the preferred method.

1. In the project where you created your list attribute, go to the Attributes dashboard under Audiences > Attributes. List attributes are grouped together at the bottom of the page.
2. Click the More actions icon to the right of the modified date and select Data Upload.
   
3. In the Upload via S3 tab, you see credentials to access your list’s S3 bucket.
   
4. Using these credentials, you can upload files in a variety of ways. The simplest approach is to use an S3 client application, such as Cyberduck. You can also upload files programmatically using the AWS CLI, an available SDK, or library.

Upload from REST API

You can update list attributes with a PATCH request via the REST API. To make a valid request, you need the following information:

• A personal access token
• The list attribute ID (accessible in the Upload Data panel for a List Attribute)

1. In the project where you created your list attribute, go to the Attributes dashboard under Audiences > Attributes. List attributes are grouped together at the bottom of the page.
2. Click the More actions icon to the right of the modified date and select Data Upload.
   
3. Select For real-time list uploads, use the REST API and enter the List Attribute ID.
   

Create an audience

To use a list attribute to target an experiment, create an Optimizely Web Experimentation audience and add your list attribute as an audience condition:

1. Go to Audiences > Saved.
2. Click Create Audience.
3. In the conditions list on the right side of the audience builder, you find your list attributes grouped together under the External Attributes heading.
4. Drag a list to the left to add it to your audience.
5. Click Save.