List attributes

With list attributes, you can target users who are part of an audience you have already defined somewhere outside of Optimizely Web Experimentation. To do this, you will import custom lists of users and then create audience conditions based on those lists. Learn more about how to set up and use List Attributes.

To target an experiment with list attributes, you must:

1. Create a list, indicating where user IDs are stored in your web environment.
2. Upload data to populate the list.
3. Create an audience that uses your list in a condition.
4. Attach the audience to an experiment.

List attributes can be created through the Optimizely application or programmatically using the REST API.

Remember, 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 Optimizely's services or systems through List Attributes or any other feature.

See personally identifiable information to learn more about sending data to Optimizely and managing your users' information.

Data upload

Once you have created a list, you need to upload data before you can target users with a matching ID. Files uploaded via Direct Upload or Amazon S3 must have the following format:

• CSV or TSV file.
• One ID per row.
• One column of data (the first column populated with IDs).
• 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 if viewed in a spreadsheet:

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

You have many options for uploading list data.

Direct Upload

You can upload small list files (less than 5 MB) directly via the Optimizely Web Experimentation interface. This is a good option when you want to test out the feature or build a one-off list that won't need to be updated frequently in the future. See Set up list attributes.

Amazon S3

Optimizely provisions an Amazon S3 folder for each list attribute you set up in the web app. After you upload a file, we'll parse it and populate your list with its data. Files uploaded via S3 have no size limit.

You can upload your files in several ways. The simplest approach is to use an S3 client application such as Cyberduck.

Upload with Cyberduck

After you've downloaded and installed Cyberduck, follow these steps to upload a file:

1. Retrieve the list's AWS Access Key, AWS Secret Key, and S3 Import Path from the Optimizely interface (Audiences > Attributes > Your List > More Actions > Data Upload).
2. Launch Cyberduck and create a new Bookmark (Bookmark menu > New Bookmark).
3. Enter a descriptive name for the list and your AWS Access Key.
4. Click More Options to enter the S3 Import Path.

📘

Note

Cyberduck requires the full S3 import path, including both the optimizely-import bucket and the given s3_path. For example, if dcp/567/678 was the s3_path, you would need to use /optimizely-import/dcp/567/678.

5. View your bookmarks and double-click to connect to the S3 bucket. Cyberduck will prompt you to enter the AWS Secret Key from Step 1.

You are now connected to your list's S3 bucket!

6. Drag and drop the files to be uploaded using the Cyberduck interface.

This process may change in future versions of Cyberduck. See the official Cyberduck website for current documentation.

Upload programmatically

You can also upload files programmatically using the Amazon Web Services (AWS) Command Line Interface, an available AWS SDK, or an available library.

Retrieve the AWS credentials and S3 path from the list attribute endpoint.

After uploading a file to S3, check Upload History to confirm that your file has been processed. If you need to upload an updated version of your file, make sure that any files with the same name have already been processed. Unprocessed files with the same name in the same S3 path might be processed out of order, which would prevent your updates from being detected.

REST API

You can upload list data by making a PATCH request to the list attributes endpoint. To do this, format your list as a comma-separated string and pass it as the value of the optional list_content key.