Using local storage and cookies for data capture

Abstract

Describes JavaScript Library data capture (Data model 2.0).

The Sitecore Customer Data Platform (CDP) uses the Boxever JavaScript Library to capture data about a Guest's behavior to use in tracking, decision making, and analytics, while ensuring General Data Protection Regulation (GDPR) compliance.

Sitecore CDP data capture is facilitated through a combination of cookies and local storage. Both methods store the same types of data and have the same Time to live (TTL) setting, by default. There is also an option to only use cookies and not local storage, but we do not recommend this (see the following section for more details). It is common practice that companies indicate on their website what cookies they are using. This also includes advertising and tracking cookies with a list of the third-party providers your company uses, including Sitecore.

Sitecore CDP cookies work with all browsers except Safari 12+

A cookie is a small file that your organization places on a user’s device (such as a PC, tablet, or mobile phone) to perform identity and data capture. Sitecore does not own the data that your organization collects through Sitecore cookies. After the cookie is set, it can only be read by your organization.

The Boxever JavaScript library places the following cookies on the site visitor's device:

  • The bid_{clientKey} cookie - persists the browser ID between sessions. It generates a Universally Unique Identifier (UUID) that is unique per browser until the cookie expires or is deleted, then a new UUID is generated. Sitecore CDP data capture cookies expire after two years of inactivity.

  • The bx_bucket_number cookie - only used if your organization has enabled at least one web experiment on your site. This cookie allocates the guest to a specific variant when using audience allocation. It performs allocation for each web experiment that is live on your site during the particular session. This session cookie is only stored for the duration of the session.

  • The boxever_test cookie - checks that the other cookies are working as expected then is immediately removed from the visitor's device.

For data capture, we recommend that you use Sitecore CDP cookies in conjunction with local storage. If your organization has strict privacy requirements and you only want to use cookies and not local storage, you can set the _boxever_settings.cookies_only property to true. We do not recommend this approach because the cookie TTL is determined by the browser that the guest happens to be using, therefore making data capture and persistence difficult.

In JavaScript Library Version 1.4.3, you can set the the_boxever_settings.cookies_only property to true to ensure that the browser's cookie behavior sets the TTL, for example, to one week.

Sitecore CDP local storage works with all browsers except Safari 12+.

For data capture, we recommend that you use Sitecore CDP cookies in conjunction with local storage, as supported in JavaScript Library versions 1.3.6+. This supports data capture even when Safari Intelligent Tracking Prevention (ITP) is employed. Safari ITP is the privacy feature that allows the Safari web browser to block cookies in Safari 12+ versions. Local storage is facilitated through the use of a local storage wrapper library. In JavaScript Library version 1.4.3+, local storage is only set when it is being used.

Adjusting the time to live for storage

The JavaScript Library versions 1.4.2+ provide a property that enables you to change the cookie and local storage expiry from the default of two years. This helps meet your organization's data retention requirements and offers flexibility if data retention procedures or laws change. The _boxever_settings.cookie_expiry_in_days property enables you to set the cookie and local storage expiry by days.

Note

Even though the name of the property implies that you can only adjust the TTL for cookies, this actually sets the TTL for both cookies and local storage.

Data captured by Sitecore CDP cookies and local storage

The following data is captured by Sitecore CDP and local storage:

  • bid_{clientkey} - the UUID (browser ID) stored against your organization's client key.

  • bx_bucket_number - the bucket number between 1 and 120 inclusive that is stored in the session. This only pertains to Sitecore CDP tenants that have web experiments enabled and where you want to set the traffic allocation for the variant.

If your organization uses the cookies-only approach, the same data is captured as set by the _boxever_settings.cookies_only property.

The cookies that the Sitecore CDP places on the visitor’s site are typically defined as first-party cookies, meaning the cookies are set by the domain name that appears in the web address bar.

There are scenarios when a Sitecore CDP session cookie is similar to a third-party cookie, for example, when you enable cross-domain support. This is true when the cookie is set by a website that is distinct from the website that appears in the web address bar. If this applies, a value is set against api.boxever.com and then the value is used in local storage to set first-party cookies across all domains.

The JavaScript Library versions 1.4.6 includes the optional _boxever_settings.itp_cross_domain setting which automatically applies the cross-domain setting only in respect to Intelligent Tracking Prevention (ITP) browsers, most commonly Safari. This ensures first-party cookies are used otherwise.

var _boxever_settings = { 
   // other settings...
   itp_cross_domain: true
};