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

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

In order to use custom attributes for audience targeting and results segmentaton, 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 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 Type

Child Attribute

Description

user
UserObject

This is a user object. Required.

type
string

Child attribute of type UserObject

This is a static value that indicates that you're using the user function. Required.

attributes
UserCustomAttributes

Child attribute of type UserObject

An 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 UserCustomAttributes

You 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 X 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 X 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
  }
});

Did this page help you?