Contact usRequest a demo

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. Many cookies also have configuration properties that let you change their names; refer to the configuration properties reference for more information.

The cookie x-unblu-session includes the API key after the prefix if the server is running in multi-account mode, even if only one Unblu account is configured.

The list below provides an overview of the cookies Unblu sets, what they’re used for, and when they expire. Where applicable, the appropriate configuration property to set the expiry of a cookie is noted where applicable.

All the cookies listed are functional cookies and are required by Unblu to provide its services.

x-unblu-agent
x-unblu-anonymous-person

  • Purpose: 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.

  • Expiry: com.unblu.identifier.anonymousPersonCookieMaxAge, default: 2147483647 s

x-unblu-authsession
x-unblu-conversation-session
x-unblu-device
x-unblu-lang

  • Purpose: Stores the user’s language preference. This cookie is used display the user interface in the user’s preferred language.

  • Expiry: Session

x-unblu-recorder-session

  • Purpose: Indicates that embedded co-browsing is active.

  • Expiry: Session

x-unblu-session

  • Purpose: Used when there is an active session with the Unblu Collaboration Server. The cookie is set as soon as the user interface is opened.

  • Expiry: Session

x-unblu-virtual-cookie-storage-session-marker

  • Purpose: Used to track when virtual session cookies expire.

  • Expiry: Session

x-unblu-virtual-cookie-storage

  • Purpose: Used to store the contents of the custom HTTP header x-unblu-set-cookie in certain cross-origin setups. See LOCAL_DOMAIN_STORAGE below for more information.

  • Expiry: Session

x-unblu-visitor-session
x-unblu-worker-origin

  • Purpose: Used to determine the correct worker node during embedded co-browsing.

  • Expiry: Session

The session authentication cookie x-unblu-authsession contains three pieces of information joined in the format <path><type>:<sessionId>:

  • <path> is the entry path the request originated from. Its value is U for a public entry path and T for an internal entry path.

  • <type> is the type of authentication. Its value is:

    • B for basic authentication

    • L for local authentication

    • P for propagagated authentication

    • U for authentication with an Unblu token

  • <sessionId> is a UUID generated using a cryptographically strong pseudorandom number generator.

If you’re using ID propagation for visitor single sign-on, the session ID may contain personally identifiable information (PII), so the content of the cookie is encrypted. For this, Unblu uses AES256 encryption with a dynamic 128-bit initialization vector (IV) and the Galois/counter mode (GCM). The initialization vector is created separately for each encryption and prepended to the encrypted value before Base64 encoding the entire string (initialization vector and value). The encryption key used is specified in the IMMUTABLE configuration property com.unblu.server.aes.encryptionKey.

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 automatically sets 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 uses .bank.com as the cookie domain. If they then navigate to https://www.bank.co.uk, Unblu transmits 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 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 Cloud, for example, they’re 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_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.