Visitors, Visits and Cookies

Cookie

For the Relevance Module to work across requests, the site needs to be able to track the visitor. For this purpose a cookie is used, with the name _visitor (by default) and an expiration time of 2 years. The cookie contains the visitor ID. Note that this is very similar to the way a regular HTTP session ID is stored.

The only information that is stored in the cookie is the visitor ID, in the UUID format by default, that does not contain any information in itself apart from an identifier to distinguish the visitor from other visitors.

This cookie is likely to fall under the 'Activities unlikely to fall within the exception' section of the cookie guidance document:

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

This implies that visitors do need to acknowledge that a cookie will be installed.

Returning Visitor

A returning visitor is identified solely by the fact that a cookie is available on the first request.

Clustering

The visitor data is persisted in a shared backend SQL database. Since the Relevance Module uses a dedicated cookie, requests can be served by any site node; there is no need for (sticky) http sessions.

HttpOnly Cookie

If, for security reasons, you want the _visitor cookie to be HttpOnly, you can achieve this by configuring:

/targeting:targeting:
  targeting:cookiesHttpOnly: true

If not configured, by default, the _visitor cookie won't have the secure flag.

Secure Cookie

If, for security reasons, you want the _visitor cookie to have the secure attribute, you can achieve this by configuring:

/targeting:targeting:
  targeting:cookiesSecure: true

If not configured, by default, the _visitor cookie won't be http only.

Custom Visitor Cookie Name

The Relevance Module reads and writes a visitor cookie.

In Bloomreach Experience Manager 14.x, this cookie is named "_visitor" by default.

As of Bloomreach Experience Manager 15.0, this cookie is named "visitor" by default.

It's possible to configure the name of the visitor cookie on the node /targeting:targeting:

For example, if the above property is set to "_br_uid", then Relevance Module will start reading and writing a visitor cookie named "_br_uid" instead.

/targeting:targeting:
  targeting:visitorCookieName: visitor

Custom Visitor ID and Visit ID Value Generation

By default, Relevance Module generates ID values in the UUID format for a new visitor and a new visit.

In Bloomreach Experience Manager 12.5 and newer, it is possible to customize the ID value generation by overriding the default com.onehippo.cms7.targeting.VisitorIdsGenerator component.

The VisitorIdsGenerator interface looks like this:

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();

}

Just as an example, you might want to remove all the hyphens from the generated UUIDs like the following:

package com.example.cms.targeting;

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

/**
 * My 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();
    }
}

Now you can apply the custom VisitorIdsGenerator component by defininig a bean like the following in a bean assembly XML file (e.g, my-visitor-ids-generator.xml) in site/components/src/main/resources/META-INF/hst-assembly/overrides/addon/com/onehippo/cms7/targeting/ folder.

<?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>

</bean>

You have configured a custom VisitorIdsGenerator component by the bean ID, "com.onehippo.cms7.targeting.VisitorIdsGenerator", and the custom component will generate visitor IDs and visit IDs based on your implementation as soon as it is applied.