Matomo analytics for back-end frameworks


I’m creating fastify-matomo, a plugin for the fastify back-end framework on NodeJS.

I looked at the tracking API and tried to fill every field I could :

  • action_name = route method + path (e.g. GET /item/:id)
  • url = the full request URL
  • _id = the user’s IP address & user-agent header concatenated and hashed using [CRC]-64 (one of the rare hashing algorithms I found that outputs 16-chars hexadecimal strings)
  • urlref = the user’s referer header
  • ua = the user’s user-agent header
  • lang = the user’s accept-language header
  • cdt = the request’s UNIX timestamp
  • pf_srv = the server’s response time (unless the plugin is set to run at request time)

Some fastify-specific details :

  • By default, the plugin is set to run at response time, i.e. when the onResponse hook is fired, which provides a getResponseTime method.
    • I’m using it to fill pf_srv (rounded, because it returns a decimal value in milliseconds).
    • I’m also using it to fill cdt, by subtracting it from the current timestamp.
  • The plugin can be set to run at request time, i.e. when the preHandler hook is fired.
    • In this case, I’m simply filling cdt with the current timestamp, and don’t fill pf_srv.
    • This option is needed when the route returns a non-HTTP response like WS or SSE.
  • The default method blindly on the framework’s time measurement, but I could have done it some other way :
    • always listen to both preHandler and onResponse
    • generate the current timestamp in both hooks
    • fill cdt with the first value
    • fill pf_srv with the subtraction of both

Have I done it right ?
Could I add more data ?
Are there useful resources regarding server-side analytics on Matomo ?

Thanks !

You may visit the link below to read this post with hyperlinks.

I don’t know this framework… But: Well done! :slight_smile:

Looking at it seems that some data are missing:

  • (I hope you provided a solution to set the matomo URL and site ID…)
  • rand (recommended) — Meant to hold a random value that is generated before each request. Using it helps avoid the tracking request being cached by the browser or a proxy.
  • apiv (recommended) — The parameter &apiv=1 defines the api version to use (currently always set to 1)
  • res — The resolution of the device the visitor is using, eg 1280x1024 .
  • h — The current hour (local time).
  • m — The current minute (local time).
  • s — The current second (local time).
  • plugins used by the visitor can be specified by setting the following parameters to 1: fla (Flash), java (Java), dir (Director), qt (Quicktime), realp (Real Player), pdf (PDF), wma (Windows Media), gears (Gears), ag (Silverlight).
  • cookie — when set to 1, the visitor’s client is known to support cookies.
  • (I hope also you provide solutions to track events, custom dimensions, content, media, ecommerce… :wink: )

I don’t know this framework

It’s an express alternative.

Well done!

Thanks !

I hope you provided a solution to set the matomo URL and site ID

I did : if you look at the main script, you’ll find those parameters declared at lines 16 and 18, then used at lines 28 and 33.

  • rand […]
  • apiv […]

Those are also provided at lines 35 (I used nanoid) and 36.

  • res […]
  • h […]
  • m […]
  • s […]
  • plugins used by the visitor […]
  • cookie […]

If I’m not mistaken, this data can only be detected client-side, however, my tracking is exclusively server-side.

I hope also you provide solutions to track events

I just started 2 days ago, so I’m not there yet, but I plan to.

custom dimensions, content, media, ecommerce…

Those, however, are way beyond what I need (and understand), so I don’t think I’d implement these features in the near future, although anyone is free to make a PR.

Salutations depuis Limoges :slight_smile:

Yes, you are right, I read too quick (and missed « back-end framework on NodeJS »
Then I think it will be difficult for you to track content interactions or media… (but you’ll be able to track content impressions)

Salutations Lyonnaises ! :hugs:

I’m mostly wondering if there are some people here, who would be experienced with both Matomo and back-end development, so they could tell me if I’m doing things right and if could add more data.

So, if not here, where could I find people experienced in back-end Matomo analytics ?


You can see here some of other tracking APIs, including some nodeJS APIs.
Maybe you can find some code examples in their GitHub repositories?

I browsed all of this already, the thing is, those modules are just wrappers to the API, but they don’t autocomplete the data like I do.