Set up a tracker proxy on your domain

You can optionally set up a tracker proxy to route tracking requests through your website domain (for example, mysite.com) instead of sending them directly to the Matomo tracking endpoint. The tracker proxy is supported with the JavaScript tracking code and Matomo Tag Manager.

This guide explains how to configure the tracker proxy using the JavaScript tracking code, which involves:

• Setting up a dedicated Matomo user.
• Downloading and configuring the proxy to forward requests.
• Updating your JavaScript tracking code to use the proxy URL.

Set up a Matomo user for the tracker proxy

A dedicated Matomo user is required if your tracker proxy authenticates requests when forwarding them to Matomo. In this setup, the proxy uses a token_auth value to authenticate tracking requests server-side. You will need to generate the token_auth in Matomo, then add it to the tracker proxy configuration on your server.

To set up the user and generate a token_auth:

1. Log in to Matomo as a superuser.
2. Create a new dedicated user, for example, named UserTrackingAPI.
   
3. Assign this user Write or Admin permission for all websites that will use the tracker proxy.
4. Log in as the new user.
5. Generate the authentication token and store it securely. The token_auth must not be restricted to secure (POST-only) requests. It is only used server-side by the proxy to authenticate tracking requests sent to Matomo and it is never exposed to the browser. If the proxy cannot reach Matomo Cloud, authentication does not occur and the proxy will silently fail.

Download the tracker proxy files

The Matomo tracker proxy consists of PHP files that you deploy on your web server.

1. Download the following files from the official Matomo tracker proxy repository: matomo.php, piwik.php, proxy.php, and matomo-proxy.php.
2. If you are using the Heatmaps and Session recordings plugin, you should also download plugins/HeatmapSessionRecording/configs.php.
3. These files work together to receive tracking requests and forward them to your Matomo instance.

In the next section, you will need to configure the proxy.php and upload all files so they are accessible on your domain (for example, https://mysite.com/matomo.php and https://mysite.com/proxy.php).

Configure the proxy to forward requests

1. Open the proxy.php file and edit the configuration variables.
2. Set $MATOMO_URL to your Matomo instance URL, and
3. The $TOKEN_AUTH must contain the token_auth generated for the dedicated Matomo user.
   
4. Upload all proxy files to your web server so they are accessible at the URL you intend to use for tracking.
5. To maintain a first-party tracking setup, host the proxy under the same site as your website. For example:
   • Website: https://mysite.com
   • Proxy URL: https://mysite.com/matomo.php
6. You can also use a subdomain (for example, analytics.mysite.com) if it belongs to the same site (mysite.com). If the proxy is hosted on a different domain, tracking requests may be treated as third-party.
7. You can now update your JavaScript tracking code to use the proxy URL.

Update the Matomo tracking code

1. Update your Matomo tracking code to send requests to the proxy endpoint by setting the tracker URL to your custom domain, for example: https://mysite.com/matomo.php.
2. The matomo.js file continues to load the tracking library as usual. The proxy only replaces the tracking endpoint used to send requests to Matomo.

Example: Before (direct tracking to the Matomo server):

//SAMPLE CODE
<!-- Matomo -->
<script>
  var _paq = window._paq = window._paq || [];
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);

  (function() {
    var u = "https://mysite.matomo.cloud/";
    _paq.push(['setTrackerUrl', u + 'matomo.php']);
    _paq.push(['setSiteId', '1']);

    var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
    g.async = true;
    g.src = "https://cdn.matomo.cloud/mysite.matomo.cloud/matomo.js";
    s.parentNode.insertBefore(g, s);
  })();
</script>
<!-- End Matomo Code -->

Example: After (tracking via the proxy on your website):

//SAMPLE CODE
<!-- Matomo -->
<script>
  var _paq = window._paq = window._paq || [];
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);

  (function() {
    var u = "https://mysite.com/";
    _paq.push(['setTrackerUrl', u + 'matomo.php']);
    _paq.push(['setSiteId', '1']);

    var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
    g.type = 'text/javascript';
    g.async = true;
    g.defer = true;
    g.src = u + 'matomo.php';
    s.parentNode.insertBefore(g, s);
  })();
</script>
<!-- End Matomo Code -->

If your tracking code includes a <noscript> image beacon that points directly to your Matomo server, update it to use the proxy URL. Remove it only if you do not want to use <noscript> tracking.

Test the tracking setup

After deployment, verify that tracking requests are sent to your domain and forwarded correctly to your Matomo instance.

1. Load the proxy endpoint directly in the browser (for example https://mysite.com/matomo.php).
2. If the proxy is working, the endpoint should load without a server error and may display a short message indicating that it is the Matomo tracking endpoint.
3. Open your browser’s developer tools and confirm that tracking requests are sent to your proxy URL rather than directly to your Matomo instance.
4. In Matomo, you can check the Visitors > Real-time report to confirm that tracking requests are processed.
5. If you see the message There was an error loading matomo.js, the proxy could not retrieve the Matomo JavaScript tracker from your Matomo instance. Check the following and test again:
   • The tracking code references your proxy URL on your website domain.
   • setTrackerUrl points to the proxy endpoint (for example https://mysite.com/matomo.php)
   • matomo.php exists on your web server and is accessible via the browser.
   • proxy.php contains the correct $MATOMO_URL including the trailing slash.
   • proxy.php contains a valid token_auth.
   • The token_auth belongs to the dedicated Matomo user created for the proxy.
   • The token_auth is not restricted to secure (POST-only) requests.
6. If the problem persists, review the PHP-based tracker proxy limitations below.

PHP-based tracker proxy limitations

The PHP-based tracker proxy requires the web server hosting the website to make outbound HTTPS requests to your Matomo instance. This includes retrieving the Matomo JavaScript tracker and forwarding tracking requests.

On some hosting environments, especially shared or managed hosting, outbound HTTPS requests from PHP may be restricted, filtered, or blocked without a clear error message. This can prevent the proxy from working correctly, even if PHP networking features appear to be available. The PHP-based tracker proxy may not be suitable if:

• your hosting environment restricts outbound HTTPS requests.
• you do not control server-level networking, DNS, or firewall settings.
• your hosting provider blocks server-side requests to external services.

Learn more about the tracker proxy.