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

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.

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...
  1. Sign in to your Google Analytics account
  2. Click Admin.
  3. In the VIEW column, click View Settings.
  4. 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

Abstract external data supplier

If you need to integrate your own external analytics tool, implement the class AbstractExternalDataSupplier.

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. 

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

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.

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.

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

cachingDefinition:
  enabled: true

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 versionMagnolia CMS version
1.06.1