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 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.
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 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
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
}
});