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 Adobe Analytics, 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-adobe-connector

Provides a default implementation to connect to Adobe Analytics.

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</artifactId>
  <version>1.1</version>
</dependency>

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

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

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

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

<dependency>
  <groupId>info.magnolia.analytics</groupId>
  <artifactId>magnolia-analytics-adobe-connector</artifactId>
  <version>1.1</version>
</dependency>

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

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 data supplier

The abstract data supplier enables you to filter chart data using filter fields in the Magnolia UI, for example, the filters used to select a start and end date for your data. 

This supplier is suitable for internal data that need filters for display purposes.

Abstract external data supplier

If you want to integrate your own external analytics tool, implement the class AbstractExternalDataSupplier, which provides credential parameters. This class extends the AbstractDataSupplier so data filtering in the UI is also supported.

The Google Analytics data supplier example below extends this generic class with Google Analytics account credentials.

Adobe Analytics data supplier example

You must have an appropriate account and credentials to connect to Adobe Analytics. 

dataSuppliers:
  adobeDataSupplier:
    class: info.magnolia.analytics.adobe.datasource.AdobeDataSupplier
    credentials:
      parameters:
        serviceUrl: https://analytics.adobe.io/api/exchan213/reports
        clientId: <your-client-id>
        clientSecret: <client_secret_or_path_to_password_manager>
        companyId: exchan213
        orgId: 6AE67B675E217A090A495EE1@AdobeOrg
        technicalAccountId: 1501153F5E44CB8F0A495E4C@techacct.adobe.com
        imsHost: https://ims-na1.adobelogin.com
        imsExchange: https://ims-na1.adobelogin.com/ims/exchange/jwt
        # generate private key file : openssl req -nodes -text -x509 -newkey rsa:2048 -keyout secret.pem -out certificate.pem -days 356
        # Upload the certificate.pem in Adobe IO Console-> Your Integration-> Public keys
        # convert private key to DER format : openssl pkcs8 -topk8 -inform PEM -outform DER -in secret.pem -nocrypt > secret.key
        # private key file should be in DER encoded format now, and config the path like below
        privateKeyPath: /adobe-analytics/analytics/adobe/secret.key
        metascopes: ent_analytics_bulk_ingest_sdk
        tokenExpTime: 3600
    parameters:
      rsid: emagmgnl
      gFilterType: dateRange
      startDate: '2020-01-01'
      endDate: '2020-01-15'
      metricId: metrics/revenue
      dimension: variables/daterangeday
Accessing Adobe Client Credentials

Many of the values for the credential parameters can be found as follows:

  1. Log into the Adobe I/O console.
  2. Create a new Integration with Adobe Analytics.
    The Client Credentials are listed in the Overview tab of the new Integration.

For example, here you can see the Client ID:

Properties

dataSuppliers

required

adobeDataSupplier

required

Arbitrary data supplier name.

class

required

AdobeDataSupplier

credentials

required

parameters

required

serviceUrl

required

The URL for your Adobe Analytics service, which includes your companyId issued by Adobe when you register.

For example: https://analytics.adobe.io/api/exchan213/reports  where exchan213 is the companyId.

clientId

required

Your client ID. 

To find your client ID, see Accessing Adobe Client Credentials.

clientSecret

required

Client secret for your Adobe Analytics account or the path to the Magnolia Passwords app.

To find your client secret, see Accessing Adobe Client Credentials.

companyId

required

Your Company ID issued by Adobe when you register.

You can also use the Adobe swagger API to retrieve it (login required): https://adobedocs.github.io/analytics-2.0-apis/

orgId

required

Your Organization ID.
To find your Organization ID, see Accessing Adobe Client Credentials.

technicalAccountId

required

Your Technical Account ID.
To find your Technical Account ID, see Accessing Adobe Client Credentials.

imsHost

required

An Adobe IMS server URL, currently it is: https://ims-na1.adobelogin.com

imsExchange

required

An Adobe IMS server URL, currently it is: https://ims-na1.adobelogin.com/ims/exchange/jwt

privateKeyPath

required

Path to the private key file, usually a relative path from resources folder.

To use the private key file:

  1. Generate the private key file: openssl req -nodes -text -x509 -newkey rsa:2048 -keyout secret.pem -out certificate.pem -days 356
  2. Upload the certificate.pem in Adobe IO Console>Your Integration>Public keys.
  3. Convert the private key to DER format: openssl pkcs8 -topk8 -inform PEM -outform DER -in secret.pem -nocrypt > secret.key
  4. When the private key file is in DER-encoded format, configure the path like the example: /adobe-analytics/analytics/adobe/secret.key

metascopes

required

For Adobe Analytics, it is ent_analytics_bulk_ingest_sdk

For more information, see the Adobe JSON Web Token (JWT) metascopes documentation.

tokenExpTime

required , default is 3600 (60 minutes)

Time in seconds after which the JSON Web Token expires. When the token expires, the system automatically generates a new one so that the services are not blocked.

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.

All the parameters shown in the example are required:

Google Analytics data supplier example

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

GoogleDataSupplierWithDateFormatter data supplier extends the GoogleDataSupplier with date formatting.

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

required

googleSupplier

required

Arbitrary data supplier name.

class

GoogleDataSupplier

credentials

required

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.

filteringSubSetExpression

optional

Use to configure segment filtering.

filtersExpression

optional

Expression to filter a segment.

For example: ga:pagePath=~%s*

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

required

matomoSupplier

required

Arbitrary data supplier name.

class

required

MatomoDataSupplier

credentials

required

parameters

required

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.

filteringSubSetExpression

optional

Use to configure segment filtering.

segment

optional

Expression to filter a segment.

For example: pageUrl=@%s

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.

Magnolia provides integration with AmCharts (AmChartDefinition) but you can also write your own simple charts (SimpleChartDefinition).

Predefined amCharts chart types

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

  • simple-line.yaml
  • trend-lines.yaml
  • line-different-colors-ups-downs.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. 

Simple chart definition

The magnolia-analytics submodule provides a simple chart definition class for charts that do not rely on amCharts. 

This example shows the configuration for a simple chart that displays icon plus the number of unique visitors to a page used to display results in the upcoming Magnolia AB Testing app.  

add link to abtesting docs

chartDefinitions:
  chart-1:
    dataSupplier: testResultsDataSupplier
    label: Unique visitors
    class: info.magnolia.analytics.common.SimpleChartDefinition
    icon: icon-user-public
    propertyOrJsonPath: $.get_rate[0].nb_uniq_visitors

dataSuppliers:
  testResultsDataSupplier:
    class: info.magnolia.abtesting.app.datasupplier.TestResultsDataSupplier


Adobe Analytics triangle column chart definition example

chartDefinitions:
  chart-1:
    label: Adobe
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    chartType: !include:/analytics-ui/chartTypes/column-and-bar/triangle-column.yaml
      # Decorate series for mapping json data
      series:
        - name: series
          dataFields:
            - name: categoryX
              jsonPath: $.rows[*].value
            - name: valueY
              jsonPath: $.rows[*].data[0]
    dataSupplier: adobeDataSupplier

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 configPie 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

amChart definition class: AmChartDefinition

Simple chart definition class: SimpleChartDefinition

icon

required (only available for simple chart definitions )

A Magnolia font icon such as icon-user-public.

propertyOrJsonPath

required ( only available for simple chart definitions )

Defines the values displayed in the simple chart. Because all data suppliers must return JSON, you can specify a property in that JSON or use a JSONPath expression to point to the value you want to display.

For example, to get the number of unique visitors from the JSON file:

$.get_rate[0].nb_uniq_visitors

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.

Adobe values: https://adobedocs.github.io/analytics-2.0-apis/

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.  

Displaying analytics in an extension panel

In addition to viewing analytics charts in the Analytics app, you can display them next to the content they apply to in IUX (Integrated User eXperience) slots. 

IUX slots are extension panels in the browser subapp. The panel allows you to configure a list of extension views in the workbench and replaces ContentToolDefinitionof Magnolia 5 UI.

The first slot, introduced in Magnolia 6.2, is a wide horizontal slot at the top of content apps such as the Pages app.

Use decoration to configure the:

  • Extension panel in the Pages app (see extensionViews for configuration and properties).  
  • Charts to be displayed.
  • Data suppliers providing the analytics data.

For example, the configuration in this decoration file (with the relevant credentials added) results in charts displayed in an IUX slot at the top of the Pages app for the Travel demo pages. 

pages-app.subApps.browser.workbench.yaml
extensionViews:
  - name: analytics
    icon: icon-analytics-app
    view:
      name: analytics
      $type: analyticsView
      chartDefinitions:
        - name: pageViews
          label: pages-app.extensionViews.analytics.pageViews.label
          class: info.magnolia.analytics.amcharts.data.AmChartDefinition
          dataSupplier: gaPageViewsSupplier
          chartType: !include:/analytics-ui/chartTypes/line-and-area/line-different-colors-ups-downs.yaml
            series:
              - name: series
                dataFields:
                  - name: categoryX
                    jsonPath: $.reports[*].data.rows[*].dimensions[*]
                  - name: valueY
                    jsonPath: $.reports[*].data.rows[*].metrics[*].values[*]
        - name: sessions
          label: pages-app.extensionViews.analytics.sessions.label
          class: info.magnolia.analytics.amcharts.data.AmChartDefinition
          dataSupplier: gaSessionsSupplier
          chartType: !include:/analytics-ui/chartTypes/line-and-area/line-different-colors-ups-downs.yaml
            series:
              - name: series
                dataFields:
                  - name: categoryX
                    jsonPath: $.reports[*].data.rows[*].dimensions[*]
                  - name: valueY
                    jsonPath: $.reports[*].data.rows[*].metrics[*].values[*]
        - name: bounceRate
          label: pages-app.extensionViews.analytics.bounceRate.label
          class: info.magnolia.analytics.amcharts.data.AmChartDefinition
          dataSupplier: gaBounceRateSupplier
          chartType: !include:/analytics-ui/chartTypes/line-and-area/line-different-colors-ups-downs.yaml
            series:
              - name: series
                dataFields:
                  - name: categoryX
                    jsonPath: $.reports[*].data.rows[*].dimensions[*]
                  - name: valueY
                    jsonPath: $.reports[*].data.rows[*].metrics[*].values[*]
        - name: newUsers
          label: pages-app.extensionViews.analytics.newUsers.label
          class: info.magnolia.analytics.amcharts.data.AmChartDefinition
          dataSupplier: gaNewUsers
          chartType: !include:/analytics-ui/chartTypes/line-and-area/line-different-colors-ups-downs.yaml
            series:
              - name: series
                dataFields:
                  - name: categoryX
                    jsonPath: $.reports[*].data.rows[*].dimensions[*]
                  - name: valueY
                    jsonPath: $.reports[*].data.rows[*].metrics[*].values[*]
        - name: returningUsers
          label: pages-app.extensionViews.analytics.returningUsers.label
          class: info.magnolia.analytics.amcharts.data.AmChartDefinition
          dataSupplier: gaReturningUsers
          chartType: !include:/analytics-ui/chartTypes/line-and-area/line-different-colors-ups-downs.yaml
            series:
              - name: series
                dataFields:
                  - name: categoryX
                    jsonPath: $.reports[*].data.rows[*].dimensions[*]
                  - name: valueY
                    jsonPath: $.reports[*].data.rows[*].metrics[*].values[*]
        - name: cityViews
          label: cityViews
          class: info.magnolia.analytics.amcharts.data.AmChartDefinition
          dataSupplier: demoMatomoSupplier
          chartType: !include:/analytics-ui/chartTypes/line-and-area/simple-line.yaml
            series:
              - name: series
                type: LineSeries
                dataFields:
                  - name: categoryX
                    value: city_name
                    jsonPath: $.[*].city_name
                  - name: valueY
                    value: lat
                    jsonPath: $.[*].lat

      dataSuppliers:
        gaPageViewsSupplier:
          class: info.magnolia.analytics.google.datasource.GoogleDataSupplierWithDateFormatter
          fromDateFormat: yyyyMMdd
          toDateFormat: MMM-dd
          credentials: &googleCredentials
            applicationName: Magnolia Analytics
            serviceAccountJsonPath: /analytics-view-example/credential/private_key.json
          parameters:
            viewId: 24199737
            startDate: 7DaysAgo
            endDate: today
            dimensionName: ga:date
            metricExpression: ga:pageviews
          filteringSubSetExpression:
            filtersExpression: ga:pagePath=~%s*
        demoMatomoSupplier:
          class: info.magnolia.analytics.matomo.datasource.MatomoDataSupplier
          credentials:
            parameters:
              serverUrl: https://demo.matomo.org
              tokenAuth: anonymous
          parameters:
            method: UserCountry.getCity
            module: API
            idSite: 3
            date: yesterday
            period: day
            format: json
          filteringSubSetExpression:
            segment: pageUrl=@%s
        gaSessionsSupplier:
          class: info.magnolia.analytics.google.datasource.GoogleDataSupplierWithDateFormatter
          fromDateFormat: yyyyMMdd
          toDateFormat: dd-MMM-yyyy
          credentials: *googleCredentials
          parameters:
            viewId: 24199737
            startDate: 7DaysAgo
            endDate: today
            dimensionName: ga:date
            metricExpression: ga:sessions
          filteringSubSetExpression:
            filtersExpression: ga:pagePath=~%s*
        gaBounceRateSupplier:
          class: info.magnolia.analytics.google.datasource.GoogleDataSupplierWithDateFormatter
          fromDateFormat: yyyyMMdd
          toDateFormat: dd-MMM-yyyy
          credentials: *googleCredentials
          parameters:
            viewId: 24199737
            startDate: 7DaysAgo
            endDate: today
            dimensionName: ga:date
            metricExpression: ga:bounceRate
          filteringSubSetExpression:
            filtersExpression: ga:pagePath=~%s*
        gaNewUsers:
          class: info.magnolia.analytics.google.datasource.GoogleDataSupplierWithDateFormatter
          fromDateFormat: yyyyMMdd
          toDateFormat: dd-MMM-yyyy
          credentials: *googleCredentials
          parameters:
            viewId: 24199737
            startDate: 7DaysAgo
            endDate: today
            dimensionName: ga:date
            metricExpression: ga:newUsers
          filteringSubSetExpression:
            filtersExpression: ga:pagePath=~%s*
        gaReturningUsers:
          class: info.magnolia.analytics.google.datasource.GoogleDataSupplierWithDateFormatter
          fromDateFormat: yyyyMMdd
          toDateFormat: dd-MMM-yyyy
          credentials: *googleCredentials
          parameters:
            viewId: 24199737
            startDate: 7DaysAgo
            endDate: today
            dimensionName: ga:date
            metricExpression: ga:users
          filteringSubSetExpression:
            filtersExpression: ga:pagePath=~%s*

      filterFields:
        - name: startDate
          $type: dateField
          type: java.util.Date
          time: false
          placeholder: Start
          defaultValue: todayMinus7Days
        - name: endDate
          $type: dateField
          type: java.util.Date
          time: false
          placeholder: End
          defaultValue: today

      multisite:
        - path: /travel
          dataSupplier:
            gaPageViewsSupplier:
              credentials:
                serviceAccountJsonPath: /analytics-view-example/credential/private_key.json
              parameters:
                viewId: 110545462
            gaSessionsSupplier:
              credentials:
                serviceAccountJsonPath: /analytics-view-example/credential/private_key.json
              parameters:
                viewId: 110545462
            gaBounceRateSupplier:
              credentials:
                serviceAccountJsonPath: /analytics-view-example/credential/private_key.json
              parameters:
                viewId: 110545462
            gaNewUsers:
              credentials:
                serviceAccountJsonPath: /analytics-view-example/credential/private_key.json
              parameters:
                viewId: 110545462
            gaReturningUsers:
              credentials:
                serviceAccountJsonPath: /analytics-view-example/credential/private_key.json
              parameters:
                viewId: 110545462

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.1

Released on April 6, 2020.

This release delivers a new connector for Adobe Analytics.

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.1

6.2
1.0

6.1

A note about connector compatibilty

The third-party versions listed below are the versions Magnolia has developed and tested against. If you don’t see a particular version listed, it simply means that we do not routinely test on it.

If you are using another version of the third-party tool and run into compatibility issues, please contact our Support team

Module versionAdobe Analytics API

1.0

Tested against 2.0 

Module versionGoogle Analytics API

1.0

Tested against v4-rev1-1.21.0

Module version

Matomo

1.0

Tested against Matomo demo  site 3.13.5-b2