matomo-org/looker-studio-connector

The officially supported Matomo Connector for Looker Studio enables you to explore your Matomo data in Looker Studio at no cost. You can connect to both Matomo Cloud instances or On-Premise instances using just a Matomo Auth Token.

looker-studio-connector's Issues

support goal specific metrics in Actions reports

The Actions plugin calculates goal specific metrics for its reports, but they are not exposed via report metadata because overall goal metrics aren't computed (I think).

This can be fixed in core or can be hardcoded in the connector.

Allow accessing multiple Matomo instances at a time

Currently the connector will only allow connecting to a single Matomo instance at a time. This is due to the way Looker Studio stores credentials: as user properties. So the once the user sets the credentials the only way to set a new Matomo instance is to revoke the access and configure the connector again.

To allow accessing multiple Matomo instances, we'd need to create a separate service that allows storing credentials for multiple Matomo instances. Users would connect to this service in Looker Studio instead of Matomo instances directly, and the connector would detect this and display the list of instances available as a choice during configuration.

Something to consider:

• many users may not want to trust a 3rd party service with their Matomo tokens (even if InnoCraft hosts it).

get tests to run in github actions

The tests currently run locally using your personal credentials, but we'd like to have it running in Github Actions.

This will require:

• creating test google account with the appropriate Google Cloud Project & oauth credentials
• make the credentials available in Github Actions
• configure a workflow to run npm run test:appscript with those credentials

(some intermediate steps may be missing)

support Matomo for WordPress

Matomo for WordPress does not use Matomo's API but routes everything through WordPress' REST API. So to be able to use the looker studio connector for MWP, we would need to conditionally support a slightly different API.

Dynamically truncate requests for Matomo report data

Looker Studio requests for data are bounded by App Script's limitations. Specifically, they can only run for a certain amount of minutes before being aborted.

If Matomo takes too long to process and return this data, the request will simply fail. Right now the only workaround is to set the "Default Row Limit" setting to limit the amount of data that is queried. But this option requires guess work from the user and is likely an annoying user experience.

Instead, we should explore dynamically truncating report data (using filter_truncate) when we know we're about to run out of time. This will at least show users the data they're expecting.

update github actions credentials when test account created

As title.

dynamically adjust number of rows fetched at a time

Different reports will result in different row sizes, and after #4, different requests will result in different row sizes. For some requests, it will be more efficient to load a large number of rows at a time, while other reports would not support it.

It would be useful if the connector was able to dynamically adjust the rows fetched at a time if too large, and cache the number that works each request.

Log slow requests so we can actively find performance issues

If a request to Matomo takes longer than a certain amount, we should log it, and regularly check to see what's taking too long.

This might reveal performance issues not just with the connector, but also Matomo.

To be determined: the threshold beyond which a request for data is considered slow.

retry requests if a DNS error is encountered

As title.

Confusing UX for Adding Server URL and Auth Token in Matomo

Description

There is a potential issue with the user experience (UX) when users are asked to submit a username to connect with Looker Studio but need to submit their Matomo server URL instead.

Current Behaviour

• The process to add a server URL and an authentication token is potentially confusing.
• The connector description currently links to a top-level topic in the Knowledge Base (KB).

Expected Behaviour

• The process to add a server URL and an authentication token should be clear and intuitive.
• Users should ideally be able to complete these steps without requiring additional guides or extensive help.

Suggested Solution

To improve the UX and make the process more user-friendly, it is proposed that:

• The placeholder text for the user input field is updated from "Username" to "Matomo URL" if possible.
• The connector description text could be updated from "Connect to Matomo Cloud instances or self-hosted instances using just a Matomo Auth Token." to "Connect to Matomo Cloud instances or self-hosted instances using just your Matomo URL and a Matomo Auth Token."
• The connector description should link directly to a dedicated connection FAQ specifically tailored to guide users through the process of adding a server URL and an authentication token. The FAQ should provide step-by-step instructions, troubleshooting tips, and clarify common questions or issues specific to the connection process.

Benefits

• Increased Clarity: Stating that a URL is required inline would help users know what details are required by the form.
• Reduced Confusion: Clarifying in the description may enable users to infer the required details without searching externally.
• Improved User Experience: Directing users to a dedicated FAQ can help alleviate confusion and reduce the number of steps required to find a solution.

Conclusion

Improving the user experience for adding a server URL and an authentication token is crucial for onboarding to the tool. By clarifying the required connection details and linking to a dedicated connection FAQ, we can enhance the overall usability of the Matomo Connector for Looker Studio and reduce the number of steps for users that get stuck.

support re-aggregation of all Matomo metrics

Looker Studio supports creating reports with arbitrary dimensions and metrics. If a flattened report has multiple dimensions and only one is selected, Looker Studio will try to aggregate the columns so only a single instance of each dimension value remains in the chart.

But this only works when the right metadata is present in the connector schema (specifically, how metrics are aggregated). Currently, we set every metric to be non-re-aggregatable.

To make normal metrics in Matomo re-aggregatable:

• introduce aggregation metadata in Matomo core and fill it out for all available reports
• in the connector, set the aggregation based on this metadata

To make processed metrics in Matomo re-aggregatable:

• introduce a metadata to reveal the processed metric's formula (eg, bounce_count / nb_visits)
• introduce mechanism to include all temporary metrics used in the computation
• in the connector
  • set metric formulas based on Matomo metadata & set aggregation to AUTO
  • fetch all temporary metrics
  • if possible, hide temporary metrics from being used by the end user

Something to keep in mind: many processed metrics in Matomo do not use columns in the report, but other data, such as metrics in past data. These would have to be made available for Looker Studio.

Workaround

There is currently a workaround that can be used in some cases. Users that want to re-aggregate can create their own calculated field that manually specifies the aggregation, and add that with the single dimension they want.

support unique visitors for week/month/years if computed in the target Matomo

Looker Studio only supports querying by arbitrary date ranges. It does not support the concept of periods.

Currently we detect when a range is just a day, and query with period=day instead of period=range. This allows us to display unique visitors for days.

However, Matomo supports calculating unique visitors for other periods if configured correctly so it's possible to get this data to Looker Studio.

Supporting unique visitors for week/month/year periods would require:

• in the connector detect when a range is a week/month/year in matomo, and query that period

better error messages for non-exception errors

It seems like some errors that arise are not, and do not look like, Error instances. So they have no message or stack property. They could just be strings, but in case they are not, the connector should be able to inspect them and log some useful information.

single metric value is incorrect when date range is for whole month

In Looker Studio when viewing a single metric for an entire month, an incorrect value appears to be displayed, specifically, the metric value for the first day of the month, rather than the visits for the whole month:

If the range is changed so it does not span the entire match, the metric value is correctly displayed as the sum of visits over the entire range:

allow more than one instance of the tests to run at a time

Currently, the tests require that an Apps Script project be setup beforehand, and this project deployed to it. This is fine for local development, but within CI, this means only one build can be running at a time.

To fix this:

• before a test run, create a new test Apps Script project (also delete any existing test Apps Script projects that were not deleted)
• delete the test project when done

[BUG] When using "All Websites -> All Websites Dashboard" Report, Ecommerce Orders and Conversions are always 0

When using "All Websites -> All Websites Dashboard" Report, Ecommerce Orders and Conversions are always 0, but correct values are provided by the API response.

Reproducibility:

• Create Data Connection
• Select "All Websites -> All Websites Dashboard" Report
• Create new Table Visualisation with "Websites" as a Dimension and "Ecommerce Orders" and "Conversions" as Metrics.
• Correspondingvalues are 0, even though the MultiSites API responds with the correct numbers (and revenue is correct)

Tested this with 2 different Matomo instances.

set default report template for users to use

Connectors can set a default report template by modifying the appsscript.json file:

However, adding it is not straightforward. In order for users to use the template successfully, they need to use a specific connector configuration. The report must be set to API > Main Metrics and the segment parameter must be made alterable. If users do not do this, the created report will fail to load properly.

Possible solutions to this problem:

• Add informational text letting users know they need to use specific options. Note: it is not possible for the connector to detect whether the checkbox to use the default report is selected, so we can't conditionally show this text.

• Allow not connecting to a report, giving the user the full list of dimensions and metrics Matomo supports in one data source. This will make it possible for the report to load with minimal configuration, but if a user uses an unsupported dimension/metric combination (which would be very easy to do), they will receive an error. Users will still have to allow the segment to be overridden.

Neither solution is ideal.

Querying "Actions > Page Urls" for multiple dates can be very slow

Querying data for one day for this Page URLs works, getting data for a larger period, however, can be very slow.

This is due to the following reasons:

• Looker Studio has no concept of hierarchical reports, so we flatten the reports. For some Matomos with many different page URLs, this can take some time, and the process is repeated for every paginated request to get the data.
• The cost of loading one day of reports is multiplied by the number of days requested. If an entire month is requested, that's (potentially) 30x the processing.

To resolve this completely, this will likely need fixes either in the core product (or Matomo Cloud's infrastructure) and changes to the way the connector requests data.

Grouping Failure in Looker Studio with Matomo Connector

There is a critical issue with the Matomo Connector used in Looker Studio where identical values from calculated fields are not being grouped as intended across all visualizations, including pie charts, tables, and others. This bug disrupts data analysis, as each instance of a value is treated as unique, leading to a fragmented and misleading representation of the data.

Steps to Reproduce:

• Connect Looker Studio to Matomo using the Matomo Connector.
• Create a calculated field that should logically group identical values together.
• Attempt to visualize this data in a pie chart, table, or any other visual format.

Expected Behavior:
The visualization should consolidate identical values into single groups for clear and accurate data representation, irrespective of the type of visualization used.
(see Screenshot: left: Matomo Connector right: GA4 Connector)

Actual Behavior:
Despite the use of calculated fields designed to group identical values, the visualizations treat each instance as unique. This results in an inflated number of groups and an erroneous depiction of the dataset. This issue is observable in pie charts, where it generates an excessive number of slices, as well as in tables, where rows that should be combined are instead displayed separately.

Impact:
This bug severely affects the usability of Looker Studio with the Matomo Connector for meaningful data analysis and visualization, as it prevents accurate aggregation of data points.

Additional Information:

The problem persists regardless of the visualization format.
This is not an isolated issue; it has been replicated with various data dimensions.

translate the Date dimension added by the connector

The Date dimension is added by the connector specifically for time series' in Looker Studio. This means it does not come from Matomo and will not be translated to the selected language, which looks odd when every other column is translated. We need some way to translate this dimension, just for Looker Studio.

based on requested fields, send showColumns value to reduce payload size

When fetching data, the connector will use pagination to make sure we don't surpass the 50mb HTTP response size limit in Apps Script. We can make it less likely and possibly reduce the time it takes for report data to load by also hiding columns that were not requested by Looker Studio.

This can be accomplished by:

• modifying getData() to send the showColumns= API parameter with the columns specified in request.fields

detect when a matomo version is < 4.14 and display a warning

Metric type metadata was only added in 4.14, so many functions in Looker Studio won't work properly when connecting to such an instance. This is mentioned in a FAQ, but it could also be mentioned on the configuration page.

change name and order of `API > Main metrics`

To be more useful to users, in the connector:

• Rename API > Main Metrics to Overview > Main metrics.
• Move the report to the top of the list.

Confusing progression instructions when adding data from connected instance.

When adding data from an already connected Matomo instance, the form window still says 'Click "CONNECT to continue.' even though the correct action is to click 'Add' at the bottom right on the window.

This message is also shown when editing an existing connection and the correct action would be to click 'Reconnect' at the top right of the window.

As the wording and location of the button varies, the colour of the button seems to be the only constant, although I'm not sure saying 'Click the blue button' would bring full clarity as other blue buttons may be present on the screen.

when authentication fails, check that the username looks like a URL

If it does not look like a URL we can report to the user via an error that the username should be a URL to a Matomo instance.

Might reduce some support requests.

add Goal Name as a "virtual" dimension

Matomo doesn't return the goal name as a column in any of it's reports. There are per-goal metrics, where the goal name is part of the column name, but never an instance where the goal name is a separate column next to metrics.

However, it might be possible to virtually add this column if requested within the connector..

support connecting to the Live.getLastVisitsDetails (visitor log) report

Some users may want to have this data available in Looker Studio. Unfortunately, the API method for the Visitor Log, Live.getLastVisitsDetails is not a normal Matomo report.

It has no metrics, just dimensions, some of which are hierarchical, and is not included in the Matomo metadata API (because it is not meant to be embedded automatically in API consumers). Furthermore, there may be privacy concerns with providing access to this data.

Despite these complications, it would be pretty impactful if there were some way to support this.