Track a website’s carbon footprint with CO2.js and Matomo Tag Manager

Cloud On-Premise

CO2.js is an external, open-source JavaScript library that estimates the carbon emissions associated with transferring data over the internet. CO2.js is not part of Matomo.

This guide explains how to use CO2.js to estimate the carbon emissions associated with each page view. Matomo Tag Manager sends the CO2 value to Matomo as an event. Once collected, you can analyse these estimates in Matomo reports.

Note: CO2.js provides an estimate rather than a direct measurement of carbon emissions. The result depends on the data and assumptions used by its carbon estimation model.

Install CO2.js

Install and initialise the CO2.js library on your website according to the CO2.js documentation.

Configure Matomo Tag Manager

You will need to create a Custom HTML tag that calculates the estimated emissions for each page. The tag then pushes the calculated value to the Matomo Tag Manager data layer.

  1. In Tag Manager, go to Tags and click Create New Tag.
  2. Choose the Custom HTML tag type.
  3. Provide a unique Name and optional Description.
  4. Select the Pageview trigger.
  5. Set the Position to Body End.
  6. In the Custom HTML field, add your script that calculates the page emissions.
  7. In this code example, greenHost is set to false. Change this value if you know the data is transferred from a green host:
<script>
  // 1. Determine the bytes transferred for this page
  const resources = performance.getEntriesByType("resource");

  const bytesSent = resources.reduce(function(total, resource) {
    return total + (resource.transferSize || 0);
  }, 0);

  // 2. Calculate the estimated emissions
  const emissions = new co2.co2();
  const greenHost = false;

  const estimatedCO2 = emissions
    .perByte(bytesSent, greenHost)
    .toFixed(3);

  // 3. Push the result to the Matomo Tag Manager data layer
  window._mtm = window._mtm || [];
  window._mtm.push({
    event: "co2Calculated",
    pageEmissions: estimatedCO2
  });
</script>

CO2.js returns the estimated emissions in grams of carbon dioxide equivalent (g CO2e). For example, a value of 0.8 represents an estimated 0.8 g CO2e for the page data included in the calculation.

The script uses the browser’s Resource Timing API to determine the transferred bytes. The transferSize value may be 0 for cached resources and some cross-origin resources. The estimate therefore reflects the transfer information available to the browser and may not include every page resource. Read more about Calculating emissions per byte on the Green Web Foundation’s website.

Read the carbon emission value

Next, create a Data Layer Variable to make the calculated value available to other tags.

  1. Go to Variables and click Create New Variable.
  2. Choose the Data Layer Variable type.
  3. Provide a user-friendly Name and optional Description.
  4. Enter pageEmissions as the Data Layer Variable Name.
  5. Save the new variable.

Create a trigger for the CO2 calculation

This Custom Event trigger fires when the calculation has completed.

  1. Go to Triggers and click Create New Trigger.
  2. Choose the Custom Event trigger type.
  3. Provide the Event Name, for example co2Calculated.
  4. Save the new trigger.

The co2Calculated event is pushed to the Matomo Tag Manager data layer by the Custom HTML tag. It signals that the emissions value is available.

Send the estimated emissions to Matomo

Create a Matomo Analytics tag to record the calculated value as an event.

  1. Go to Tags and click Create New Tag.
  2. Choose the Matomo Analytics tag type. This tag will send the actual analytics event to Matomo.
  3. Set the Tracking Type to Event.
    define event tracking
  4. Configure the event values as needed, for example:
    • Category: Consumption
    • Action: {{PageTitle}}
    • Name: co2Calculated
    • Value: pageEmissions (data layer variable containing the CO2.js result)
  5. Select the Custom Event trigger created for the co2Calculated event.
  6. Save the tag.

The co2Calculated data layer event triggers this tag. The Matomo Analytics tag then sends the calculated emissions value to Matomo.

Test the event tracking

Use Preview and Debug mode with your browser’s developer tools to verify the configuration before publishing the Tag Manager container.

  1. Go to your website and reload the page.
  2. Open your browser’s developer tools and select the Console tab.

  3. Enter: _mtm to confirm the co2Calculated entry contains pageEmissions.

  4. In Debug mode, confirm the Custom Event trigger fires and executes the Matomo Analytics Event tag.

  5. Verify that the event contains the pageEmissions and then publish the container.
    view co2 event in matomo

Analyse the carbon emission estimates

After Matomo processes the events, go to Behaviour > Events reports to analyse total estimated carbon emissions recorded across your website and estimated emissions for individual pages.

Interpret the emission value

CO2.js returns an estimated carbon footprint in grams of carbon dioxide equivalent (g CO2e). Lower values indicate lower estimated emissions for the page data included in the calculation.

You can compare results between pages and monitor changes over time to identify pages with higher estimated emissions. For additional context, the Website Carbon rating system benchmarks page emissions from A+ at 0.095 g CO2e per page view through to F at 0.847 g CO2e or more per page view. Treat these benchmarks as a reference rather than an absolute measure.

Previous FAQ: How to set up dual tracking with Matomo and Piwik PRO