Google Analytics module

The Google Analytics module integrates Magnolia websites with Google Analytics. The module is based on the gaTracker jQuery plugin designed by Jason Huck and enhanced by David Simpson. The module is fully configurable within Magnolia and no additional coding is necessary. Google Analytics is a powerful solution for analyzing website traffic and how users interact on your site. It is possible to monitor virtually all site activity, even on individual elements of a page.

The module is fully integrated with the Standard Templating Kit.

Download

The Google Analytics module is bundled with Magnolia and typically already installed. You can download it from our Nexus repository

Installing

Google Analytics is a Community Edition module. It is typically not installed.

Click for installation steps...

Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.

To install a module:

Stop the application server.
Copy the module JAR files into the WEB-INF/lib directory. The location of this directory depends on the application server.
- Tomcat: /webapps/magnoliaAuthor/WEB-INF/lib
- JBoss: /server/default/deploy/magnoliaAuthor/WEB-INF/lib
Restart the server.
Go to the AdminCentral URL.
Start the Web update process.
Click Start up Magnolia.

Repeat the steps for each author and public instance.

Uninstalling

Click for uninstallation steps...

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.

However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.

To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one.

We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.

Setting your tracking code

The Google Analytics module configuration requires a unique GA tracking code (UA-XXXXXXXX-X) that you will find in your GA account.

The module is configured at Configuration > /modules/google-analytics/config/sites/default.

Community Edition users are limited to a single site and should configure GA in the /sites/site node.

To start GA tracking, set the enabled property to true and enter your GA tracking code for the trackerID property.

Node name	Value
modules
google-analytics
config
sites
site
default
tracking
enabled	true
trackerID	UA-1234567-1

The configurable properties within the /default/tracking node are dealt with below in Tracking options. If no specific tracking configurations are added, the /default configuration essentially tracks pageviews, but GA does provide a lot of detail about user behavior and sources.

JavaScripts

Two JavaScripts are relevant to GA tracking: jquery-gatracker and init-gatracker. You can view these in STK > Resources /templating-kit/js/ga.

These scripts, in conjunction with the GoogleAnalyticsModule class and GoogleAnalyticsJSResourceModel model class define and implement the GA requirements. They insert the required parameters into the HTML code on each page:

jquery-gatracker is the original gaTracker jQuery plug-in script that has been customized for Magnolia. It is a non-processed, normal JavaScript.
The business logic provided by GoogleAnalyticsJSResourceModel translates the Magnolia configuration to a JavaBean using the Node2Bean mechanism.
init-gatracker requests the tracking configuration from the model and injects the values into the GA configuration. init-gatracker is a processed JavaScript.

Tracking options

GA is flexible and can be customized to track almost anything. For more information see Google Analytics Developer Guides. The Magnolia module allows for most options and additional customizations can be made.

There are four tracking configuration options at Configuration > /modules/google-analytics/config/sites/default/tracking that allow for the configuration of detailed tracking of events, links, domain and misc. The TrackingOptions class supports the configuration options and properties.

Node name	Value
modules
google-analytics
config
sites
site
default
tracking
events
links
domain
misc

Link tracking

The Google Analytics module uses virtual pageviews to track download, external, mailto and anchor links. GA does not track links by default unless they are specifically tagged. The _trackPageview() method is used to tag the links and the results appear in GA as virtual pages. The only drawback of this method is that the clicks are added to the total pageview count.

Links are configured in Configuration > /modules/google-analytics/config/sites/default/tracking/links. There are four subnodes: /download, /external. /mail and /anchor and each has two configurable properties:

Property	Description	Default value
`enabled`	To enable and disable the tag	`false`
`linkPrefixToAdd`	The prefix added to the link that appears in the GA reports	null

Node name	Value
default
tracking
events
links
download
extensions
enabled	true
linkPrefixToAdd	/downloads/
external
enabled	true
linkPrefixToAdd	/external/
mail
enabled	true
linkPrefixToAdd	/mailtos/
anchor
enabled	true
linkPrefixToAdd	/anchors/
enabled	true
domain

The links/download/extensions node allows for the definition of the file extensions to be included. Each extension is registered in an individual node and there are two configurable properties:

Property	Description	Default value
`enabled`	To enable and disable the extension	`true`
`name`	The node name	null

Node name	Value
default
tracking
events
links
download
extensions
pdf
enabled	true
name	pdf
doc
docx
xls
xlsx
ppt
pptx
odt
....

To view the links statistics in the GA interface go to Behavior > Site Content and filter on the terms “downloads”, “external”,”mailtos” or “anchors”.

Here are a few results for anchor links in the demoauthor GA account.

Event Tracking

Event Tracking allows you to record user interaction with website elements. This is accomplished by attaching the method call to the particular UI element. The accessed page element is identified in GA with a path that starts with /events-tracking. With events tracking you can, for example, determine the number of times a form was submitted, the effectiveness of a particular component type or the popularity of a page within a grouped teaser.

The EventsTrackingPattern class defines a search pattern for tracking events as a click or submit. Within these categories of events, any number of patterns can be configured. Each pattern corresponds to a CSS element defined in styles.css that is available in STK > Resources > /templating-kit/themes/pop/css. Tracking is triggered when GA encounters the CSS element in the HTML code of the page.

Node name	Value
default
tracking
events
click
patterns
tw-paging-stage
tw-paging-main
tw-switcher-main-prev
cssSelector	#main .tw-switcher .prev span
enabled	true
evalStatsLink	true
statsLink	/events-tracking/click/teaser-wrapper/tw-switcher/main/prev
tw-switcher-main-next
tab-box
enabled	true
submit
patterns
form-contact
form-login
form-registration
enabled	true

The nodes configured under /tracking/events/click/patterns/ and /submit/patterns allow for tracking activity on specific page elements. Each configuration node has four properties.

Property	Description	Default value
`cssSelector`	Defines the CSS element that triggers event tracking	null
`enabled`	Defines whether the pattern should be used	`false`
`evalStatsLink`	Defines whether the `statsLink` property should be evaluated by the JavaScript	`false`
`statsLink`	Defines the link submitted to GA when tracking is triggered. It does not form part of the rendered HTML. In GA, it represents a tracked event in the statistics	null

The pattern set in the statsLink property is the page path you see in the GA reports. For example, the /tw-paging-stage node in the screenshot above is configured to record statistics for the stkStagePaging component on the home pages of the demo sites. The pattern defines a readable path and its constituent parts translate as follows:

Part	Translation
`/events-tracking`	An event is tracked
`/click`	It is a a click event
`/teaser-wrapper`	It is a teaser element
`/main`	The element resides in the `main` area of the page
`/prev`	The specific action clicked

In GA go to Behavior > Site Content and filter on "events-tracking" to see the results. Pageview calculations are unaffected by user activity tracked using this method.

Here are a few events results for the demoauthor GA account.

Cross-domain tracking

By default, GA tracks content for a single domain, such as www.example.com. Cross-domain tracking facilitates tracking of subdomains and across separate domains within a single GA account. It is useful in many instances, for example to track users referred to a third-party payment gateway or a subdomain hosting a blog. This function should not be confused with Mapping to multiple domains above.

jquery-gatracker.js, available in STK > Resources in /templating-kit/js/ga, uses three methods for cross-domain tracking:

Method	Purpose
`_setDomainName()`	Sets the top-level domain name for cookies
`_setAllowLinker()`	Sets the linker functionality flag as part of enabling cross-domain user tracking
`_linkByPost()`	Passes the cookies from the referring form to another site in a string appended to the action value of the form (HTTP POST)

Cross-domain tracking is configured in Configuration > /modules/google-analytics/sites/default/tracking/domain. There are three configurable properties:

Property	Description	Default value
`crossDomainSelector`	URL of third-party site	null
`domainName`	Top-level domain to track	null
`enabled`	To enable and disable cross-domain tracking	`false`

Node name	Value
default
tracking
events
links
domain
crossDomainSelector	payment-gateway.com
domainName	example.com
enabled	true
misc

Miscellaneous tracking options

Additional miscellaneous tracking options can be configured in Configuration > /modules/google-analytics/config/site/default/tracking/misc. There are two general properties:

Property	Description	Default value
`pageViewsEnabled`	To enable and disable pageview tracking for `misc` tracking options	`true`
`sampleRate`	Enables client-side visitor sampling. This feature is designed for high-traffic sites to reduce the load on all systems. Only a percentage of page views are tracked	null

Node name	Value
default
tracking
events
links
domain
misc
organicSearch
pageViewsEnabled	true
sampleRate	50

Organic search

The organic search feature allows you to add to the list of organic search engines recognized by GA. This is helpful, for example to add local search engines that GA does not recognize. You can find a list of engines that GA tracks by default at Search Engine Configuration.

Organic search engines are configured at Configuration > /modules/google-analytics/config/site/default/tracking/misc/organicSearch/patterns. The OrganicSearchTrackingPattern class defines the search pattern for tracking organic search engines.

For each search engine there are three configurable properties.

Property	Description	Default value
`enabled`	Defines whether the pattern should be used	`false`
`queryParameterName`	Defines the query parameter name of the search engine URL, for examples 'q' in URL 'http://www.alexa.com/search?q=magnolia+cms	null
`searchEngineDomain`	Defines the URL of the search engine to track	null

Node name	Value
default
tracking
events
links
domain
misc
organicSearch
patterns
alexa
enabled	true
queryParameterName	q
searchEngineDomain	alexa.com
enabled	true

Mapping to multiple domains

The Multisite module available to Enterprise Edition users supports multiple domains. These are configured in STK > Site Definitions. Here are the site definitions for the demo sites.

Node name	Value
default
demo-project
domains
demo-project
name	www.demo-project.com
i18n
mappings
extends	../default
demo-features
domains
demo-features
i18n
mappings
extends	../default
demo-project-de
domains
demo-project-de
i18n
extends	../demo-project

Multiple domains can be tracked in a single GA account or different accounts can be used for each. The extends feature allows you to use the /default GA configuration for multiple sites and domains by defining only the properties that are different in the new configuration.

The configuration below includes all the demo sites in a single GA account, by extending the /default and /demo-project configurations. Note that node names of the sites configured in STK > Site Definitions must match the node names in the GA configuration identically.

Node name	Value
modules
google-analytics
config
sites
site
default
tracking
enabled	true
trackerID	UA-1234567-1
demo-project
extends	../default
demo-features
extends	../default
demo-project-de
extends	../demo-project

Here are the results in the demoauthor GA account showing the inclusion of both the /demo-project and /demo-features sites in a single account.

The configuration below applies all the configurations of /default to the /demo-features site, but it is tracked in a different GA account.

Node name	Value
modules
google-analytics
config
sites
site
default
tracking
enabled	true
trackerID	UA-1234567-1
demo-features
extends	../default
trackerID	UA-1011121-1

Page tree