Add the Relevance Module to a Project - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 11. There's an updated version available that covers our most recent release.

12-04-2019

Add the Relevance Module to a Project

This feature is only available in Hippo DX.

Introduction

Goal

Add the Relevance Module to a Hippo implementation project.

Background

The Relevance Module is an optional Hippo DX 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'.

Instructions

Start with a Hippo DX project created from the Hippo archetype, as explained in Set up a Hippo DX 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:

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>20160405</version>
      <scope>runtime</scope>
    </dependency>

Add an Elasticsearch Webapp to Cargo

In your local Cargo-based development environment, add an Elasticsearch webapp to store visits data.

In your projects top-level pom.xml, locate the cargo.run profile. If you haven't modified this profile, you can copy and paste the XML from this file and skip the steps below.

Add a <dependencies> child element to <profile>, and add the following dependency:

      <dependencies>
        <dependency>
          <groupId>com.onehippo.cms7</groupId>
          <artifactId>hippo-addon-targeting-demo-support-elasticsearch</artifactId>
          <version>${hippo.addon-targeting.version}</version>
          <type>war</type>
        </dependency>
      </dependencies>

Add a <properties> child element to <profile>, and add the following property:

      <properties>
        <es.path>${project.build.directory}/storage</es.path>
      </properties>

Locate the <systemProperties> section (in the <container> section), and add the following system property:

<es.path>${es.path}</es.path>

Locate the <deployables> section, and add the following deployable:

                <deployable>
                  <groupId>com.onehippo.cms7</groupId>
                  <artifactId>hippo-addon-targeting-demo-support-elasticsearch</artifactId>
                  <type>war</type>
                  <properties>
                    <context>/elasticsearch</context>
                  </properties>
                </deployable>

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 New Loggers to log4j-dev.xml and log4j-dist.xml

By default, all relevance logs are written to hippo-cms.log. However, all relevance code except for the Visitor Analysis runs in the site webapp. Hence, make sure you add to conf/log4j-dev.xml and conf/log4j-dist.xml the following loggers:

<logger name="com.onehippo.cms7.targeting.frontend">
    <level value="warn"/>
</logger>

<logger name="com.onehippo.cms7.targeting">
    <level value="warn"/>
</logger>

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.

 

This product includes GeoLite2 data created by MaxMind, available from http://www.maxmind.com.
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?