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>

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.