Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

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...

(warning) 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:

  1. Stop the application server.
  2. 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
  3. Restart the server.
  4. Go to the AdminCentral URL.
  5. Start the Web update process.
  6. 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.

(warning) 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 nameValue

 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:

  1. jquery-gatracker is the original gaTracker jQuery plug-in script that has been customized for Magnolia. It is a non-processed, normal JavaScript.
  2. The business logic provided by GoogleAnalyticsJSResourceModel translates the Magnolia configuration to a JavaBean using the Node2Bean mechanism.
  3. 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 nameValue

 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 nameValue

 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 nameValue

 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 nameValue

 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

/mainThe element resides in the main area of the page
/prevThe 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 nameValue

 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 nameValue

 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 nameValue

 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 nameValue

 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 nameValue

 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 nameValue

 modules

 

 google-analytics

 

 config

 

 sites

 

 site

 

 default

 

 tracking

 

 enabled

true

 trackerID

UA-1234567-1

 demo-features

 

 extends

../default

 trackerID

UA-1011121-1