Add the Collectors Bundle to a Project

Introduction

Goal

Add the Collectors Bundle, which contains commonly used collectors, characteristics, and UI plugins, to a Bloomreach Experience Manager implementation project.

Background

The Relevance Module contains several collectors that are not bootstrapped by default. To make it easier to add these collectors to a project a Collectors Bundle has been created. The bundle is available as a jar file and contains commonly used collectors, characteristics, and UI plugins. This page describes what the bundle contains and how it can be used in a project.

Installation through Essentials

The Relevance Collectors Bundle can be installed into your project through Essentials. If you start developing a new project, ensure that you check Make use of Enterprise features, navigate to the Library tab in Essentials, locate the Relevance Collectors Bundle feature and click Install feature. Essentials then applies the steps documented for manual installation below to your project. Rebuild and restart your project, and configure the collectors as described below.

Manual Installation Instructions

Add the bundle as a dependency to the pom.xml file of your project’s cms module:

  <dependency>
    <groupId>com.onehippo.cms7</groupId>
    <artifactId>hippo-addon-targeting-bundle-collectors</artifactId>
  </dependency>

Some collectors in the bundle require additional configuration, as described in Configure Collectors below.

Contents of the Collectors Bundle

Provided Collectors

The Collectors Bundle provides configuration for the following collectors:

Class Name	Collects
DayOfWeekCollector	The (server side) day of the week a visitor is viewing pages.
DocumentTypesCollector	The type of documents a visitor has viewed.
GroupsCollector	The groups a logged-in visitor belongs to.
ReferrerCollector	The external web page that led the visitor to our site.
ReturningVisitorCollector	Whether the visitor has visited the site before or not.
TagsCollector	The tags on documents a visitor has viewed.
CookieCollector	The HTTP cookies assigned to a visitor.
PrincipalsCollector	The name of the currently authenticated visitor if the visitor has been authenticated.
EngagementCollector	The Bloomreach Engagement segment assigned to the visitor. Available as of brXM 16.2.0. Requires integration with Bloomreach Engagement.

Provided Characteristics and Plugins

Visitor data for a collector is only updated if a corresponding characteristic has been configured for it. This is done to minimize the volume of visitor data and the number of back-end calls. The bundle provides characteristics (with corresponding UI plugins) for the following collectors:

Collector	Characteristic	Pre-configured Target Groups
DayOfWeekCollector	visits the site on a (day of the week)	Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday, Weekend
DocumentTypesCollector	mostly looks at (content type)
GeoIPCollector	comes from (continent)	Africa, Asia, Europe, North America, Oceania, South America
GroupsCollector	is logged in as (group)
ReferrerCollector	is referred from (url)
ReturningVisitorCollector	is a (returning or new visitor)	New visitor, Returning visitor
EngagementCollector	is segmented in (segment)

These collectors will therefore update visitor data after adding the bundle to your project. These collectors also come with a characteristics plugin so that the visitor data can be used to set up target groups for personalization.

Characteristics and UI plugins are not provided for the following collectors:

Collector

TagsCollector

PrincipalsCollector

These collectors will not update visitor data. If you want to use the collected data for personalization you will have to write your own characteristic and UI plugin.

Configure Collectors

The Collectors Bundle cannot provide all bootstrap configuration because some collectors require project specific configuration.

CookieCollector

The following optional property controls which cookies are collected:

Property name	Type	Example
cookies	Multi-valued String	cartID, domain1.user.prefs

The cookie name matching is case-sensitive, so ‘cartID’ will not match ‘CartID’.

If the cookie name contains dots, the collector will replace them by underscores (see section Dots in fields for more information) .

This collector only collects request data and does not update visitor data. As a result you cannot use this collector for personalization and a characteristic and UI plugin are not available.

RequestParamsCollector

This collector is bootstrapped by default via the Relevance Module. The values of those request parameters specified in the ‘params’ property will be saved as targeting request data.

Property name	Type	Example
params	Multi-valued String	q, query, search

The parameter name matching is case-sensitive so ‘Q’ will not match ‘q’.

If the parameter name contains dots then the collector replaces them by underscores.

This collector only collects request data and will not update visitor data. As a result you cannot use this collector for personalization and a characteristic and UI plugin are not available.

EngagementCollector

This collector integrates with the Segmentation feature of Bloomreach Engagement and requires configuration.

Prerequisites

• Contact your Bloomreach CSM to enable the "BrX Integration" feature for your Engagement account.
• Verify that you can access projects in Engagement with the correct user role (Project Admin) to manage project configuration.

Expose segmentations in Engagement

Any segmentation in Engagement that you'd like to use for content personalization in brXM needs to be exposed.

In Engagement, navigate to Analyses > Segmentations.

Use the Show only exposed toggle to show segmentations exposed for content personalization.

If you want to use a new or unexposed segmentation for page personalization in brXM, edit the segmentation, then click on the three dots in the top right, then choose Expose > Content personalization from the dropdown menu

Set up API access in Engagment

In Engagement, navigate to Project settings > Project > Access management > API and create a private API group. Save the API secret, you'll need it in the next step.

Under Group permissions, select the Brx tab and make sure Content integration is checked.

Configure Engagement API in brXM

The Engagement API configuration needs to be set up in brXM using the following system properties:

Property name	Description
engagement.project.id	Engagement project token
engagement.api.base.url	Engagement API base URL
engagement.api.key.id	Engagement API key ID
engagement.api.secret	Engagement API secret

For local development with Cargo, add these under the <systemProperties> section of the cargo.run profile in the project's root POM.

For Cloud or on-premise deployments, add these to the properties file.

Integrate Engagement tracking snippet in your site

The collector relies on the Engagement tracking snippet being integrated in the site.

In Engagement, select Settings > Web integration and copy-paste the tracking snippet.

Add the snippet at an appropriate place in your site.

For example, in a standard implementation project created using the Maven archetype, add the snippet to the <head> section in repository-data/webfiles/src/main/resources/site/freemarker/myproject/base-layout.ftl.