Add the Relevance Module to a Project - Bloomreach Experience - Open Source CMS
28-02-2020

Add the Relevance Module to a Project

This Bloomreach Experience Manager feature requires a standard or premium license. Please contact Bloomreach for more information.

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 application called Content audiences.

Installation through Essentials

The installation of the Relevance Module is supported 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 feature and click Install feature. Essentials then applies most of the steps documented for manual installation below to your project.

 

Add a GeoIP database in order to collect visitor location data.

Rebuild and restart your project.

Finally, configure the Google API key in order to get a working visitor location map in the Relevance module's Audiences tab.

The Essentials Relevance feature includes bootstrap data to add the relevance system user to the webmaster group. However, due to the way configuration management works, this only works when bootstrapping a new repository and is ignored for existing repositories. Therefore, use one of the following two workarounds:

  • For new projects generated using the archetype only, delete the local storage folder before restarting your project after adding the Relevance feature.
  • In all other cases, including each redeployment in an existing environment after adding the Relevance feature, perform the manual step Add Relevance System User to Webmaster Group.

Manual Installation Instructions

Start with a Bloomreach Experience Manager project created from the Maven archetype, as explained in Set up a Bloomreach Experience Manager Project. Make sure the top-level pom.xml has the hippo-cms7-enterprise-release as parent.

Add Dependency to Top-level POM

To the top-level pom.xml, add 

 <dependencies>
    <dependency>
      <groupId>com.onehippo.cms7</groupId>
      <artifactId>hippo-addon-targeting-shared-api</artifactId>
      <scope>provided</scope>
    </dependency>
  </dependencies>

Note the above dependency must not be inside <dependencyManagement>.

To the cargo.run profile, add hippo-addon-targeting-shared-api as shared lib:

    <profile>
      <id>cargo.run</id>
      <build>
        <plugins>
          <plugin>
            <groupId>org.codehaus.cargo</groupId>
            <artifactId>cargo-maven2-plugin</artifactId>
            <configuration>
              <!-- snip --/>
              <container>
                <!-- snip --/>
                <dependencies>
                  <dependency>
                    <groupId>com.onehippo.cms7</groupId>
                    <artifactId>hippo-addon-targeting-shared-api</artifactId>
                    <classpath>shared</classpath>
                  </dependency>
                </dependencies>
              </container>
            </configuration>
          </plugin>

Add the following properties to the cargo.run profile's <properties> element:

      <properties>
        <targeting.bootstrap>false</targeting.bootstrap>
        <sql.url>jdbc:h2:${repo.path}/targeting/targeting;AUTO_SERVER=TRUE</sql.url>
        <sql.driver>org.h2.Driver</sql.driver>
        <targeting.truncate>true</targeting.truncate>
        <sql.username>sa</sql.username>
      </properties>

Add Dependency to CMS Dependencies POM

cms-dependencies/pom.xml:

    <dependency>
      <groupId>com.onehippo.cms7</groupId>
      <artifactId>hippo-addon-targeting-cms-dependencies</artifactId>
      <type>pom</type>
    </dependency>

Add Dependency to Site Components POM

site/components/pom.xml:

    <dependency>
      <groupId>com.onehippo.cms7</groupId>
      <artifactId>hippo-addon-targeting-site-dependencies</artifactId>
      <type>pom</type>
    </dependency>

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"/>

The requests, visitors and statistics data stores are configured to use the jdbc/targetingDS data source by default.

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"/>

Include the Targeting API in Shared Lib for Distribution

to myproject/src/main/assembly/shared-lib-component.xml, add:

<include>com.onehippo.cms7:hippo-addon-targeting-shared-api</include>

Disable Elasticsearch Support in HST Config Properties

If you plan to add Trends and Experiments, skip this step.

If you don't plan to use Trends and Experiments, disable Elasticsearch support in cms/src/main/webapp/WEB-INF/hst-config.properties:

targeting.elastic.disabled = true

Add GeoIP Database

To enable geolocation for visitors, follow Add the GeoIP/GeoLite Database to a Project.

Rebuild and Restart

Stop the application (if it was running), and rebuild and (re)start it as explained in the Get Started Trail.

Add Relevance System User to Webmasters Group

Using the Console, browse to the node /hippo:configuration/hippo:groups/webmaster.

Add the value hippo-relevance to the multi-valued String property hipposys:members. For example:

/hippo:configuration/hippo:groups/webmaster:
  hipposys:members: [hippo-relevance, editor]
For existing projects already deployed in one or more environments prior to adding the Relevance Module, this step must be repeated in each environment when redeploying after adding the Relevance Module.

Configure Google API Key

To enable the map widget in the on the Realtime tab of the Content audiences application, 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.

Optional: Add Experiments and Trends

The Relevance Experiments and Trends features are optional and require Elasticsearch. See Add Relevance Experiments and Trends to a Project for more information and instructions.

Run in Docker

To add Relevance support for Docker, follow the instructions below.

Add the following resource/environment configuration into context-mysql.xml or context-postgres.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="@[email protected]" password="@[email protected]"
 driverClassName="@[email protected]"
 url="jdbc:mysql://@[email protected]:@[email protected]/targeting?characterEncoding=utf8&amp;useSSL=false&amp;allowPublicKeyRetrieval=true"/>

Create an init.sql file at db-bootstrap folder or open the existing one, and add the following commands:

CREATE DATABASE targeting;
GRANT ALL PRIVILEGES ON targeting.* TO [email protected]'%';

Add Maven shared dependency

Open the project's root pom.xml and add the following dependency to the docker.build profile:

<dependency>
   <groupId>com.onehippo.cms7</groupId>
   <artifactId>hippo-addon-targeting-shared-api</artifactId>
   <scope>provided</scope>
</dependency>

 

Add Logger to log4j2-docker.xml

Add the following logger to conf/log4j2-docker.xml:

    <Logger name="com.onehippo.cms7.targeting" level="warn"/>
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?