Skip to main content
menu_icon.png

Everything you need to switch from Optimizely Classic to X in one place: See the Optimizely X Web Transition Guide.

x
Optimizely Knowledge Base

Set up list attributes

relevant products:
  • Optimizely Classic
  • Optimizely X Web Experimentation
  • Optimizely X Web Personalization

This article will help you:
  • Use custom lists of data to target experiences
  • Create list attributes and create audience conditions based on them
  • Run experiments for groups of visitors not easily captured by other Audience conditions

List attributes are a type of external attribute that enable you to target visitors that are part of an audience you have already defined somewhere outside of Optimizely. They allow you to import custom lists of users, and then create audience conditions based on those lists.

List Attributes are available with the Web Enterprise package in Optimizely X.

Some more common use cases for list attributes include:

  • Targeting your premium subscribers by uploading a list of cookies for each subscriber that you’ve identified offline

  • Targeting VIP members in your loyalty program by uploading a list of cookies for loyal customers from your data warehouse or business intelligence platform

  • Querying your analytics tool to target users who have signed up for your newsletter but never purchased anything

  • Uploading a list of cookies or query parameters from your email service provider for users who qualify for an upcoming promotion

  • Targeting users who live in ZIP codes with particular demographic traits or political affiliations

Remember that your terms of service prohibit you from sending any personally identifiable information (such as names, social security numbers, email addresses, or any similar data) to the Optimizely services, through list attributes or otherwise.

How list attributes work 

Imagine your data warehouse team has provided you with a list of customer account IDs in a CSV file. These accounts have been 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'll have to do is match visitors to your site with their account IDs. This is often done with the use of a cookie; if you aren't sure how this process works for your site, ask your web development team for help.

Once you have this information, you're ready to configure a list attribute. During the configuration process, you'll need access to the following information:

  • The name of the list (for this example, we will name the list “high_upsell_potential”)

  • The name and type of the on-site identifier for this list (for this example, we will use a cookie named account_id)

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

When a visitor logs in and your website creates an account_id cookie, the Optimizely snippet will read 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 snippet reads the response to determine if your visitor matches your Optimizely audience.

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. Navigate to Audiences > Attributes.

  3. Click Create New Attribute > External Attribute.

  4. Select List and click Create List Attribute to start the configuration wizard.
    list_attributes_1.png

  5. Provide a list attribute name. Note that characters used in list attribute names are restricted to alphanumeric, hyphens, and underscores only.

  6. Configure the list type to reflect the type of data your list will contain:

  • Cookies

  • Query parameters

  • Global JS variables

  • ZIP codes

  1. Enter the name of the object selected in the previous step as it occurs in your website environment. Optimizely will use this information to match visitors who are active on your website with the contents on your list attribute.

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

Upload data 

Once you’ve created a list attribute, you'll populate the list with data, via one of three upload methods. Direct upload allows you to upload small lists (5mb or less) via your browser; Amazon S3 is a good option for larger lists; and the REST API may be suitable for some code-level integrations.

Uploading fresh data to an existing list will overwrite the previous data contained in the list.

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

  • Files should be formatted 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 (i.e. the first row should contain an ID)

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

sample-CSV-file-containing-UUID-style-IDs.png

Direct upload

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

  1. In the project where you created your list attribute, navigate to the Attributes dashboard under Audiences > Attributes. You’ll find all of your list attributes 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 direct upload tab, click the link to choose a file to upload. This will open a file browser where you can select the file which contains your list data.

Amazon S3

If your list is larger than 5mb or you would like 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, navigate to the Attributes dashboard under Audiences > Attributes. You’ll find all of your list attributes 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’ll 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.

REST API

It is possible to update list attributes with a PATCH request via the REST API. In order to make a valid request, you will need the following information:

  • A personal access token

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

list_attribute_id.png

Create an audience

In order to use a list attribute to target an experiment, you’ll need to create an Optimizely audience and add your list attribute as an audience condition:

  1. Navigate to Audiences > Saved.

  2. Click Create Audience.

  3. In the conditions list on the right side of the audience builder, you’ll find all 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.