Integrate Google Analytics Tracking
Introduction
Goal
Use Google Analytics visitor tracking in your Hippo-based sites and monitor the statistics in the CMS.
Background
Hippo CMS provides support for tracking site visitors using Google Analytics. This page gives an overview of the functionality provided and the steps required to use it in your site and the CMS.
Provided Functionality
The Google Analytics support consists of the following three modules:
- org.onehippo.cms7.hst.client-modules:hst-google-analytics-repository: Google Analytics configuration service.
- org.onehippo.cms7:hippo-cms-google-analytics-frontend: Document hits plugin that can be added to a document editor template to show a graph showing the hit count over a configurable period of time.
- org.onehippo.cms7.hst.client-modules:hst-google-analytics-hst: tags and tracking code to incorporate Google Analytics tracking into an hst site.
To use this functionality specify the following dependencies in your poms:
cms/pom.xml:
<dependency> <groupId>org.onehippo.cms7</groupId> <artifactId>hippo-cms-google-analytics-frontend</artifactId> </dependency> <dependency> <groupId>org.onehippo.cms7.hst.client-modules</groupId> <artifactId>hst-google-analytics-repository</artifactId> </dependency>
site/pom.xml:
<dependency> <groupId>org.onehippo.cms7.hst.client-modules</groupId> <artifactId>hst-google-analytics-hst</artifactId> </dependency>
Set up Google Analytics Tracking for your Site
If you haven't set up a Google Analytics account yet you will need to do that first. Go to http://www.google.com/intl/en/analytics/ and sign up for google analytics. You will probably want to create a dedicated Google account for this.
You'll also need to enable OAuth 2.0 access to Google Analytics API, for which you should follow the Java quickstart for service accounts
After finishing Google Analytics API setup, a new service account will be created and you'll also be presented with an option to generate a new P12 key file. We'll need this file to authenticate with Google Analytics API from Hippo CMS application. Note: you only get this key file once, so safeguard it properly, or else you will need to generate a new one.
Make sure you also allow access to the generated service account (email address) through the http://www.google.com/intl/en/analytics/ admin panel.
After this, you can verify your account settings by visiting: https://ga-dev-tools.appspot.com/query-explorer/
Configure the Account ID
Assuming you have successfully set up a Google Analytics account and Google Analytics API OAuth 2.0 access service account, the first thing you need to do is to configure the account id in the repository.
The account id is used by the tracking code. It is sent to Google Analytics as part of the tracking request whenever a user requests a page on your site.
You can find this id by logging into Google Analytics and viewing the account information by clicking the name of the account in the account listing. You will be presented with a listing of website profiles. Next to the name of the website you have configured you will see a string starting with UA- and then a number. This is your account id.
Go to the CMS console and browse to the node /hippo:configuration/hippo:modules/googleAnalyticsConfiguration/hippo:moduleconfig. Specify the property hippogoogleanalytics:accountId with your account id.
You will probably want to add this configuration automatically when bootstrapping the repository. To do this add a file with the following contents to your content module:
<?xml version="1.0" encoding="UTF-8"?>
<sv:node xmlns:sv="http://www.jcp.org/jcr/sv/1.0"
xmlns:h="http://www.onehippo.org/jcr/xmlimport"
sv:name="googleAnalyticsConfiguration"
h:merge="combine">
<sv:node sv:name="hippo:moduleconfig" h:merge="combine">
<sv:property sv:name="hippogoogleanalytics:accountId" sv:type="String"
h:merge="override">
<!-- TODO: specify your account id -->
<sv:value>UA-XXXXX-XX</sv:value>
</sv:property>
</sv:node>
</sv:node>
and then in hippoecm-extension.xml add a corresponding initialize item:
<sv:node
sv:name="myhippoproject-prod-google-analytics-configuration-properties">
<sv:property sv:name="jcr:primaryType" sv:type="Name">
<sv:value>hippo:initializeitem</sv:value>
</sv:property>
<sv:property sv:name="hippo:contentresource" sv:type="String">
<sv:value>
hippo-configuration/google-analytics-configuration-properties.xml
</sv:value>
</sv:property>
<sv:property sv:name="hippo:contentroot" sv:type="String">
<sv:value>/hippo:configuration/hippo:modules</sv:value>
</sv:property>
<sv:property sv:name="hippo:sequence" sv:type="Double">
<sv:value>910</sv:value>
</sv:property>
</sv:node>
However, if you add this bootstrapping code to your default content module then the account id will be available during development of your site, and developer visits and page views will be registered with Google Analytics. This is probably something you will want to avoid. To do that you must add this bootstrapping configuration to a content module that is only deployed to a production environment.
Add the Tracking Code to your Site
To add Google Analytics tracking code to your site in order to start tracking your visitors first add the following taglib declaration to a global template, such as a general layout page that is always rendered:
JSP
<%@ taglib uri="http://www.onehippo.org/jsp/google-analytics" prefix="ga" %>
Freemarker
<#assign ga=JspTaglibs ["http://www.onehippo.org/jsp/google-analytics"] >
This imports the Hippo Google Analytics tag library. Then, in the same page, just before the closing html body tag add the following snippet:
JSP
<c:if test="${not hstRequest.requestContext.cmsRequest}">
<ga:accountId/>
<hst:link var="googleAnalytics" path="/resources/google-analytics.js"/>
<script src="${googleAnalytics}" type="text/javascript"></script>
</c:if>
Freemarker
<#if !hstRequest.requestContext.cmsRequest>
<@ga.accountId/>
<@hst.link var="googleAnalytics" path="/resources/google-analytics.js"/>
<script src="${googleAnalytics}" type="text/javascript"></script>
</#if>
The accountId tag inserts a piece of javascript inside your page that defines a javascript variable holding the account id. This is then used by the google-analytics.js script that is included next and which is also provided by the Google Analytics HST module.
Track Document Views instead of Page Views
The Google Analytics addon frontend module provides a CMS plugin that can show the number of times a document is viewed over time. However, in order for this plugin to work, your pages must tell Google Analytics to track the document path instead of the page path. You do this by using the <ga:trackDocument /> tag inside a detail page that shows the document you are interested in.
Say your site has a section that shows details of products like the Go Green demo site does. Then you will have a products detail page with a corresponding ProductDetail.java component. In this scenario you first add something like the following to your ProductDetail.java component class in order for the bean that represents the current product to be available in the template:
Product document = (Product) getContentBean(request);
if (document == null) {
redirectToNotFoundPage(response);
return;
}
request.setAttribute("document", document);
Then in the template that displays the product add the following tag:
JSP
<ga:trackDocument hippoDocumentBean="${document}"/>
Freemarker
<@ga.trackDocument hippoDocumentBean=document"/>
The tag will add a piece of javascript to your page that will be picked up later by the google-analytics.js we saw earlier.
Note that you can track multiple documents on a single page in cases where your pages display more than one document at a time. Do consider however that usually you don't want to let overview pages track documents as if they were viewed.
Add the Document Hits Plugin to the Editor
The Google Analytics addon frontend module provides a plugin for showing a graph of document views over time. The following describes how to add this plugin to the editor.
Configure Google Analytics Account Information
First you need to configure /hippo:configuration/hippo:modules/googleAnalyticsConfiguration/hippo:moduleconfig with the login details and data feed table id for accessing the Google Analytics data. Change the property hippogoogleanalytics:username with the Google Analytics API OAuth service account email address and upload the P12 key file to hippogoogleanalytics:privateKey binary property. You also need to set the value of the googleanalytics:tableId property. You can find this by going to the Google Analytics data export API query explorer, click on the dropdown labeled "click to list your accounts", and select your account. The table id is shown in the left input field.
Register the Plugin with the Editor
Assuming you have a document type with a two column layout editor add the following node to /hippo:namespaces/myhippoproject/mydocumenttype/editor:templates/_default:
<?xml version="1.0" encoding="UTF-8"?>
<sv:node sv:name="documentHits"
xmlns:frontend="http://www.onehippo.org/jcr/frontend/nt/2.0"
xmlns:sv="http://www.jcp.org/jcr/sv/1.0">
<sv:property sv:name="jcr:primaryType" sv:type="Name">
<sv:value>frontend:plugin</sv:value>
</sv:property>
<sv:property sv:name="caption" sv:type="String">
<sv:value>Document Hits</sv:value>
</sv:property>
<sv:property sv:name="interval" sv:type="String">
<sv:value>weeks</sv:value>
</sv:property>
<sv:property sv:name="numberofintervals" sv:type="String">
<sv:value>15</sv:value>
</sv:property>
<sv:property sv:name="plugin.class" sv:type="String">
<sv:value>org.onehippo.cms7.ga.editor.DocumentHitsPlugin</sv:value>
</sv:property>
<sv:property sv:name="wicket.id" sv:type="String">
<sv:value>${cluster.id}.right.item</sv:value>
</sv:property>
<sv:property sv:name="wicket.model" sv:type="String">
<sv:value>${wicket.model}</sv:value>
</sv:property>
</sv:node>
Registering the plugin for different layouts should be almost the same. The only difference will be the wicket.id property. Inspect the properties for the other registered plugins to see what values you can use.
The graph displayed by the plugin can be configured by the following two properties:
interval: the time interval between two data points or more technically: the Google Analytics dimension that is used. Possible values: days, weeks, months
Default value: weeks
numberofintervals: the number of data points on the graph or less technically: how far back in time your graph must display document hits
Default value: 10