Written by The Jahia Team
 
Developers
Sysadmins
   Estimated reading time:

Introduction

In this section, we list the various cookies used by jExperience and jCustomer to keep track of sessions and profiles. We use a standardized format to make it easy to understand the various important data about each of the cookies.

Cookies and domain matching

In order for a cookie to work properly, the following conditions must be met:

  • The cookie domain must match the domain it is sent to (ie: www.acme.com)
  • The cookie path must match the beginning of the URL path it is sent to (ie: /books)
  • The following rules also apply with new third-party cookie restrictions: when a site is loaded from a domain, only cookies on the SAME domain will be sent out (first-party cookies). For example, if a site is loaded from jahia.com and there is a cookie for google.com to send data to Google Analytics, the google.com cookie will NOT be sent (anymore) since third-party cookies are no longer supported by most modern browsers.

How jCustomer resolves profile IDs

jCustomer will use multiple methods to resolve a profile ID:

  • If a “context-profile-id” cookie is sent to a jCustomer request, it will use it
  • If a profileId is sent in the body of the request it will use it
  • If a “?sessionId=” is used in the URL request it will use it to resolve the session. Each session is associated with a profile ID, so it will use that one.
  • If a sessionID is sent in the body of a request it will use it to resolve the session, and then the associated profile.

context-profile-id

Description/use

This is a cookie set by jCustomer to store the profile ID on the client browser. It is used to keep track of the actions of visitors on sites managed by jExperience.

Since Lax configuration allows the cookie to be passed in top-level navigation only (only for links and URL change in browser), this cookie might be impacted by recent browser limitations. However, in our case we are using AJAX requests to load the context.

How it is set

jCustomer is responsible for setting this cookie. When a new request comes to the /context.json endpoint, it will check if it receives an existing cookie. If not, it will try to resolve the profile using other information such as the profile ID in the request body, or the session ID it was passed. If it still cannot resolve a profile, it will create a new profile and return a cookie that stored the profile identifier in the context-profile-id cookie.

Domain & path matching

context-profile-id and site on the same domain

When your site and jCustomer share the same domain or subdomain, the cookie will be passed during AJAX context loading, allowing jCustomer to retrieve the user profile from the cookie.

As a result, each new session will be attached to the existing profile as the context-profile-id cookie already exists on the client.

context-profile-id on a different domain

When your site and jCustomer are not sharing the same domain or subdomain, the cookie will not be sent to jCustomer during AJAX context loading. jCustomer cannot retrieve the current profile from the cookie and must retrieve the profile from the session ID (see wem-session-id cookie).

jCustomer can retrieve the user profile based on the current session ID, but if the wem-session-id cookie is expired or lost, jCustomer will be forced to create a new profile.

Parameters

Domain

  • Default value: same as jCustomer server domain
  • Can be configured: yes, this is configured in jCustomer in the `org.apache.unomi.profile.cookie.domain` property or the `UNOMI_PROFILE_COOKIE_DOMAIN` environment property

SameSite

  • Default value: Lax
  • Can be configured: no, hardcoded in jCustomer’s code

HTTPOnly

  • Default value: false
  • Can be configured: yes using the `org.apache.unomi.profile.cookie.httpOnly` property or the `UNOMI_PROFILE_COOKIE_HTTPONLY` environment property
  • Note: be careful if setting this setting to true, some jExperience functionality will no longer work, as the cookie value will not be accessible to the Javascript tracker.

Secure

  • Default value: depends in incoming request, if it is HTTP secure=false, if HTTPS secure=true
  • Can be configured: no

Expires

  • Default value: 1 year
  • Can be configured: yes using the `org.apache.unomi.profile.cookie.maxAgeInSeconds` or the `UNOMI_PROFILE_COOKIE_MAXAGEINSECONDS` environment property
  • What happens when the cookie expires: the profile will no longer be tracked and another profile with a different ID will be used.

Path

  • Default value: /
  • Can be configured: no, hardcoded in jCustomer code

wem-session-id

Description/use

This cookie is required by the jExperience wem.js script when loading the context, which allows to keep and reuse the jCustomer generated session UUID in the current site domain.

As this cookie is only read client-side by Javascript (jtracker and wem.js), the cookie is not impacted by browser restrictions because it’s not used during HTTP requests directly.

The session ID is reused by the wem.js context loading and the session ID is passed to the context request using JSON as an URL parameter.

jExperience checks if this cookie is already present in the browser:

  • if not, jExperience creates the cookie with a random UUID (new session)
  • if yes, jExperience reuses the cookie and remains on the same session ID (ongoing session)

How it is set

It is set by the jtracker tracking script, once it has finished loading the wem.js script, or when using server-side rendering it is done by the jExperience backend filter. 

Parameters

Domain

  • Default value: same domain as current site
  • Can be configured: no
  • What happens if the domain & path are not matched: a new session will be created

SameSite

  • Default value: Strict 
  • Can be configured: no, hardcoded in jExperience wem.js code

HTTPOnly

  • Default value: false
    Can be configured: no, never set in any code

Secure

  • Default value: false
  • Can be configured: no, never set in any code

Expires

  • Default value: session cookie, expires at client (browser) shutdown
  • Can be configured: no, hardcoded in jExperience wem.js code
  • What happens when the cookie expires: a new session with a new ID is created

Path

  • Default value: /
  • Can be configured: no, hardcoded in jExperience wem.js code

wem-profile-id

Description/use

This cookie is a copy of the context-profile-id into the existing context of the current Jahia site. It, therefore, ensures that the cookie is accessible to scripts coming from the domain of the current site.

How it is set

It is set by the wem.js script once the call to jCustomer’s context has been completed. Its value is copied from the response from jCustomer.

Parameters

Domain

  • Default value: same as the current site
  • Can be configured: no
  • What happens if the domain & path are not matched: upon the next context call a new cookie will be created

SameSite

  • Default value: Strict
  • Can be configured: no, hardcoded in jExperience wem.js code

HTTPOnly

  • Default value: false
  • Can be configured: no, never set in any code

Secure

  • Default value: false
  • Can be configured: no, never set in any code

Expires

  • Default value: session cookie, expires after client (browser) is shutdown
  • Can be configured: no, hardcoded in jExperience wem.js code
  • What happens when the cookie expires: in this case the profile will not be recognized until the context is reloaded

Path

  • Default value: /
  • Can be configured: no, hardcoded in jExperience wem.js code