Send visits to Matomo

Starting with v3.7.0, Shlink can send every visit to a Matomo instance of your choice.

Matomo is an open source Google Analytics alternative, which can be self-hosted or used in the cloud, with a philosophy very much in line with Shlink’s.

Sending visits to Matomo will enable an alternative UI to check short URL visits, and take advantage of all its analytics capabilities.

Matomo integration FAQ

This is some general information and considerations when integrating Shlink with a Matomo instance:

• When enabled, all visits are sent to Matomo, no matter the runtime used to serve Shlink. When using a runtime that supports background jobs (like roadrunner), it will send the visits asynchronously, with no impact to end visitors. However, if you serve Shlink with a classic web server, visits will be sent to matomo before redirecting the visitor to the long URL.
• In order to integrate a matomo instance, you need to provide three configuration options:
  • An instance public URL that can be reached by Shlink.
  • The Site ID (usually a number). You can see how to get this value in their docs.
  • An API token. Their docs explain how to generate one.
• While Matomo supports sending data via GET and POST, Shlink will always use the latter, making sure data is secure as long as your Matomo instance uses HTTPS.
• Matomo tracks unique visits in intervals of 30 minutes. Any new visit from the same visitor within this interval will be tracked as an action of the same visit. This could make visits tracked by Shlink and Matomo differ.
• Shlink will send raw IP addresses to Matomo, to let it geolocate them in case something failed in Shlink side. Matomo has its own mechanism to anonymize visitor’s IP addresses.

Configuring Matomo integration

As with any other configuration params, there are two main ways to provide matomo integration options:

• Environment variables, which allow you to enable the integration however you like.

• The installation tool, which, at some point in the process, will ask you if you want to integrate with matomo, and request you to provide all required options.

   [...]
  
  INTEGRATIONS
  ============
  
    Do you want Shlink to send all visits to an external Matomo server? (yes/no) [no]:
    > yes
  
    Matomo server URL:
    > https://my-matomo-server.example.com
  
    Matomo site ID:
    > 3
  
    Matomo API token:
    > 15a010fec36a1f7d07f507ccd9ef1de5
  
   [...]

Sending existing visits

If you have been using Shlink for a while and start using Matomo at a later point in time, you may find yourself with existing visits that do not show in Matomo.

Starting with Shlink 4.1.0, Shlink provides a integration:matomo:send-visits command to send existing/old visits to your Matomo instance.

For example, if you started using Matomo on October 10th, 2023, you can send all visits which are older than that:

$ shlink integration:matomo:send-visits --until 2023-10-09