Analytics module

The Analytics Connector Pack modules provide a framework and connectors to inject your analytics data into the Magnolia UI enabling authors and marketeers to make data-driven decisions.

The overall process to configure a dashboard is:

Connect to a data supplier, such as Google Analytics, Matomo, a file or another third party analytics data provider.
Decide what data you want to display in your charts and provide the parameters for a REST call to configure the JSON results retrieved.
Choose a chart type from one of the many predefined samples (or configure your own) and decide which data is displayed and how.
Optionally, customize the dashboard dimensions, theme and css or filters.

The pack delivers out-of-the-box connectors, a default Analytics app and extensive predefined samples to help you build your own charts and dashboards.

Module structure

artifactID	Description
`magnolia-analytics-parent`	Parent reactor.
`magnolia-analytics-amcharts`	Provides a default implementation to connect to amCharts, which provides JavaScript-based interactive charts and maps programming libraries and tools.
`magnolia-analytics-google-connector`	Provides a default implementation to connect to Google Analytics.
`magnolia-analytics-matomo-connector`	Provides a default implementation to connect to Matomo.
`magnolia-analytics`	Provides the foundation and the API for the Analytics add-on.
`magnolia-analytics-ui`	Provides the Analytics app, the `demo` dashboard and predefined chart types that you can reuse.
`magnolia-analytics-amcharts-samples`	Provides sample dashboards.

Installing

Maven is the easiest way to install the modules. Add the following dependencies to your webapp. All the other necessary dependencies will be brought in automatically:

<dependency>
  <groupId>info.magnolia.analytics</groupId>
  <artifactId>magnolia-analytics-parent</artifactId>
  <version>1.0</version>
</dependency>

<dependency>
  <groupId>info.magnolia.analytics</groupId>
  <artifactId>magnolia-analytics-ui</artifactId>
  <version>1.0</version>
</dependency>

<dependency>
  <groupId>info.magnolia.analytics</groupId>
  <artifactId>magnolia-analytics-amcharts</artifactId>
  <version>1.0</version>
</dependency>

<dependency>
  <groupId>info.magnolia.analytics</groupId>
  <artifactId>magnolia-analytics-google-connector</artifactId>
  <version>1.0</version>
</dependency>

<dependency>
  <groupId>info.magnolia.analytics</groupId>
  <artifactId>magnolia-analytics-matomo-connector</artifactId>
  <version>1.0</version>
</dependency>

<dependency>
  <groupId>info.magnolia.analytics</groupId>
  <artifactId>magnolia-analytics</artifactId>
  <version>1.0</version>
</dependency>

<dependency>
  <groupId>info.magnolia.analytics</groupId>
  <artifactId>magnolia-analytics-amcharts-samples</artifactId>
  <version>1.0</version>
</dependency>

Pre-built JARs are also available for download. See Installing a module for help.

Configuration

The magnolia-analytics-ui submodule provides a sample Analytics app configuration, the demo dashboard you see in the app and several preconfigured chart types.

The magnolia-analytics-amcharts-samples provides sample dashboards.

You can create or edit the configuration of the app and the dashboard as part of a light module (YAML).

magnolia.resources.dir/ 
└── analytics-ui/ 
	├── apps/ 
		└── analytics.yaml 
	├── dashboards 
		└── demo.yaml 
	└── i18n/ 
		└── magnolia-analytics-ui-messages_en.properties

Defining the data supplier

Define the data supplier(s) for the charts displayed in the dashboard. You later refer to the supplier in the chart definition dataSupplier property.

Abstract external data supplier

If you need to integrate your own external analytics tool, implement the class AbstractExternalDataSupplier. The Google Analytics data supplier example below extends this generic class with Google Analytics account credentials.

Google Analytics data supplier example

You must have an appropriate account and credentials to connect to GA.

dataSuppliers:
  googleSupplier:
    class: info.magnolia.analytics.google.datasource.GoogleDataSupplier
    credentials:
      applicationName: Magnolia Analytics
      serviceAccountJsonPath: /google-analytics/analytics/google/private_key.json
    parameters:
      viewId: 191451330
      startDate: 7DaysAgo
      endDate: today
      dimensionName: ga:date
      metricExpression: ga:sessions
      metricAlias: sessions

Properties

`dataSuppliers`
`googleSupplier`	required Arbitrary data supplier name.
`class`	GoogleDataSupplier
`credentials`
`applicationName`	required Name of the application requesting the data from the Google Analytics reporting service. For example: Magnolia Analytics
`serviceAccountJsonPath`	required Path to JSON file with service account credentials for your Google Analytics Service Account. For example: `/analytics-google-connector/analytics/google/private_key.json`
`parameters`	required The parameters used in the REST call to configure the JSON results retrieved. These parameters vary depending on the data supplier used. Each parameter is a key-value pair. For Google Analytics, at least the `viewId` parameter is required: How to find your viewId value... Sign in to your Google Analytics account Click Admin. In the VIEW column, click View Settings. The View ID is under Basic Settings. See the Google Analytics API documentation (https://developers.google.com/analytics/devguides/reporting/core/dimsmets) to find valid parameters for Google Analytics.

Matomo data supplier example

You must have an appropriate account and credentials to connect to Matomo.

dataSuppliers: 
  matomoSupplier:
    class: info.magnolia.analytics.matomo.datasource.MatomoDataSupplier
    credentials:
      parameters:
        serverUrl: https://demo.matomo.org
        tokenAuth: anonymous
    parameters:
      method: UserCountry.getCity
      module: API
      idSite: 62
      date: yesterday
      period: day
      format: json
      filter_limit: 5

Properties

`dataSuppliers`
`matomoSupplier`	required Arbitrary data supplier name.
`class`	required MatomoDataSupplier
`credentials`
`parameters`
`serverUrl`	required The URL to your Matomo server.
`tokenAuth`	required The authentication token from Matomo.
`parameters`	required The parameters used in the REST call to configure the JSON results retrieved. These parameters vary depending on the data supplier used. Each parameter is a key-value pair. For Matomo, at least the `format: json` key-value is required to retrieve JSON format data. See the Matomo API documentation (https://developer.matomo.org/api-reference/reporting-api#API) to find valid parameters for Matomo. For example, the Matomo example above retrieves JSON format data using the Matomo UserCountry API.

File-based data supplier example

Depending on your requirements, you can configure a file-based data supplier using the class FileBasedDataSupplier to fetch data from a JSON file.

For example:

dataSuppliers: 
  treeMapDataSupplier:
    class: info.magnolia.analytics.datasource.FileBasedDataSupplier
    filePath: /info/magnolia/analytics/samples/json/treemap/treemap-data.json

Periscope data supplier example

In our demo dashboard, we show an example of search data taken from the Magnolia find bar data using a custom data supplier with a limit on the number of results returned:

dataSuppliers: 
  periscopeDataSupplier:
    class: info.magnolia.analytics.datasource.PeriscopeDataSupplier
    limit: 8 # limit the number of results from the supplier

Class: PeriscopeDataSupplier

Content tags data supplier example

Again in our demo dashboard, we show an example of Magnolia content tags data using a custom data supplier:

dataSuppliers: 
  contentTagsDataSupplier:
    class: info.magnolia.analytics.datasource.ContentTagsDataSupplier

Class: ContentTagsDataSupplier

Configuring chart definitions

You configure what content and how it is displayed in your dashboard in the chart definition YAML file under chartDefinitions.

Predefined chart types

The magnolia-analytics-amcharts-ui submodule provides several predefined amCharts charts under /analytics-ui/chartTypes:

simple-line.yaml
trend-lines.yaml
simple-bar.yaml
floating-bar.yaml
3d-bar.yaml
simple-column.yaml
triangle-column.yaml
3d-column.yaml
pie.yaml
3d-pie.yaml
donut-with-radial-gradient.yaml
3d-donut.yaml
candlestick.yaml
xy-chart-fills-axis.yaml
ohlc.yaml

You can see details of the amCharts chart types in their documentation.

You can reuse the predefined chart types when defining your chart definition using YAML includes and decorating the series provided.

Google Analytics XY chart definition example

chartDefinitions:
  line2GA:
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    label: Session by date from GA
    chartType: !include:/analytics-ui/chartTypes/column-and-bar/simple-column.yaml
      # This is example how to decorate chart type to decorate data field mapping
      series:
        - name: series
          dataFields:
            - name: categoryX
              jsonPath: $.reports[*].data.rows[*].dimensions[*] # Decorate jsonPath for categoryX to map data from GA
            - name: valueY
              jsonPath: $.reports[*].data.rows[*].metrics[*].values[*] # Decorate jsonPath for categoryX to map data from GA
    dataSupplier: googleSupplier

Matomo pie chart definition example

chartDefinitions:
  column2Matomo:
    label: User country from Matomo
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    chartType: !include:/analytics-ui/chartTypes/pie-and-donut-group/pie.yaml
      responsive:
        enabled: true
    dataSupplier: matomoSupplier

In this example, the predefined pie.yaml chart does not show a decorated series because Matomo can reuse the default series directly.

Custom AmChartType configuration

If you do not want to use a predefined chart type supplied by Magnolia, you can configure your own. There are two ways of doing so:

Select the amCharts type you require and provide the native JSON-based config by amCharts.
For example:

/analytics-amcharts-samples/dashboards/treemap-sankey-gauge-chord.yaml

chartDefinitions:
  treemap:
    label: treemap
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    dataSupplier: treeMapDataSupplier
    nativeJsonConfig: /info/magnolia/analytics/samples/json/treemap/treemap-config.json
    type: TreeMap

Write your own chart type YAML configuration.
For example:

analytics-ui/chartTypes/pie.yaml

class: info.magnolia.analytics.amcharts.data.configuration.AmChartType
type: PieChart
series:
  - name: series
    type: PieSeries
    dataFields:
      - name: category
        value: label
        jsonPath: $.[*].label
      - name: value
        value: nb_visits
        jsonPath: $.[*].nb_visits
legend:
  position: bottom

And include it in your chart definition:

  chart-2:
    dataSupplier: mostActiveUsersDataSupplier
    label: Most active users by publication
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    chartType: !include:/analytics-ui/chartTypes/pie-and-donut-group/pie.yaml

Click to see an example of JSON config translated to YAML

Pie chart JSON config

Pie chart YAML config

<script src="//www.amcharts.com/lib/4/core.js"></script>
<script src="//www.amcharts.com/lib/4/charts.js"></script>

<div id="chartdiv" style="width: 900px; height 800px;"></div>

<script>
// Create chart instance in one go
var chart = am4core.createFromConfig({
  // Create pie series
  "series": [{
    "type": "PieSeries",
    "dataFields": {
      "value": "litres",
      "category": "country"
    }
  }],

  // Add data
  "data": [{
    "country": "Lithuania",
    "litres": 501.9
  }, {
    "country": "Czech Republic",
    "litres": 301.9
  }, {
    "country": "Ireland",
    "litres": 201.1
  }, {
    "country": "Germany",
    "litres": 165.8
  }, {
    "country": "Australia",
    "litres": 139.9
  }, {
    "country": "Austria",
    "litres": 128.3
  }, {
    "country": "UK",
    "litres": 99
  }, {
    "country": "Belgium",
    "litres": 60
  }, {
    "country": "The Netherlands",
    "litres": 50
  }],

  // And, for a good measure, let's add a legend
  "legend": {}

}, "chartdiv", am4charts.PieChart);
</script>

class: info.magnolia.analytics.amcharts.data.configuration.AmChartType
type: PieChart
series:
  - name: series
    type: PieSeries
    dataFields:
      - name: value
        value: litres
        jsonPath: $.[*].litres
      - name: category
        value: country
        jsonPath: $.[*].country

Properties

`chartDefinitions`	required
`<your-chart-name>`	required A name for the given chart displayed in the dashboard. For example `line2GA`.
`dataSupplier`	required The source of the data displayed in the charts. For example, `googleSupplier` or `matomoSupplier` .
`label`	required A text label displayed as the title of the chart in the dashboard. For example "Session by date from GA".
`class`	required Chart definition class: AmChartDefinition
`chartType`	required if you are using a predefined chart type Use a Magnolia-specific directive YAML include to reuse the predefined chart types delivered by the `analytics-ui` module. For example: chartType: !include:/analytics-ui/chartTypes/pie-and-donut-group/pie.yaml You then override the chart type series to adjust the data to your requirements.
`class`	required Chart type class:AmChartType
`series`	required Each chart type can support only relevant amCharts series. When using a predefined chart type, the correct series is included. You must override the series to adjust the data to your requirements. You must modify the entire `series`. Not just parts of it. Series have two main purposes: Setting appearance and behavior of a series of chart/map items; Binding individual items in series to source data. Many amCharts series settings are available.
`dataFields`	required Defines the connection between data item and actual properties in raw data. The `name` and `value` properties are required for the amCharts data fields. If you need a more advanced selection of data, you can also use the `jsonPath` property to filter the data.
`name`	required The name of the data field.
`value`	required The value of the data field.
`jsonPath`	optional The JSONPath expression filters the data you retrieve about your site from the data supplier. The syntax you use depends on your data and what you want to display in your chart. Tips If you use a Google Analytics data supplier, you must have a valid Google Analytics access token to be able run API requests. Get one here. Copy your JSON output to https://jsonformatter.curiousconcept.com/ to format it if required. Copy your JSON output again to https://jsonpath.com/ to test out your JSONPath syntax for the `jsonPath` property. Example: jsonPath: $.reports[].data.rows[].dimensions[*]
`xAxes`	required for most chart types Defines the X axis data and appearance. For example, in the predefined simple-bar.yaml chart type: xAxes: - name: xaxe type: VALUE_AXIS See the amCharts documentation about Axes.
`yAxes`	required for most chart types Defines the Y axis data and appearance. For example, in the predefined simple-bar.yaml chart type: yAxes: - name: yaxe type: CATEGORY_AXIS renderer: minGridDistance: 10 grid: location: 0 dataFields: category: city_name See the amCharts documentation about Axes.
`nativeJsonConfig`	required If you are not using a predefined chart type Path to the native JSON-based config custom configuration you created. For example: chartDefinitions: treemap: label: treemap class: info.magnolia.analytics.amcharts.data.AmChartDefinition dataSupplier: treeMapDataSupplier nativeJsonConfig: /info/magnolia/analytics/samples/json/treemap/treemap-config.json type: TreeMap See Custom AmChartType configuration.
`type`	required If you are not using a predefined chart type The chart type for the native JSON-based config custom configuration you created. For example: `TreeMap`
`position`	required if you override the default dashboard dimensions Defines where the chart is positioned in the dashboard. Values can be: `row`, `column`, `rowSpan`, `colSpan`. You can override the default by configuring specific dashboard dimensions. If you do so, you must specify compatible positions for your charts. (By default, the dashboard has two columns. Charts are positioned automatically on a first come, first served basis in the columns from left to right on as many rows as are necessary for the number of charts you add.) See Customizing the dashboard dimensions.

Customizing the dashboard dimensions

The dashboard dimensions define how many rows and columns are in your dashboard.

By default, the dashboard has two columns. Charts are positioned automatically on a first come, first served basis in the columns from left to right on as many rows as are necessary for the number of charts you add.

You can override the default by configuring specific dashboard dimensions.

We recommend you only override the default if you need to customize positions for a specific purpose. Note that the dashboard dimensions and the chart positions are related to each other and if they are not correctly configured together, they may cause errors. For example, if the dashboard dimension is configured to 2x2 but a chart is configured to position 3 an error will occur.

This example shows the configuration for a dashboard with 2 rows and 6 columns:

dimension: 
 rows: 2 
 columns: 6

You can also define a specific position for each chart type you define if you choose. For example:

.... 
position: 
 row: 1 
 column: 3 
 rowSpan: 1 
 colSpan: 3

Note that the first row and column are counted as 0. The configuration above places the chart in the green squares:

0 0	1	2	3	4	5
1

Defining dashboard filter fields

Developers can define filters to drill down into the data displayed in the charts that are configured. When set, each filter is applied to all the charts in the dashboard simultaneously. For example, if you set a filter to display a given time range, all the charts display data for that time range.You can use basic Magnolia field types to define filters, such as date, rich text, and so on.

Complex fields such as multiValue, composite, switchable and collapsibleComposite are not supported.

Example

filterFields:
  - name: idSite
    class: info.magnolia.ui.form.field.definition.TextFieldDefinition
    placeholder: site id
    label: Site ID
  - name: filter_limit
    class: info.magnolia.ui.form.field.definition.TextFieldDefinition
    label: Filter limit
  - name: date
    class: info.magnolia.ui.form.field.definition.DateFieldDefinition
    label: Date
  - name: startDate
    class: info.magnolia.ui.form.field.definition.DateFieldDefinition
    label: Start date
  - name: endDate
    class: info.magnolia.ui.form.field.definition.DateFieldDefinition
    label: End date

Properties

`filterFields`	required
`name`	required The filter names are used to append the REST call against the supplier. Therefore the value here must have a counterpart in the given data suppliers. You can also use filters to override parameters. Matomo values: https://developer.matomo.org/api-reference/reporting-api#API Google values: https://developers.google.com/analytics/devguides/reporting/core/dimsmets
`class`	required Fully qualified classname for the field. See List of fields. For example: DateFieldDefinition
`label`	required A text label displayed as the title of the filter in the dashboard. For example "Start date".
`placeholder`	optional Text to be displayed in the filter field when you do not want the filter to appear empty.
`options`	optional Options to be applied to the filter contents. The sub-properties depend on the field type being used.

Changing the theme and CSS

You can change the CSS and theme of the dashboard charts to suit your visual requirements.

To do so, update the amcharts.css and amcharts_theme.js files in /info/magnolia/analytics/amcharts/vaadin.

Enabling responsiveness

Magnolia supports amCharts responsiveness feature.
To make your charts responsive, enable the feature by adding the responsive property to the chart definition and setting it to enabled: true as shown in this example:

analytics-amcharts-samples/dashboards/ga-and-matomo-samples.yaml

chartDefinitions:
  column2Matomo:
    label: User country from Matomo
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    chartType: !include:/analytics-ui/chartTypes/pie-and-donut-group/pie.yaml
      responsive:
        enabled: true
    dataSupplier: demoMatomoSupplier

If you enable responsiveness, when a chart’s pixelWidth is <= 500px, Magnolia automatically hides the chart legend.

You can change the responsive rules in /info/magnolia/analytics/amcharts/vaadin/amcharts_connector.js.

Configuring the cache

You can configure the cache in the JCR or the File System (YAML) under: /analytics/config.yaml

By default, the cache is enabled and content pulled from your external solution is updated every 300 seconds (5 minutes).

cachingDefinition:
  enabled: true
  invalidateInSeconds: 300

Set the property to false to disable caching.

When you click the refresh button on the dashboard, the cache is invalidated.

Release history

Analytics module 1.0

Released on July 9, 2019.

Initial release of the Analytics Connector Pack modules, which provide a framework and connectors to inject your analytics data into the Magnolia UI enabling authors and marketeers to make data-driven decisions. See Analytics Connector Pack for an overview of the functionality provided.

Analytics Connector Pack compatibility

Module version	Magnolia CMS version
1.0	6.1

Page tree

Analytics module

Module structure

Installing

Configuration

Defining the data supplier

Abstract external data supplier

Google Analytics data supplier example

Properties

Matomo data supplier example

Properties

File-based data supplier example

Periscope data supplier example

Content tags data supplier example

Configuring chart definitions

Predefined chart types

Google Analytics XY chart definition example

Matomo pie chart definition example

Custom AmChartType configuration

Properties

Customizing the dashboard dimensions

Defining dashboard filter fields

Properties

Changing the theme and CSS

Enabling responsiveness

Configuring the cache

Release history

Analytics module 1.0

Analytics Connector Pack compatibility