Improve custom attribute persistence using browser cookies

  • Updated

This topic describes how to:

Increase the availability of custom attributes across origins.

Optimizely Web Experimentation and Optimizely Web Personalization use cross-origin targeting to persist information stored in browser localStorage across origin boundaries. Information in localStorage is used for many things, including:

Cross-origin targeting is effective at persisting localStorage information across origins for most visitors and browsers, but for custom attributes, you can accomplish even more reliable persistence with browser cookies. 

Optimizely Web Experimentation's Project JavaScript solution relies on a first-party browser cookie to persist custom attributes across origins. It's effective because browser cookies can be broadly scoped to a domain, whereas localStorage is scoped to the origin.

In the abstract, here's what Optimizely Web Experimentation's code for using browser cookies to persist custom attributes does:

  1. On snippet initialization, submits the custom attributes stored in the cookie to the snippet via the User API.

  2. After all campaigns and experiments have activated:

    • Queries the snippet for the visitor's custom attributes and merges those back into the cookie.

    • Shims window.optimizely.push so that any post-snippet initialization-pushes to the User API also result in the included attributes being written to the browser cookie, in addition to the usual localStorage.

This helps ensure that any custom attributes that are set before changing origins will be available for audience targeting and included in events for results segmentation—as long as the browser cookie is available after crossing an origin boundary.

Implement the solution

The code for this cookie-based solution is available here: https://gist.github.com/anonymous/eb7c91960307a1df733bcbc48fe751cd

  1. Place the code into Project JavaScript for any projects where you want to use the solution.

  2. Modify line 13 to include the domain where you want to set cookies.

    For example, to persist custom attributes between all origins on the domain atticandbutton.com (and its subdomains), update line 13 to read:

var COOKIE_DOMAIN = 'atticandbutton.com';

Optimizely Web Experimentation engineers have reviewed and tested this code, but it is provided as-is and without warranty. Take reasonable steps to ensure that this code will work in your environment, including:

  • Review with your engineering department

  • Implement in a QA or staging environment before deploying in production

Performance considerations

Code deployed via Project JavaScript will run each time the Optimizely Web Experimentation snippet initializes. This means that there will be a slight impact on your web page performance due to the extra code being evaluated.

In addition, data stored in browser cookies is sent along with network requests to the web servers on your domain (in other words, the servers or services responsible for serving your website).  Because this solution persists data by storing it in a cookie, it will increase the amount of data transmitted with each request to your web servers.

Cookie size considerations

Browsers can impose maximum size limits on cookies, and these limits vary by browser.  A rule of thumb is that browsers disallow cookies larger than 4,096 bytes, although your results may vary. Because this solution stores all custom attributes in a single browser cookie, you should confirm that the cookie will not exceed 4,096 bytes.

For reference, 100 custom attributes whose names and values are each 15 characters long will be approximately 3,700 bytes when serialized and stored in a cookie. If your attributes have API Names or values that are significantly longer than 15 characters, you could exceed the 4,096-byte limit, and this solution would not work as intended.

In addition to browser limitations, some web servers also impose a limit on the amount of cookie data they will accept with each request. Limits vary by web server and are typically configurable. If other cookies implemented on your page are large enough, the additional data stored in the cookie that this solution creates could push requests for some users over the limit. When the limit is exceeded, servers may stop responding to requests for new pages, which will affect visitors' ability to use your website. We recommend confirming that adding up to 4,096 bytes to your network requests will not put visitors over the limit your web servers impose.

Behavioral targeting and cookies

Behavioral targeting is an Optimizely Web Personalization feature that enables targeting based on visitor actions. Like custom attributes, the behavioral events that power this feature are stored in browser localStorage and can therefore be even more reliably persisted across origins using browser cookies.  

However, this solution is not suitable due to the large amount of data contained in behavioral events. Optimizely Web Personalization stores the last 1,000 events that a visitor triggers in localStorage. Typical behavioral events are 100 bytes, and they can be much larger if event tags are implemented.  For this reason, you shouldn't try to store all behavioral events in a browser cookie.

Even so, you might be able to adapt this solution to selectively persist information used for behavioral targeting. For example, if you have a behavioral audience which targets visitors based on their most frequently viewed product category, you can use the Customer Behavior API to retrieve this information and store it as a custom attribute. Then, you could update your behavioral audience definition to use this custom attribute to control targeting (instead of the default behavioral condition).

A backup copy of this code sample (which can be used if the anonymous gist in Implementation instructions is accidentally deleted) is at https://pastebin.com/raw/JVrJPWKY.