config.php.example

<?php

// -----
// Important: read the instructions in README.md or at:
// https://github.com/matomo-org/tracker-proxy#readme
// -----

// Edit the line below, and replace http://your-matomo-domain.example.org/matomo/
// with your Matomo URL ending with a slash.
// This URL will never be revealed to visitors or search engines.
$MATOMO_URL = 'http://your-matomo-domain.example.org/matomo/';

// Edit the line below and replace http://your-tracker-proxy.org/ with the URL to your tracker-proxy
// setup. This URL will be used in Matomo output that contains the Matomo URL, so your Matomo is effectively
// hidden.
$PROXY_URL = 'http://your-tracker-proxy.org/';

// Edit the line below, and replace xyz by the token_auth for the user "UserTrackingAPI"
// which you created when you followed instructions above.
$TOKEN_AUTH = 'xyz';

// Maximum time, in seconds, to wait for the Matomo server to return the 1*1 GIF
$timeout = 5;

// By default, the HTTP User Agent will be set to the user agent of the client requesting matomo.php
// Edit the line below to force the proxy to always use a specific user agent string.
$user_agent = '';

// How the real visitor IP is sent to Matomo.
//
// By default ($http_ip_forward_header empty) the proxy sends the visitor IP to Matomo as the
// `cip` tracking parameter, authorized by your $TOKEN_AUTH. This works out of the box for both
// single and bulk tracking requests and needs no Matomo-side configuration.
//
// Alternatively, set $http_ip_forward_header (e.g. to 'X-Forwarded-For') to forward the visitor
// IP in that header instead. In this mode the proxy injects NO `cip`/token_auth at all and relies
// solely on the header for the visitor IP (so this mode does not even require a write/admin token).
//
// IMPORTANT: this only works if Matomo is configured to trust the header - both the http server in
// front of Matomo (Apache mod_remoteip / nginx realip) AND Matomo's trusted-proxy settings
// (proxy_client_headers[] / proxy_ips[] in its config.ini.php). If it is not, Matomo records the
// proxy's IP for every visitor.
//
// BREAKING CHANGE: previously this header was sent in addition to `cip`+token; setting it now
// switches the proxy to header-only IP forwarding. If you already set it, verify the Matomo
// trusted-proxy configuration above, or leave it empty to keep using `cip`.
//
// For apache http see https://httpd.apache.org/docs/2.4/mod/mod_remoteip.html
// for nginx see https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/
//
$http_ip_forward_header = '';

// By default, the proxy forwards the visitor's entire Cookie header to Matomo unchanged, which
// also forwards unrelated site cookies (session, consent tools, A/B testing, etc.).
//
// Set $COOKIE_ALLOWLIST to restrict what's forwarded. Each entry matches either an exact name
// (e.g. 'mtm_consent') or, if it ends with '*', a prefix (e.g. '_pk_id*' matches '_pk_id.1.1fff').
// Prefix entries are needed for Matomo's id/session/referrer/custom-variable cookies, since the
// JS tracker appends a per-site/per-domain suffix to their base name. Matching is case-sensitive.
//
// Typical Matomo cookie names/prefixes: '_pk_id*', '_pk_ses*', '_pk_ref*', '_pk_cvar*', '_pk_hsr*',
// 'mtm_consent', 'mtm_consent_removed', 'matomo_ignore'. Check your tracker config first: a custom
// setCookieNamePrefix() replaces '_pk_*' entirely, and enabled plugins may set cookies of their own.
//
// Leaving this unset (the default) forwards all cookies, for backward compatibility. Setting it to
// an empty array, or to a non-array value by mistake, forwards NO cookies (fails closed). A bare
// '*' or empty-string entry is a no-op, not "allow everything", so a typo can't defeat the allowlist.
//
// Always keep 'matomo_ignore' (or your opt-out cookie) in this list - dropping it silently
// re-enables tracking for opted-out visitors. A dropped tracking cookie otherwise just stops
// Matomo recognizing returning visitors, inflating visit counts; verify by loading a page twice.
//
// $COOKIE_ALLOWLIST = array('_pk_id*', '_pk_ses*', '_pk_ref*', '_pk_cvar*', '_pk_hsr*', 'mtm_consent', 'mtm_consent_removed', 'matomo_ignore');