Google Analytics Visualization module

Magnolia integrates with the Google Analytics Core Reporting API and the Google Analytics Embed API. The Google Analytics Visualization module enables you to view Google Analytics data within Magnolia. The module can be configured to display the data you are interested in but does not insert Google Analytics tags into pages. The Marketing Tags module can be used for inserting tags.

Installing

<dependency>
  <groupId>info.magnolia.ga.visualization</groupId>
  <artifactId>magnolia-module-google-analytics-visualization</artifactId>
</dependency>

Enabling the Analytics API

To enable the Analytics API you register your application with the Analytics API in the Google Developers Console. This involves creating a new project and adding service account credentials to it.

Creating a service account

Follow the steps below to create a project in the Google Developers Console, enable the Analytics API and generate the service account.

1. Open the Google Developers Console.
2. Click Continue.
   
   This creates a new project called "My Project" in the Google Developers Console and enables the Analytics API. 
3. The console notifies you that the project has been created and that Analytics API has been enabled. Click Go to credentials. 
   
4. Fill in the form:

• Which API are you using?: Analytics API
• Where will you be calling the API from?: Web server
• What data will you be accessing?: Application data
• Are you using Google App Engine or Google Compute Engine?: No

Then click What credentials do I need? to define the credentials needed for your project.

1. skip
2. skip
3. skip
4. skip
5. Add credentials to your project:

• • Name: MagnoliaGAV (or your choice of name)
  • Service account ID: note the value shown here, you will need it later. 
  • Key type: JSON (recommended)

Then click Continue to create the service account. 

1. skip
2. skip
3. skip
4. skip
5. skip
6. The following dialog is displayed and the account's public/private key pair is saved to your computer. Click Close .
   

Adding the service account to your Google Analytics account

The service account you created has a service account ID in email address format. Use this ID to add a user to the Google Analytics Account/Property/View you want to access via the API.

1. Sign in to your Analytics account.
2. Select the Admin tab and navigate to the required Account/Property/View.
3. In the View column, click User Management.
4. Under Add permissions for, enter the email address of the service account.
5. Assign Read & Analyze permissions to the user. Additional permissions are not required because the Magnolia Google Analytics Visualization module does not modify any data in Google Analytics.
6. Click Add.

Finding out your View ID

You need the View ID when configuring your client to fetch data from Google Analytics and when configuring the chart view.

1. In your Analytics account, select the Admin tab and select the required View .
2. In the View column click View Settings. 

Configuring credentials in the Google Analytics Visualization module

You must configure the Google Analytics Visualization module to fetch data from the Google Analytics view. To do so, you load the credentials from the file saved to your computer when you created the service account. You then store the credentials in the module configuration.

Loading credentials from a JSON file

Properties:

Loading credentials from a P12 file

Properties:

Storing credentials in the Magnolia configuration

Properties:

Integrating with Pages app

Once integrated in the Pages app, Magnolia adds two new columns by default: Page views and Exit rate info.magnolia.ga.visualization.column.GoogleAnalyticsPageStatisticsColumnFormatter. You can configure the Pages app to display more data from Google Analytics.

The status bar extension info.magnolia.ga.visualization.extension.GoogleAnalyticsPageStatisticsExtension also displays some Google Analytics data by default and can be customized.

Fetching data from Google Analytics - Clients

To avoid exceeding API limits and quotas, limit your use of the Analytics Core Reporting API by refreshing data from Google Analytics in configured time intervals. The client uses the Analytics Core Reporting API to fetch the data and the Magnolia Scheduler module to schedule the data refresh frequency.

Client configuration

Properties:

Configuring the column display in the Pages app

The columns in the Pages app are configured under Configuration > /modules/pages/apps/pages/subApps/browser/workbench/contentViews/list/columns.

Configuring the Google Analytics Visualization column

Properties:

info.magnolia.ga.visualization.column.GoogleAnalyticsPageStatisticsColumnDefinition extends AbstractColumnDefinition. Only the properties specific to GoogleAnalyticsPageStatisticsColumnDefinition are described here.  See the basic set of properties in the Column definition documentation.

Extending the status bar in the detail subapp

Extensions for the status bar in the Pages app are configured under Configuration >  /modules/pages/apps/pages/subApps/detail/statusBar/extensions.

Configuring the Google Analytics Visualization extension

{0} page views this month

Properties:

Google Analytics Visualization app

The Google Analytics Visualization app uses Google Analytics Embed API to display more detailed statistics about pages in the form of charts. Every request to update a chart triggers a request to the Analytics API and provides real-time data from Google Analytics.

You can open the app in Tools > Page statistics or by clicking View page stats in the Pages app. 

The app is configured under Configuration > /modules/google-analytics-visualization/apps/gav.

Chart view

You can use the chart view to define what type of data you want to display and how it should be displayed in the Google Analytics Visualization app.

Configuring Chart views

Chart views are configured under Configuration > /modules/google-analytics-visualization/config/chartViews.

ga:24199737

Properties:

Query string in Google Analytics URL

Google Analytics splits pages into multiple rows with different parameters. The Google Analytics Visualization module can only display (in columns, status bar extensions and in charts) data for URLs without parameters.

In the example above, the statistics for the Configuration/modules/google-analytics-visualization/config/credentialConfig/travel/contact.html page are split into 8 rows. You cannot get an accurate overview of the page statistics because they are not combined. The URLs must be merged into one row.

Merging URLs with different parameters

There are different ways of merging URLs. You can:

• Use a canonical URL.
• Exclude specific query parameters.
• Use filters.

Using a canonical URL

Add a <link> element with the attribute rel="canonical" to the <head> section of the pages. In our example with the /travel/contact.html page, add <link rel="canonical" href="/travel/contact.html"/>.

Learn more about using canonical URLs.

Excluding specific query parameters

In Google Analytics you can exclude specific query parameters. However, this method cannot be used over several views; the parameters must be copied and pasted to every view. You must also know the query parameter names. 

1. Sign in to your Analytics account.
2. Select the Admin tab and navigate to View/View Settings.
3. Add any query parameters that you do not want to see as a comma-separated list in the Exclude URL Query Parameters box.

Using filters

You can define filters instead of excluding specific query parameters. The advantage of using filters is that they can be defined on an account level and reused in multiple views. Whole query strings can be removed by using regular expressions, so you do not need to know the parameter names.

1. Sign in to your Analytics account.
2. Select the Admin tab and navigate to Account/All Filters for account level filters or Account/View/Filters for view level filters.
3. Click Add Filter.
4. Under Filter Type, select Custom and Search and Replace.
5. In the Filter Field dropdown, select Request URI.
6. Add the following regular expression in the Search String field: \?.*
7. Click Save.

Path resolving

There are two implementations for path resolving of the info.magnolia.ga.visualization.pathresolver.GoogleAnalyticsPathResolver interface. The default value info.magnolia.ga.visualization.pathresolver.GoogleAnalyticsSimplePathResolver resolves the path from node path by adding or removing a prefix defined via prefixToRemove and prefixToAdd properties. If not defined, the node path is used.

The value can optionally be set to info.magnolia.ga.visualization.pathresolver.GoogleAnalyticsSiteAwarePathResolver if the path is to be resolved from site definition or URI2RepositoryMapping mechanism:

Properties: