Migrate from ngx-matomo to ngx-matomo-client

Funny enough, my first interaction with Matomo was on the exact date they switched from Piwik.

While ngx-matomo has been my go-to library for Matomo integration in Angular projects ever since, its delayed compatibility with recent Angular versions has motivated me to research other available options.

In this article, I'll go over the reasons you might want to stick to ngx-matomo, but also what to do when you decide to switch.

Why ngx-matomo to begin with?

When I first had to integrate Matomo in an Angular project, ngx-matomo was one of the few libraries available. It was quick to set up and easy to understand, so it was the best choice at the moment, the alternative being writing the integration from scratch. 

We used features ranging from tracking regular user navigation to advanced tracking via tag manager configurations and custom variables.

What I appreciate about the library:

• it's easy to get started with
• it has simple user consent management
• it comes with a small bundle, of 16.18kb on the production build

If you are already using ngx-matomo and are not looking to use the latest versions of Angular early on, this library still covers most of the use cases you might be looking for.

You can follow this thread for updates on the latest Angular version support (Angular 18).

Best alternative: ngx-matomo-client

Previously distributed as two separate packages (ngx-matomo/tracker and ngx-matomo/router), ngx-matomo-client is now the most popular and well-maintained Angular library for Matomo integration. Taking into account also its resemblance to the existing library and its minimal impact of just 15.92 kb on our production build, ngx-matomo-client stood out as the most logical for replacing ngx-matomo.

If you are starting from scratch, I would definitely recommend going directly for the ngx-matomo-client library.

In the following sections, I will show you how I translated the capabilities of ngx-matomo into ngx-matomo-client.

Configuration

First up, is the configuration. This part has suffered the most changes, but it is still quite straightforward. 

In ngx-matomo, the configuration and module import might look something like the following:

// app.module.ts
import { MatomoModule } from 'ngx-matomo';
...
imports: [
  ...
  MatomoModule.forRoot(environment.matomoConfig)
  ...
]

// environment config

matomoConfig: {
  scriptUrl: `${matomoBaseUrl}/js/container_<containerId>.js`,
  trackers: [
    {
      trackerUrl: `${matomoBaseUrl}/matomo.php`,
      siteId: 1,
    },
  ],
  requireConsent: true,
  routeTracking: {
    enable: true,
  },
},

For ngx-matomo-client it is a bit simpler, making use of Angular injection for including route tracking:

// app.module.ts
import { MatomoModule, MatomoRouterModule } from 'ngx-matomo-client';
...
imports: [
  ...
  MatomoModule.forRoot(environment.matomoConfig),
  MatomoRouterModule,
  ...
]

// environment config

matomoConfig: {
  siteId: 1,
  trackerUrl: `${matomoBaseUrl}`,
  scriptUrl: `${matomoBaseUrl}/js/container_<containerId>.js`,
  requireConsent: 'tracking',
},

If no route tracking is needed, the MatomoRouterModule can be skipped and the import of MatomoModule can be adjusted to avoid dependencies on @angular/router as seen below:

// app.module.ts
import { MatomoModule } from 'ngx-matomo-client/core';
...

If you only need to ask user consent for using cookies and not the tracking itself, the equivalent configurations are the following:

// ngx-matomo
{
  ...
  requireConsent: false,
  requireCookieConsent: true
}

// ngx-matomo-client
{
  ...
  requireConsent: 'cookie'
}

User consent management

For managing user consent opt-in, there is not much difference between the two libraries. Both of them have similar methods on a class called MatomoTracker, so what you have to do is make sure you change the import to the new library.

import { MatomoTracker } from 'ngx-matomo-client';

// usage
this.matomoTracker.rememberConsentGiven(hoursToExpire);
this.matomoTracker.forgetConsentGiven();

Custom variables and custom dimensions

Similar to user consent, methods like setUserId, setCustomVariable, setCustomDimension are the same for both libraries. Here as well you just need to make sure the import is updated to the new library.

Custom event triggers

In our project, we had the need to create triggers based on custom events. This is a requirement that none of the two libraries provide a wrapper for, so for this, we were left interacting directly with the _mtm object.

You can read more about this and why we no longer use a third-party library in my article about architectural mistakes.

Closing thoughts

When looking into libraries I looked into the ones that focus on direct integration with Matomo. If you are looking for a vendor-agnostic library you might want to look into the following:

• https://www.npmjs.com/package/angulartics2

I hope you found this article helpful. Let me know in the comments section what was your experience with integrating Matomo.