Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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:
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.
- Open the Google Developers Console.
- Click Continue.
This creates a new project called "My Project" in the Google Developers Console and enables the Analytics API. - The console notifies you that the project has been created and that Analytics API has been enabled. Click Go to credentials.
- 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.
- skip
- skip
- skip
- skip
- 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.
- skip
- skip
- skip
- skip
- skip
- 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.
- Sign in to your Analytics account.
- Select the Admin tab and navigate to the required Account/Property/View.
- In the View column, click User Management.
- Under Add permissions for, enter the email address of the service account.
- 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.
- 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.
- In your Analytics account, select the Admin tab and select the required View .
- 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 name | Value |
|---|---|
GAV | |
<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. |
| required Name of the application requesting data from Google Analytics. For example: GAV. |
Loading credentials from a P12 file
| Node name | Value |
|---|---|
GAV | |
<path_to_p12_file_with_service_account_credentials> |
Properties:
| required Name of your application for requesting data from Google Analytics. For example: GAV. |
| 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 name | Value |
|---|---|
GAV | |
<private_key> | |
<service_account_email> |
Properties:
| required Name of the application requesting data from Google Analytics. For example: GAV. |
| required if you want to store credentials in the Magnolia configuration. See the screenshot of the open JSON file below. |
| 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 name | Value |
|---|---|
true | |
true | |
today | |
31daysAgo | |
ga:pagePath=~^/travel* | |
ga:pageviews,ga:exitRate | |
ga:24199737 | |
30daysAgo | |
60daysAgo |
Properties:
| required
|
| optional, default is Client service class which extends |
| optional, default is Cron expression which defines the frequency of data refreshes fetched by this client. |
| optional, default is Command which is used to instantiate and trigger the client. |
catalog | optional, default is Name of the catalog where the command resides. |
| optional, default is If set to |
| optional, default is Defines the delay (in seconds) after which fetching data from Google Analytics should start, if |
| required Unique profile (view) ID for retrieving Analytics data. The See more on Analytics Core Reporting API documentation. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| required A comma-separated list of dimension or metric filters to be applied to Analytics data. See more on Analytics Core Reporting API documentation. |
| 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. |
| optional Setting for the parser of Google Analytics data. |
| optional, default is Parser class which has to extend |
| required |
| optional Name of the metric. Can be formatted as ga-<metric_name> (for example, "ga-pageviews") or simply as <metric_name> (for example, "pageviews"). |
| optional, default is When you compare data to the previous period, it is sometimes positive that the value has decreased. When this property is set to When it is set to |
| optional, default is 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 name | Value |
|---|---|
sportstation | |
travel-demo | |
info.magnolia.ga.visualization.column.GoogleAnalyticsPageStatisticsColumnDefinition | |
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.
| required
|
| required Name of the metric for which data is shown in the column. |
| optional Units of data shown in the column. |
| required |
| 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 name | Value |
|---|---|
sportstation | |
travel-demo | |
info.magnolia.ga.visualization.column.GoogleAnalyticsPageStatisticsColumnDefinition | |
ga:pageviews | |
{0} page views this month |
Properties:
| required
|
| required Name of metric for which data is shown in the column. |
| required Text displayed in the status bar. {0} in the text is substituted with the value. i18n can be used in the text field. |
| required |
| 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 name | Value |
|---|---|
PIE | |
ga:country | |
gav.chartViews.topCountriesBySession.label | |
ga:sessions | |
ga:24199737 |
Properties:
| required, default is The chart type. Possible options are: |
dimensions
| required, default is 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. |
| required Label for the chart view. |
| required, default is 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. |
| required Unique view ID for retrieving Analytics data. The 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.
- Sign in to your Analytics account.
- Select the Admin tab and navigate to View/View Settings.
- 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.
- Sign in to your Analytics account.
- Select the Admin tab and navigate to Account/All Filters for account level filters or Account/View/Filters for view level filters.
- Click Add Filter.
- Under Filter Type, select Custom and Search and Replace.
- In the Filter Field dropdown, select Request URI.
- Add the following regular expression in the Search String field:
\?.* - 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 name | Value |
|---|---|
|
Properties:
| optional, default is
|
| optional, default is EMPTY a |
| optional, default is EMPTY a |
Overview
Content Tools