Add the Relevance Module to a Project
Introduction
Goal
Add the Relevance Module to a Bloomreach Experience Manager implementation project.
Background
The Relevance Module is an optional Bloomreach Experience Manager module. This page explains how to add the Relevance Module to a project, and configure its data stores in a local Cargo-based development environment. After the steps explained below, the CMS application will contain an additional perspective called 'Audiences'.
Installation through Essentials
As of Bloomreach Experience Manager v12.1, the installation of the Relevance Module is supported through Essentials (v4.1). If you start developing a new project, ensure that you "Make use of Enterprise features", navigate to the Library tab in Essentials, locate the Relevance 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 Google API key as described at the bottom of this page, in order to get a working visitor location map in the Relevance module's Audiences tab.
Manual Installation Instructions
Start with a Bloomreach Experience Manager project created from the Bloomreach Experience Manager archetype, as explained in Set up a Bloomreach Experience Manager Project.
Add Maven Dependencies
Add the following Maven dependencies:
cms/pom.xml:
<dependency> <groupId>com.onehippo.cms7</groupId> <artifactId>hippo-addon-targeting-dependencies-cms</artifactId> <type>pom</type> </dependency>
site/pom.xml:
<dependency> <groupId>com.onehippo.cms7</groupId> <artifactId>hippo-addon-targeting-dependencies-site</artifactId> <type>pom</type> </dependency>
Add Geo Location Database
The Relevance Module uses the geo location database of MaxMind to map IP addresses to cities and countries. This database comes in two flavors:
-
GeoLite2 City (free, less accurate)
-
GeoIP City (paid, more accurate than the lite version)
To use the free GeoLite City database, add the following dependency to your site's pom.xml:
site/pom.xml:
<dependency> <groupId>com.onehippo.cms7</groupId> <artifactId>hippo-maxmind-geolite2</artifactId> <version>20161123</version> <scope>runtime</scope> </dependency>
Add the Elasticsearch Maven Plugin to the Cargo Run Profile
In your local Cargo-based development environment, use the Elasticsearch Maven Plugin to add an Elasticsearch instance to store visits data.
In your project's top-level pom.xml, locate the cargo.run profile. Make the following changes the the profile:
Add the following properties to the profile's <properties> element:
<properties>
<targeting.bootstrap>false</targeting.bootstrap>
<targeting.truncate>true</targeting.truncate>
<es.path>${project.build.directory}/storage</es.path>
<sql.driver>org.h2.Driver</sql.driver>
<sql.username>sa</sql.username>
<sql.password />
<sql.url>jdbc:h2:${repo.path}/targeting/targeting;AUTO_SERVER=TRUE</sql.url>
<es.httpPort>9200</es.httpPort>
<es.tcpPort>9300</es.tcpPort>
<es.skip.start>false</es.skip.start>
</properties>
For version 12.0 add the following properties for the Elasticsearch plugin:
<maven.plugin.elasticsearch.version>6.6</maven.plugin.elasticsearch.version>
<maven.plugin.elasticsearch.configuration.version>5.6.10</maven.plugin.elasticsearch.configuration.version>
Directly after the profile's <plugins> opening element, add the following plugin configuration:
<plugin>
<groupId>com.github.alexcojocaru</groupId>
<artifactId>elasticsearch-maven-plugin</artifactId>
<version>${maven.plugin.elasticsearch.version}</version>
<configuration>
<clusterName>esDevCluster</clusterName>
<httpPort>${es.httpPort}</httpPort>
<transportPort>${es.tcpPort}</transportPort>
<version>${maven.plugin.elasticsearch.configuration.version}</version>
<keepExistingData>true</keepExistingData>
<timeout>60</timeout>
<skip>${es.skip.start}</skip>
</configuration>
<executions>
<execution>
<id>start-elasticsearch</id>
<phase>validate</phase>
<goals>
<goal>runforked</goal>
</goals>
</execution>
<execution>
<id>stop-elasticsearch</id>
<phase>post-integration-test</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
This will start up a local Elasticsearch instance when running mvn -P cargo.run. The visits data store is configured to use this local Elasticsearch instance by default.
Configure an H2 Database JNDI Data Source
In your local Cargo-based development environment, configure a JNDI data source to store requests, visitors and statistics data in the embedded H2 SQL Database.
Add the following JNDI data source configuration to conf/context.xml:
<Resource name="jdbc/targetingDS" auth="Container" type="javax.sql.DataSource"
maxTotal="100" maxIdle="10" initialSize="10" maxWaitMillis="10000"
testWhileIdle="true" testOnBorrow="false" validationQuery="SELECT 1"
timeBetweenEvictionRunsMillis="10000" minEvictableIdleTimeMillis="60000"
username="sa" password=""
driverClassName="org.h2.Driver"
url="jdbc:h2:${repo.path}/targeting/targeting;MVCC=TRUE"/>
The requests, visitors and statistics data stores are configured to use the jdbc/targetingDS data source by default.
Configure a JNDI Environment Variable for Elasticsearch Properties
In your local Cargo-based development environment, add a JNDI environment variable that contains configuration properties for connecting to Elasticsearch. Add the following JNDI environment variable to conf/context.xml:
<Environment name="elasticsearch/targetingDS" type="java.lang.String"
value="{'indexName':'visits', 'locations':['http://localhost:9200/']}" />
The visits data store will use these properties to instantiate a client for connecting to the Elasticsearch webapp that you added previously.
Add Logger to log4j2-dev.xml and log4j2-dist.xml
Add the following logger to conf/log4j2-dev.xml and conf/log4j2-dist.xml:
<Logger name="com.onehippo.cms7.targeting" level="warn"/>
Rebuild and Restart
Stop the application (if it was running), and rebuild and (re)start it as explained in the Getting Started Trail.
Verify that the Elasticsearch webapp is running correctly by browsing to the following URL:
http://localhost:9200/_cat/indices?v
You should see something like this:
health status index pri rep docs.count docs.deleted store.size pri.store.size green open visits 1 0 0 0 159b 159b
Configure Google API Key
To enable the map widget in the on the Realtime tab of the Audiences perspective, configure your Google API key.
Using the Console, browse to the node /hippo:configuration/hippo:frontend/cms/hippo-targeting/experience-optimizer-perspective.
Add a String property google.api.key and set its value to your Google API key:
/hippo:configuration/hippo:frontend/cms/hippo-targeting/experience-optimizer-perspective: /google.api.key = YOUR_API_KEY
Optional: Add the Collectors Bundle
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. See Add the Collectors Bundle to a Project for more information and instructions.