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

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

Maven is the easiest way to install the module. Add the following to your bundle:

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

A pre-built bundle is also available for download. See Installing a module for help.

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

Do not use Safari to create a service account. The public/private key pair generation in step 6 does not work correctly in Safari.

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

Node nameValue

 modules


 google-analytics-visualization


 config


 credentialConfig


 applicationName

GAV

 serviceAccountJsonPath

<path_to_json_with_service_account_credentials>

Properties:

serviceAccountJsonPath 

required if you want to load credentials from a JSON file.

Path to JSON file with service account credentials generated in Creating a service account if the JSON key type was selected.

applicationName

required

Name of the application requesting data from Google Analytics. For example: GAV.

Loading credentials from a P12 file

Node nameValue

 modules


 google-analytics-visualization


 config


 credentialConfig


 applicationName

GAV

 servicePrivateKeyPath

<path_to_p12_file_with_service_account_credentials>

Properties:

applicationName

required

Name of your application for requesting data from Google Analytics. For example: GAV.

servicePrivateKeyPath

required if you want to load credentials from a P12 file.

Path to P12 file with service account credentials generated in Creating a service account if the P12 key type was selected.

Storing credentials in the Magnolia configuration

Node nameValue

 modules


 google-analytics-visualization


  config


 credentialConfig

 applicationName

GAV

 servicePrivateKey

<private_key>

 serviceEmail

<service_account_email>

Properties:

applicationName

required

Name of the application requesting data from Google Analytics. For example: GAV.

servicePrivateKey

required if you want to store credentials in the Magnolia configuration.

See the screenshot of the open JSON file below.

serviceEmail

required if you want to store credentials in the Magnolia configuration.

See the screenshot of the open JSON file below.

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

Node nameValue

 modules


  google-analytics-visualization


 clients


 travel-demo


 parser


 metrics


 ga-exitRate


 reverse

true

 enabled

true

 endDate

today

 endDateCompare

31daysAgo

 filters

ga:pagePath=~^/travel*

 metrics

ga:pageviews,ga:exitRate

 profileId

ga:24199737

 startDate

30daysAgo

 startDateCompare

60daysAgo

Properties:

enabled

required

true enables the client. false disables the client.

serviceClass

optional, default is info.magnolia.ga.visualization.client.GoogleAnalyticsClient

Client service class which extends info.magnolia.ga.visualization.client.GoogleAnalyticsClient.

cron

optional, default is 0 0/5 * 1/1 * ? *

Cron expression which defines the frequency of data refreshes fetched by this client.

command

optional, default is clientExecutor

Command which is used to instantiate and trigger the client.

catalog

optional, default is gav

Name of the catalog where the command resides.

fetchDataImmediately

optional, default is true

If set to true, the data for the client will immediately be fetched from Google Analytics when the client is added or reconfigured.

delay

optional, default is 5s

Defines the delay (in seconds) after which fetching data from Google Analytics should start, if fetchDataImmediately is set to true.

profileId

required

Unique profile (view) ID for retrieving Analytics data. The profileId is written as ga:View ID. See how to find out your Analytics View ID.

See more on Analytics Core Reporting API documentation.

startDate

required

Start date for fetching Analytics data. Requests must specify a start date formatted as YYYY-MM-DD, or a relative date such as today, yesterday, or 7daysAgo.

See more on Analytics Core Reporting API documentation.

endDate

required

End date for fetching Analytics data. Requests must specify an end date formatted as YYYY-MM-DD, or a relative date such as today, yesterday, or 7daysAgo.

See more on Analytics Core Reporting API documentation.

startDateCompare

optional

Start date of previous period for comparing the result. Requests must specify a start date formatted as YYYY-MM-DD, or a relative date such as today, yesterday, or 7daysAgo.

endDateCompare

optional

End date of previous period for comparing the result. Requests must specify an end date formatted as YYYY-MM-DD, or a relative date such as t oday, yesterday, or 7daysAgo.

metrics

required

A comma-separated list of Analytics metrics such as 'ga:sessions,ga:pageviews'.

See more on Analytics Core Reporting API documentation. Explore all the metrics in the Dimensions & Metrics Explorer.

filters

required

A comma-separated list of dimension or metric filters to be applied to Analytics data.

See more on Analytics Core Reporting API documentation.

maxResults

optional

The maximum number of entries to be included in the response. If it is not set then the Google Analytics default value (1000) is used.

parser

optional

Setting for the parser of Google Analytics data.

parserClass

optional, default is info.magnolia.ga.visualization.client.parse.GoogleAnalyticsDataParser

Parser class which has to extend info.magnolia.ga.visualization.client.parse.GoogleAnalyticsDataParser

metrics

required

<metric_name>

optional

Name of the metric. Can be formatted as ga-<metric_name> (for example, "ga-pageviews") or simply as <metric_name> (for example, "pageviews").

reverse

optional, default is false 

When you compare data to the previous period, it is sometimes positive that the value has decreased.

When this property is set to false then it means that it is positive that the value has increased compared to the previous period.

When it is set to true then it means that it is positive that the value has decreased compared to the previous period.

roundTo

optional, default is 2

This property specifies number of decimal points for rounding.

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

Node nameValue

 ga-pageviews


 clients


 sportstation

sportstation

 travel-demo

travel-demo

 class

info.magnolia.ga.visualization.column.GoogleAnalyticsPageStatisticsColumnDefinition

 metric

ga:pageviews

Properties:

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

class

required

info.magnolia.ga.visualization.column.GoogleAnalyticsPageStatisticsColumnDefinition

metric

required

Name of the metric for which data is shown in the column.

units

optional

Units of data shown in the column.

clients

required

<name_of_the_client>

required

Name of the client from which the column reads data.

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

Node nameValue

 ga-pageviews


 clients


 sportstation

sportstation

 travel-demo

travel-demo

 class

info.magnolia.ga.visualization.column.GoogleAnalyticsPageStatisticsColumnDefinition

 metric

ga:pageviews

 text

{0} page views this month

Properties:

class

required

info.magnolia.ga .visualization.column.GoogleAnalyticsPageStatisticsColumnDefinition

metric

required

Name of metric for which data is shown in the column.

text

required

Text displayed in the status bar. {0} in the text is substituted with the value. i18n can be used in the text field.
For example, "{0} page views this month".

clients

required

<name_of_the_client>

required

Name of the client from which column reads data.

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.

Node nameValue

 topCountriesBySession


 chartType

PIE

 dimensions

ga:country

 label

gav.chartViews.topCountriesBySession.label

 metrics

ga:sessions

 viewId

ga:24199737

Properties:

chartType

required, default is LINE

The chart type. Possible options are: LINE, COLUMN, BAR, TABLE, GEO and PIE.

dimensions

required, default is ga:date

A list of comma-separated dimensions for your Analytics data. The dimensions parameter breaks down metrics by common criteria.

See more in the Analytics Core Reporting API documentation. Explore all the metrics in the Dimensions & Metrics Explorer.

label

required

Label for the chart view.

metrics

required, default is ga:pageviews

A comma-separated list of Analytics metrics such as "ga:sessions,ga:pageviews".

See more in the Analytics Core Reporting API documentation. Explore all the metrics in the Dimensions & Metrics Explorer.

viewId

required

Unique view ID for retrieving Analytics data. The viewId is written as ga:<View ID>. See how to find out your Analytics View ID.

See more on Analytics Core Reporting API documentation.

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.

Google Analytics does not filter data retroactively.

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.

If you do not want to merge URLs in your default view then you should have a separate view that strips query parameters.

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.

If you do not want to merge URLs in your default view then you should have a separate view that strips query parameters.

  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:

Node nameValue

 modules


 google-analytics-visualization


  config


 pathResolver

 class

info.magnolia.ga.visualization.pathresolver.GoogleAnalyticsSiteAwarePathResolver


Properties:

class

optional, default is info.magnolia.ga.visualization.pathresolver.GoogleAnalyticsSimplePathResolver

info.magnolia.ga.visualization.pathresolver.GoogleAnalyticsSiteAwarePathResolver

prefixToAdd

optional, default is EMPTY

a string value to be used by info.magnolia.ga.visualization.pathresolver.GoogleAnalyticsSimplePathResolver

prefixToRemove

optional, default is EMPTY

a string value to be used by info.magnolia.ga.visualization.pathresolver.GoogleAnalyticsSimplePathResolver