How do I use Matomo tracking on a website with caching (e.g. Akamai)?

If your website uses a caching layer such as Akamai, you can still track visits and Ecommerce activity accurately with Matomo.

When using the JavaScript tracking code, tracking requests are always sent directly from the visitor’s browser to your Matomo instance even when the page is served from cache. This means caching does not prevent data from being collected.

For Ecommerce data collection, no additional configuration is required for cached environments. As long as the tracking code runs in the visitor’s browser after each interaction or purchase, Matomo will record the events as expected.

However, there are optional configurations you can apply to improve tracking reliability or capture cache-related data, for example:

1. Use cache-bypass headers to ensure the tracking file is always requested from your Matomo server. Refer to the Akamai technical documentation.
2. Track whether a page was served from cache or from the origin using a Custom Dimension (example configuration below).

How to capture the cache status of a page using a Custom Dimension

When your site is served through Akamai, you can enable the Return Cache Status behaviour to expose whether a page was delivered from cache or from the origin. Once this header is available, your site or application can read it and pass the value into Matomo.

1. In Matomo, go to Administration > Websites > Custom Dimensions.
2. Create an Action Dimension and set the dimension as Active.
3. Take note of ID assigned to this Custom Dimension.
4. If your application can output a variable (e.g, window.cacheStatus or a server-side flag), send that value in setCustomDimension to Matomo before the trackPageView call.
5. For example, modify the tracking code by adding _paq.push(['setCustomDimension', 1, window.cacheStatus || 'unknown']);

<script>
  var _paq = window._paq = window._paq || [];

// Example: if the cache status is exposed via a response header or JS variable
  _paq.push(['setCustomDimension', 1, window.cacheStatus || 'unknown']);
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="//your-matomo-domain.example.com/";
    _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=u+'matomo.js'; s.parentNode.insertBefore(g,s);
  })();
</script>

Note on cache status and timing

If the cache status value is retrieved asynchronously, through a fetch request or delayed script, the rest of the code may continue running before the value becomes available. This means the trackPageView might execute before window.cacheStatus has a value, and the first hit would not include the dimension. To avoid this, you can check the following:

• The variable is rendered synchronously by the server, for example, it’s injected into the page as window.cacheStatus = "HIT" or "MISS". If your site exposes the cache status, ensure your tracking logic retrieves that value before sending the pageview request.
  Note: A HIT means the page was delivered from the CDN cache, while a MISS means it was fetched from the origin server. Capturing this status helps you compare engagement or performance between cached and uncached pageviews.

• If the value is determined asynchronously, delay the trackPageView call until the value is ready, for example by waiting for a promise to resolve or by using a short timeout fallback.

Once the configuration is successfully set up, you can now segment or build reports based on the cache status Custom Dimension to measure how caching impacts engagement, bounce rates, or conversion behaviour.