Analytics - Add Matomo support, test and verify

[jesade-vbg]

Today, Analytics.js has working support for Plausible tracking since #1065, and is prepared (placeholder and commented example code etc) for Matomo tracking.

The Matomo tracking script need to be added, tested, edited and verified before pushed to dev.

[jacobwod]

Sounds good. In case you want a quick start:

• .env contains ANALYTICS_* keys. Use it and you'll get an object in mapConfig if you comment out the stubb I've prepared here:

  Hajk/new-backend/server/api/utils/getAnalyticsOptionsFromDotEnv.js

  Lines 41 to 49 in b87db22

  	// TODO: Adding support for Matomo should be as simple as…
  	// case "matomo":
  	// return {
  	// type: "matomo",
  	// options: {
  	// siteId: parsedOptions.option_siteid,
  	// trackerUrl: parsedOptions.option_trackerurl,
  	// },
  	// };

• Next, this should work pretty well once activated. It'll track both page views and custom events:

  Hajk/new-client/src/models/Analytics.js

  Lines 55 to 76 in b87db22

  	case "matomo":
  	// TODO: Adding support for Matomo should be as simple as…
  	//
  	// npm install matomo-tracker
  	// import MatomoTracker from 'matomo-tracker';
  	// Initialize with your site ID and Matomo URL
  	// const { siteId, trackerUrl } = config.options;
  	// const matomo = new MatomoTracker(siteId, trackerUrl);
  	// Next, subscribe to our two global observer events. Call
  	// corresponding Matomo methods:
  	// globalObserver.subscribe("analytics.trackPageView", () =>
  	// matomo.track()
  	// );
  	// globalObserver.subscribe(
  	// "analytics.trackEvent",
  	// ({ eventName, ...rest }) =>
  	// matomo.track({ actionName: eventName, ...rest })
  	// );
  	break;

It's been a while since I wrote it but it should be good unless they've changed the API somehow. 😄

[jesade-vbg]

Great, thanx! Hopefully it will work right away :)

[jesade-vbg]

I'm a bit confused, there are code in new-backend. I guess this is not added in .Net backend.

[jacobwod]

That's for sure. The part in Backend ensures that we read values from .env and put them in a nice place in map config. This is a nice and easy way to ensure that each map config (no matter which, as long as it's on the same Hajk instance) will use the same settings for analytics.

Another way (which I probably wrote about somewhere) is that we make it map-specific. In that we must extend Admin so you can edit the necessary fields to map config.

Anyway, for testing that the Client part works, just add the analytics key in the mapConfig object manually.

For production you will need to choose if you go the NodeJS way with settings in .env, or if you choose to write a new view in Admin and have this as a map setting. Finally, you can extend the .NET backend similarly and store the settings in Web.config I guess.

[jesade-vbg]

Ok. Right now it feels that adding (allowing) the analytics object in .Net backend would suffice. If this isnt done, backend would filter out the analytics object thats manually added to config.

[jesade-vbg]

The matomo-tracker package in the psuedo code is intended for nodejs and should not be used. Trying another lib for our purposes : @jonkoops/matomo-tracker

[jesade-vbg]

@jacobwod
Unfortunately Matomo is not compatible with current code. Plausible is much more forgiving regarding incoming data.
For example........ in Plausible:
{pluginName: "myPlugin"}

But in Matomo you'll need to specify:
{name: "pluginName": value: "myPlugin"}

This make it hard to automate translation. Especially as sometimes multiple key/values are sent. Matomo only acceps 1 pair as default without plugins. This also make it troublesome as activeMap: "mapName" and sometimes cleanMode is sent.

So right now it looks like I will need translate and hardcode all tracking events.

[jacobwod]

Are you sure? According to the documentation for the tracker you intend to use, you can do:

tracker.trackEvent({
  category: 'sample-page',
  action: 'click-event',
  name: 'test', // optional
  value: 123, // optional, numerical value
})

[jesade-vbg]

Yes exactly, but you will need to specify.
name: "pluginName", value: "sketch"
category and action is built in.

So as the event gets more than 1 key/value we cant possibly know what to put in name: "what name", value: "what value".

[jesade-vbg]

I'll investigate further........

[jesade-vbg]

So, because an event does not have a value as {value: "the value"}. A translation needs to be made to get the correct value.
It's kind of annoying.

const eventValueKeys = {
   pluginShown: "pluginName",
   mapLoaded: "activeMap",
   layerShown: "layerName",
   spatialSearchPerformed: "type",
   textualSearchPerformed: "query",
};

[jesade-vbg]

@jacobwod What do you think about the idea to move publish("analytics.trackEvent",x) below await this.#getRawResults and add a search result hit-count to the tracking event?

The positive: We get to track how many hits a search creates
The negative: The tracking occures after the results have been received.

I think the positive outweighs the negative as we will be able to get more relevant data for free. For example: If many people search for something that results in zero hits, maybe that would give us a hint that we can improve something, and this is just one use case.

Hajk/new-client/src/models/SearchModel.js

Line 70 in 4657375

// If the method was initiated by an actual search (not just autocomplete),

[jacobwod]

Sounds like a good idea. Perhaps we could take a look into the error object too (investigate a little what it contains, I'm not sure if just supplying error.message is enough or if it is needed). This way we could track failed searches. 👍

[jesade-vbg]

Regarding error. Its an array of objects. Is if something specific you would like to send. Maybe "${status}: ${reason}" from the first object?