Matomo In Depth

Opt-out

Matomo core - Opt-out

This guide is intended for Matomo core developers. For information on integrating opt-out forms please check out the Opt-out Tracking Guide.

Two different opt-out form implementations are included in Matomo, this guide explains how they work and the reasoning behind the implementations.

Background

Until version 4.12 Matomo included an opt-out form generator implemented as an iFrame which would then set third-party consent cookies for the JavaScript tracker. With browser support for third-party cookies gradually being phased out, this iFrame opt-out was replaced with a solution where the opt-out form could be served as part of the website and set first-party cookies.

The Matomo JavaScript tracker includes opt-out functions _paq.push(['optUserOut']); and _paq.push(['forgetUserOptOut']); which provide a simple, standardised way to record user opt-out, however loading third-party tracking JavaScript can be unreliable for users with strict security settings and is potentially inappropriate for some sites.

Because of this two opt-out form implementations are provided, one which tries to use the Matomo JavaScript tracker code to record the opt-out and one implementation which is completely self-contained, making no server requests and using no remote resources. This allows site administrators the flexibility to choose the approach most suitable for their circumstances.

Opt-out using the Matomo JavaScript Tracker

The embed code consists of:

  • A <div> with an id which will contain the opt-out form and can be placed anywhere on the page as styled as needed.
  • A <script> tag which loads JavaScript from the CoreAdminHome optOutJS controller method, passing configuration as URL parameters.
<div id="m-opt-out"></div>
<script src="/index.php?module=CoreAdminHome&action=optOutJS&language=auto&div=m-opt-out">
</script>

The optOutJS method returns dynamically built JavaScript to create the opt-out form based on the supplied URL parameters. Text translation is done server-side based on the requested or auto-detected language.

The optOutJS JavaScript will remain inactive until the DOMContentLoaded page event fires, at which point the following process will be followed:

Direct Cookies Using JS Tracker Settinguse Cookies If No Tracker enabled? JS tracker found? No Timeout hit? Get opt-out status from JS tracker Show opt-out message Use _paq.push to set opt-out status Yes Yes No Log console error No Opt out JS loaded Yes Custom cookie params? Yes Get opt-out status from custom cookie Show opt-out message Write direct cookie using custom params Get opt-out status from default cookie Show opt-out message Write direct cookie using default params No Done Done Done

Error messages will also be displayed in the content <div> if cookies are disabled or if the connection is not secure. If the specified content <div> is not found on the page then a <div> will be added so an error message can be shown.

For a description of URL parameters, see the Opt-out Tracking Guide.

Opt-out using self-contained code

The self-contained opt-out embed code consists of:

  • A content <div> with an id which will contain the opt-out form and can be placed anywhere on the page as styled as needed.
  • A <script> tag which contains all the JavaScript required for the opt-out form, all settings are in an inline object.

Text translations are stored as inline settings and generated for the chosen language when the embed code is generated.

<div id="matomo-opt-out"></div>
<script>
     var settings = {"showIntro":true,"divId":"matomo-opt-out","cookiePath":"","cookieDomain":"","cookieSameSite":"Lax","OptOutComplete":"Opt-out complete","snip":"snip"};

     ... other JavaScript code removed for clarity ...

<script>

The self-contained opt-out code will remain inactive until the DOMContentLoaded page event fires. It will then attempt to render the opt-out form using the following process:

  • Attempt to find the content div by id, if not found then new div will be added to the page in order to show an error.
  • Check that cookies are enabled, if not then an error will be shown in the content div.
  • Check that the connection is HTTPS if secure cookies are to be used, if not then an error will be shown in the content div.
  • The small inline JavaScript MatomoConsent class hasConsent method is used to read the consent cookie and determine opt-out status.
  • The opt-out form is rendered in the content div using the inline settings.
  • The opt-out form checkbox is connected to events which call MatomoConsent.consentGiven() or Matomo.consentRevoked(); to set or remove the consent cookie as needed.

For a description of inline settings, see the Opt-out Tracking Guide.