User

8 min

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

Warning The Optimizely 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.

To use custom attributes for audience targeting and result segmentation, you must first create the attributecreate the attribute in the Optimizely UI. The User API lets you use any API name to set attributes that have not yet been created, but those attribute values are not available for audience targeting or segmentation. If you later create a custom attribute using that same API name, previously stored values are made available for audience targeting and segmentation the next time the Web Experimentation snippet updates.

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

Syntax

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

Parameters

Parameter and Type	Child Attribute	Description
user UserObject	N/A	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

Specify 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. After create a custom attributecreate a custom attribute in the Optimizely UI, an ID is generated and displayed in Audiences > Attributes.

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

Specify 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 attributecreating a custom attribute in the Optimizely UI in Audiences > Attributes.

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

Unset 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.

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