Dev GuideAPI ReferenceUser Guide
Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideProduct feedbackGitHubNuGetDev CommunitySubmit a ticketLog In
Product feedbackGitHubNuGetDev CommunitySubmit a ticket

User

Record the user's values for any number of dimensions or custom attributes

Use this API to record the user's values for any number of dimensions or custom attributes. The syntax is identical for both.

❗️

Warning

The Experimentation terms of service prohibit you from sending any personally identifiable information (PII) such as names, social security numbers, email addresses, or any similar data to the Experimentation system through list attributes or other features.

Custom attributes can be used for audience targeting as well as results segmentation.

In order to use custom attributes for audience targeting and result segmentation, you must first create the attribute in the Optimizely UI. The User API will allow you to use any API name to set attributes that haven't yet been created, but those attribute values will not be available for audience targeting or segmentation. If you later create a custom attribute using that same API name, previously stored values will be made available for audience targeting and segmentation the next time the Optimizely Web Experimentation snippet updates.

The values are saved in localStorage and are persisted across sessions, so you don't need to provide them again on future page loads.

Syntax

window["optimizely"].push(user);

Parameters

Parameter and TypeChild AttributeDescription
user
UserObject		N/AThis is a user object. Required.
type
string		Child attribute of type UserObjectThis is a static value that indicates that you're using the user function. Required.
attributes
UserCustomAttributes		Child attribute of type UserObjectAn object that maps custom attribute IDs or custom attribute API names to the user's value for each custom attribute. Custom attribute values must be strings, or null if you want to remove the previously set value.
*
string or integer		Child attribute of type UserCustomAttributesYou can specify additional properties of your choice.

Example Call

window["optimizely"].push({
  "type": "user",
  "attributes": {
    "123": "custom attribute value",
    "customAttributeApiName": "this is also a custom attribute value"
  }
});

Examples

Specifying a custom attribute by ID

You can specify a custom attribute by using its ID as the key for an entry in the attributes object. Once you've created a custom attribute in the Optimizely UI, an ID will be generated and displayed under Audiences > Attributes.

Example code for specifying a custom attribute by ID

window["optimizely"].push({
  type: "user",
  attributes: {
    123: "gold"
  }
});

Specifying a custom attribute by API name

You can specify a custom attribute by using its API name as the key for an entry in the attributes object. You provide the API name when creating a custom attribute in the Optimizely UI under Audiences > Attributes.

Example code for specifying a custom attribute by API name

window["optimizely"].push({
  type: "user",
  attributes: {
    frequentFlyerStatus: "gold"
  }
});

Unsetting a user's custom attribute value

If you want to remove a custom attribute value that had previously been set for a user, you can do that by providing a value of null.

Example code for unsetting a user's custom attribute value

window["optimizely"].push({
  type: "user",
  attributes: {
    frequentFlyerStatus: null
  }
});