Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
HTML Wrap
width250
alignright
classmenu
Page properties

Download

Multiple modules

Connector Pack

Analytics Connector Pack

License

Include Page
_MLA
_MLA

Issues

ANALYTICS

Maven site

ANALYTICS

Latest version

Artifact resource link
groupIdinfo.magnolia.analytics
artifactIdmagnolia-analytics
label$version
renderTypedisplay_only
resourceTypePOM

HTML Wrap
clearboth
width250
alignright
classmenu

Related topics:

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.

Table of Contents
maxLevel4

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:

Multiexcerpt
MultiExcerptNameInstall

Artifact maven dependencies snippet
groupIdinfo.magnolia.analytics
artifactIdmagnolia-analytics

Artifact maven dependencies snippet
groupIdinfo.magnolia.analytics
artifactIdmagnolia-analytics-ui

Artifact maven dependencies snippet
groupIdinfo.magnolia.analytics
artifactIdmagnolia-analytics-amcharts

Artifact maven dependencies snippet
groupIdinfo.magnolia.analytics
artifactIdmagnolia-analytics-google-connector

Artifact maven dependencies snippet
groupIdinfo.magnolia.analytics
artifactIdmagnolia-analytics-matomo-connector

Artifact maven dependencies snippet
groupIdinfo.magnolia.analytics
artifactIdmagnolia-analytics-adobe-connector

Artifact maven dependencies snippet
groupIdinfo.magnolia.analytics
artifactIdmagnolia-analytics-amcharts-samples

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

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

Anchor
#anc-data-supplier
#anc-data-supplier
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 

Javadoc resource link
classNameinfo.magnolia.analytics.datasource.AbstractExternalDataSupplier
renderTypeasynchronous
, 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. 

Code Block
languageyml
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

Javadoc resource link
classNameinfo.magnolia.analytics.adobe.datasource.AdobeDataSupplier
renderTypeasynchronous

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. 

Tip

GoogleDataSupplierWithDateFormatter data supplier extends the GoogleDataSupplier with date formatting.

Code Block
languageyml
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

Javadoc resource link
classNameinfo.magnolia.analytics.google.datasource.GoogleDataSupplier
renderTypeasynchronous

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:

Expand
titleHow 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. 

Code Block
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

Javadoc resource link
classNameinfo.magnolia.analytics.matomo.datasource.MatomoDataSupplier
renderTypeasynchronous

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 

Javadoc resource link
classNameinfo.magnolia.analytics.datasource.FileBasedDataSupplier
renderTypeasynchronous
 to fetch data from a JSON file. 

For example:

Code Block
languageyml
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:

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

Class:  

Javadoc resource link
classNameinfo.magnolia.analytics.datasource.PeriscopeDataSupplier
renderTypeasynchronous

Content tags data supplier example

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

Code Block
languageyml
dataSuppliers: 
  contentTagsDataSupplier:
    class: info.magnolia.analytics.datasource.ContentTagsDataSupplier

Class:  

Javadoc resource link
classNameinfo.magnolia.analytics.datasource.ContentTagsDataSupplier
renderTypeasynchronous

Anchor
anc-chartdefinition
anc-chartdefinition
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 (

Javadoc resource link
classNameinfo.magnolia.analytics.amcharts.data.AmChartDefinition
renderTypeasynchronous
) but you can also write your own simple charts (
Javadoc resource link
classNameinfo.magnolia.analytics.common.SimpleChartDefinition
renderTypeasynchronous
).

Anchor
anc-predefinedcharttypes
anc-predefinedcharttypes
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
Tip

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.  

Hide block

add link to abtesting docs

Code Block
languageyml
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


Anchor
anc-adobe-chartdef-example
anc-adobe-chartdef-example
Adobe Analytics triangle column chart definition example

Code Block
languageyml
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

Anchor
anc-ga-chartdef-example
anc-ga-chartdef-example
Google Analytics XY chart definition example

Code Block
languageyml
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

Code Block
languageyml
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: 

      Code Block
      languageyml
      title/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:

      Code Block
      languageyml
      titleanalytics-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:

      Code Block
        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
Expand
titleClick to see an example of JSON config translated to YAML
Pie chart JSON configPie chart YAML config
Code Block
languagejava
<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>
Code Block
languageyml
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: 

Javadoc resource link
classNameinfo.magnolia.analytics.amcharts.data.AmChartDefinition
renderTypeasynchronous

Simple chart definition class: 

Javadoc resource link
classNameinfo.magnolia.analytics.common.SimpleChartDefinition
renderTypeasynchronous

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:

Code Block
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:

Javadoc resource link
classNameinfo.magnolia.analytics.amcharts.data.configuration.AmChartType
renderTypeasynchronous

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.

Tip
titleTips

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: 

Code Block
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:

Code Block
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:

Code Block
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:

Code Block
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

Anchor
#anc-dimensions
#anc-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. 

Note

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:

Code Block
languageyml
dimension: 
 rows: 2 
 columns: 6

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

Code Block
languageyml
.... 
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

Excerpt

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. 

Info

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

Example

Code Block
languageyml
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: 

Javadoc resource link
classNameinfo.magnolia.ui.form.field.definition.DateFieldDefinition
renderTypeasynchronous

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 

Javadoc resource link
rangeHigherVersion6.2
classNameinfo.magnolia.ui.workbench.contenttool.ContentToolDefinition
renderTypeasynchronous
of 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. 

Image Added

Code Block
languageyml
titlepages-app.subApps.browser.workbench.yaml
collapsetrue
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:

Code Block
languageyml
titleanalytics-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).

Code Block
languageyml
cachingDefinition:
  enabled: true
  invalidateInSeconds: 300

Set the property to false  to disable caching. 

Info

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

Release history

Multiexcerpt
MultiExcerptNameanalyticsconnectorpackreleases

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