This document describes version 6 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version.

The support period for version 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu.

Unblu cookies

The Unblu server uses cookies for a number of purposes.

By default, the names of all of the cookies have the prefix x-unblu-. You can change the prefix with the configuration property com.unblu.identifier.cookieNamePrefix. Some cookies, such as x-unblu-session, include the API key after the prefix if multiple accounts are configured on the same server.

The table below provides an overview of the cookies Unblu sets, what they are used for, and when they expire. The appropriate configuration property to set the expiry of a cookie is noted where applicable. All of the cookies listed are functional cookies and are required by Unblu to provide its services.

Table 1. Unblu cookies
Cookie name	Purpose	Expiry
`x-unblu-anonymous-person`	Used to store session information for anonymous Visitors. For example, if a visitor is sent a link to a conversation by an agent, this cookie can be used to restore the visitor’s session.	com.unblu.identifier.anonymousPersonCookieMaxAge, default: 2147483647s
`x-unblu-authsession`	Session authentication	com.unblu.authentication.cloud.cookieMaxAgeSeconds, default: 604800s
`x-unblu-conversation-session`	Stores the conversation ID of an ongoing conversation. This can be used to determine whether a visitor has an ongoing conversation or not.	com.unblu.cookiestrategy.cookieExpirationTime, default: 90s
`x-unblu-device`	Identifies the browser and the device.	com.unblu.identifier.deviceCookieMaxAge, default: 2147483647s
`x-unblu-lang`	Stores the user’s language preference. This cookie is used display the user interface in the user’s preferred language.	Session
`x-unblu-recorder-session`	Indicates that embedded co-browsing is active.	Session
`x-unblu-session`	Used when there is an active session with the Unblu Collaboration Server. The cookie is set as soon as the user interface is opened.	Session
`x-unblu-worker-origin`	Used to determine the correct worker node during embedded co-browsing.	Session

Enabling subdomain switching

When a visitor accesses an Unblu-instrumented page, Unblu uses the page’s domain or subdomain when setting cookies. For example, if the visitor is on the page https://www.bank.com, Unblu uses www.bank.com as the cookie domain.

If you want Unblu sessions to remain active when visitors navigate to a different subdomain, you need to configure Unblu to enable subdomain switching. For this, you must specify a cookie domain in the Unblu server configuration file. The following configuration properties set the cookie domain for all requests:

In a cluster environment (com.unblu.identifier.clusterEnabled is set to true), set the cookie domain in the configuration property com.unblu.identifier.clusterUniverseCookieDomain.
In a non-cluster deployment (com.unblu.identifier.clusterEnabled is set to false), set the cookie domain in the configuration property com.unblu.identifier.cookieDomain.

If you need to specify a different cookie domain for the visitor context origin, you can do so with the configuration property com.unblu.identifier.visitorClientCookieDomain.

All three configuration properties can be set in one of two ways:

If you only need to maintain Unblu sessions across subdomains of a single domain, set the configuration property as follows:
```
com.unblu.identifier.cookieDomain=.bank.com (1)
com.unblu.identifier.clusterUniverseCookieDomain=.bank.com (1)
com.unblu.identifier.visitorClientCookieDomain=.bank.com (1)
```
1 Note the period . at the beginning of the property value.

In this case, Unblu will use .bank.com as the cookie domain when creating cookies. If a visitor navigates to a subdomain such as chat.bank.com and the Unblu snippet is present on that page, the Unblu session will remain active.
If you want to store the same Unblu cookie information across multiple domains, set the configuration property as follows:
```
com.unblu.identifier.cookieDomain=automatic
com.unblu.identifier.clusterUniverseCookieDomain=automatic
com.unblu.identifier.visitorClientCookieDomain=automatic
```
Unblu will automatically set the cookie domain to be the most general domain of the current context origin. For example, if the visitor is on https://www.bank.com, Unblu will use .bank.com as the cookie domain. If they then navigate to https://www.bank.co.uk, Unblu will transmit cookies with the same values and associate them with the domain .bank.co.uk.

The automatic approach also works for subdomains within a single domain.

Unblu cookies in cross-origin setups

When the Unblu server sets cookies, it does so with two different types of HTTP headers:

The standard set-cookie HTTP headers for the cookies described in the previous section.
A custom HTTP header called x-unblu-set-cookie that contains the same Unblu cookies, but packaged in a custom format.

If you use the Unblu Financial Cloud, or deployed Unblu in a cross-origin setup, Unblu cookies sent in the standard response headers are associated with the domain where Unblu is running. In the case of the Unblu Financial Cloud, for example, they are associated with https://unblu.cloud. This means these cookies are third-party cookies when a visitor is on your website. Due to the way browsers treat third-party cookies, visitors may therefore be unable to use Unblu on your website if you don’t take additional measures.

How the Unblu JavaScript stores the data sent in the custom HTTP header depends on the configuration property com.unblu.server.cors.corsCookieMode. If Unblu and your website are running on different domains, you must choose between the following two settings:

LOCAL_DOMAIN_COOKIE: The JSON object containing copies of the Unblu cookies is stored in a cookie called x-unblu-virtual-cookie associated with the domain and subdomains your website is running on. For example, if the instrumented page is accessible at https://ebanking.bank.com, x-unblu-virtual-cookie will be associated with .bank.com. This option has the advantage that the cookies are accessible on all subdomains of your website, like normal HTTP cookies. On the other hand, the visitor’s browser will transmit the cookies with each call to the domain, increasing the amount of network traffic.
LOCAL_STORAGE: The JSON object containing copies of the Unblu cookies is stored as a localStorage data item associated with the domain of the instrumented page.

If your deployment isn’t a cross-origin setup, you needn’t set com.unblu.server.cors.corsCookieMode explicitly. The default value, PRODUCT_DOMAIN, will work for you.