Web Analytics API Documentation

The Cadenza Web Analytics API allows you to track user actions by listening to analytics events dispatched by Cadenza. The API is exposed on the global window.Disy.webAnalyticsApi object, which is an EventTarget. You can use it to integrate with web analytics platform such as Matomo, Google Analytics, or similar tools.

Events

The API dispatches a single event type: action. Each action event is a CustomEvent whose detail property contains information about the tracked user action.

Event Detail Properties

Every event detail includes the following base properties:

Property Type Description

category

string

High-level category of the event (e.g., 'export').

action

string

Specific action or type within the category (e.g., 'csv', 'excel', 'curated_report').

Export Events

For export events, the category is always 'export'. The following additional properties are available:

Property Type Description

action

ExportActionType

The export format. One of: 'csv', 'excel', 'geopackage', 'image', 'kml', 'gpx', 'shapefile', 'curated_report', 'adhoc_report'.

entityType

ExportEntityType

The type of entity being exported. One of: 'workbook', 'worksheet', 'view', 'view_individual_values', 'layer'.

entityPrintName

string

The display name of the entity being exported.

workbookPrintName

string

The display name of the workbook.

worksheetPrintName

string (Optional)

The display name of the worksheet. Not available when entityType is a 'workbook'.

Curated Report Export Events

When the action is 'curated_report', the entityType is always 'workbook' and an additional property is available:

Property Type Description

reportTemplatePrintName

string

The display name of the report template used for the curated report export.

Usage

To consume the API, register an event listener on the window.Disy.webAnalyticsApi object in your theming template:

window.Disy.webAnalyticsApi.addEventListener('action', (event) => {
  const { category, action, entityType, entityPrintName, reportTemplatePrintName } = event.detail;
  // Process the event with your analytics platform
});

Example: Matomo Integration

The following example shows how to forward Cadenza analytics events to Matomo using the Matomo JavaScript Tracking API:

window.Disy.webAnalyticsApi.addEventListener('action', (event) => {
  const { category, action, entityType, entityPrintName, workbookPrintName, reportTemplatePrintName } = event.detail;
  _paq.push(['trackEvent', category, action, `${entityType}: [${entityPrintName}] | workbook: [${workbookPrintName}]${reportTemplatePrintName != null ? ` | report: [${reportTemplatePrintName}]` : ''}`]);
});

In this example, the Matomo trackEvent call is constructed as follows:

  • Event Category: The category value (e.g., 'export').

  • Event Action: The action value (e.g., 'csv', 'curated_report').

  • Event Name: A concatenation of entityType, entityPrintName, and optionally reportTemplatePrintName.

Instead of concatenating extra details into the event name field, consider using Matomo’s Custom Dimensions feature to track entityType, entityPrintName, and reportTemplatePrintName as separate dimensions for more flexible analysis.