Visitors, Visits, and Cookies

This page describes how the Relevance Module in Bloomreach Content tracks visitors and visits using cookies, and how you can configure related behavior.

The Relevance Module requires a way to identify visitors across multiple requests. By default, it uses a cookie named visitor (or _visitor in earlier versions) with a two-year expiration. This cookie stores only the visitor ID, which is a UUID that uniquely identifies the visitor but does not contain any personal information.

This approach is similar to how HTTP session IDs are stored. The only data in the cookie is the visitor ID.

According to the ICO cookie guidance, this type of cookie is generally considered to require user consent:

"Cookies used to recognise a user when they return to a website so that the greeting they receive can be tailored"

Visitors must acknowledge that this cookie will be set.

Note: For details on implementing cookie consent, see Implement Tracking Cookie Consent and Configure the Relevance Module's Tracking Cookie Policy.

Returning Visitor

A returning visitor is identified when the visitor cookie is present in the first request of a session.

Clustering

Visitor data is stored in a shared backend SQL database. Because the Relevance Module uses a dedicated cookie, any site node can serve requests. Sticky HTTP sessions are not required.

To set the visitor cookie as HttpOnly for security reasons, configure the following property:

/targeting:targeting:
  targeting:cookiesHttpOnly: true

By default, the visitor cookie is not set as HttpOnly.

To set the visitor cookie with the secure attribute, configure the following property:

/targeting:targeting:
  targeting:cookiesSecure: true

By default, the visitor cookie does not have the secure flag.

The Relevance Module reads and writes a visitor cookie. The default name depends on the version:

brXM 14.x: _visitor
brXM 15.0 and later: visitor

You can configure the cookie name on the /targeting:targeting node:

Name	Type	v14 Default	v15 Default	Description
`targeting:visitorCookieName`	String	`_visitor`	`visitor`	Name of the visitor cookie used by the Relevance Module.

For example, to use the cookie name _br_uid:

/targeting:targeting:
  targeting:visitorCookieName: _br_uid

Important: The underscore in the v14 default (_visitor) can cause issues in some scenarios, such as when deploying to Bloomreach Cloud with an SPA frontend. To avoid problems, use a cookie name without an underscore, for example:

/targeting:targeting:
  targeting:visitorCookieName: visitor

Custom Visitor ID and Visit ID Value Generation

By default, the Relevance Module generates visitor and visit IDs as UUIDs. You can customize this behavior by overriding the com.onehippo.cms7.targeting.VisitorIdsGenerator component.

When implementing a custom VisitorIdsGenerator, ensure that each call returns a unique identifier (for example, using UUID.randomUUID().toString()). The Relevance Module requires unique IDs for each visitor and visit.

The VisitorIdsGenerator interface:

package com.onehippo.cms7.targeting;

/**
 * Visitor's IDs Generator Service.
 */
public interface VisitorIdsGenerator {

    /**
     * Create a new visitor ID.
     * @return new visitor ID
     */
    String createVisitorId();

    /**
     * Create a new visit ID.
     * @return new visit ID
     */
    String createVisitId();

}

Example: To generate UUIDs without hyphens:

package com.example.cms.targeting;

import java.util.UUID;
import org.apache.commons.lang.StringUtils;

/**
 * Custom Visitor's IDs Generator Service, returning UUID without hyphens.
 */
public class MyCustomVisitorIdsGenerator implements VisitorIdsGenerator {

    @Override
    public String createVisitorId() {
        return StringUtils.replace(newUUID(), "-", "");
    }

    @Override
    public String createVisitId() {
        return StringUtils.replace(newUUID(), "-", "");
    }

    private String newUUID() {
        return UUID.randomUUID().toString();
    }
}

Register your custom VisitorIdsGenerator by defining a bean in an assembly XML file (for example, my-visitor-ids-generator.xml) in the site/components/src/main/resources/META-INF/hst-assembly/overrides/addon/com/onehippo/cms7/targeting/ directory:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd">

  <bean id="com.onehippo.cms7.targeting.VisitorIdsGenerator"
        class="com.example.cms.targeting.MyCustomVisitorIdsGenerator">
  </bean>

</beans>

After registering the bean with the ID com.onehippo.cms7.targeting.VisitorIdsGenerator, the Relevance Module will use your implementation to generate visitor and visit IDs.

Visitors, Visits, and Cookies

Cookie

Returning Visitor

Clustering

HttpOnly Cookie

Secure Cookie

Custom Visitor Cookie Name

Custom Visitor ID and Visit ID Value Generation