Analytics Module

The Confinity Analytics module allows to integrate Google Analytics and/or Matomo very easily. It also abstracts the tracking of custom events in order to easily switch between supported analytics provider (currently Matomo and Google Analytics).

Modules like Confinity.MediaPlayer and Confinity.Forms already come with some measuring points (custom events) out of the box.

Supported Providers

Currently we're supporting the following providers.

• Google Analytics (Universal Analytics [deprecated])
• Google Tag Manager (with Google Analytics 4)
• Matomo
• Matomo Tag Manager
• Microsoft Clarity

Installation

Add the Module to your Project

You can install the Analytics module from NuGet with

dotnet add package Confinity.Analytics

In your Startup.cs you can now register the module with the module builder by calling the AddModule method with AnalyticsModule. See Modules documentation for more information.

Add the Scripts to your Layouts

In your layout files, add @Html.ConfinityAnalyticsHeadAsync() inside the head tag and @Html.ConfinityAnalyticsBodyAsync() right after the opening body tag (as required for Google Tag Manager).

<!-- @include: @DocsDemos/Modules/Analytics/AnalyticsLayout.cshtml{5} -->

Configure Analytics in the Setting App

The last step is to configure Analytics in the Settings app in the Admin Panel. You should see an entry in the Settings app with the key Confinity.Analytics . Edit this entry and add the tracking code (JavaScript) from your analytics provider. If it makes sense for you, you can also add multiple providers. You can even add different tracking codes or providers to different websites.

Check if it Works

If everything is set up correctly, open the developer tools from your browser and set the log level to verbose. You now should see something like this:

Confinity.Analytics: Provider GoogleAnalyticsUniversal is active

Google Tag Manager Integration

Google Tag Manager Integration Code

<!-- Google Tag Manager -->
<script>(function (w, d, s, l, i) {
    w[l] = w[l] || [];
    w[l].push({
        'gtm.start':
                new Date().getTime(), event: 'gtm.js'
    });
    var f = d.getElementsByTagName(s)[0],
            j = d.createElement(s), dl = l != 'dataLayer' ? '&l=' + l : '';
    j.async = true;
    j.src =
            'https://www.googletagmanager.com/gtm.js?id=' + i + dl;
    var n = d.querySelector('[nonce]');
    n && j.setAttribute('nonce', n.nonce || n.getAttribute('nonce'));
    f.parentNode.insertBefore(j, f);
})(window, document, 'script', 'dataLayer', 'GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

Don't forget to replace the GTM-XXXXXX placeholder with your correct ID.

Custom HTML with script

Custom HTML with scrip tags is disabled by default. This can be enabled in the Analytics settings at runtime.

Configure Confinity Event Tracking

When using Google Tag Manager, custom events are being pushed to the Google Tag Manager data layer. So these events have to be forwarded to Google Analytics in order to use custom event tracking. In Google Tag Manager, create a new tag with the following settings.

• Name: Confinity Events
• Tag Configuration:
  • Tag Type: Google Analytics Universal Analytics
  • Track Type: Event
  • Category:
    • New variable with these settings:
      • Name: Confinity eventCategory
      • Variable Type: Data Layer Variable
      • Data Layer Variable Name: eventCategory
      • Data Layer Version: Version 2
  • Action:
    • New variable with these settings:
      • Name: Confinity eventAction
      • Variable Type: Data Layer Variable
      • Data Layer Variable Name: eventAction
      • Data Layer Version: Version 2
  • Label:
    • New variable with these settings:
      • Name: Confinity eventLabel
      • Variable Type: Data Layer Variable
      • Data Layer Variable Name: eventLabel
      • Data Layer Version: Version 2
  • Value:
    • New variable with these settings:
      • Name: Confinity eventValue
      • Variable Type: Data Layer Variable
      • Data Layer Variable Name: eventValue
      • Data Layer Version: Version 2
  • Non-Interaction Hit
    • New variable with these settings:
      • Name: Confinity nonInteractionHit
      • Variable Type: Data Layer Variable
      • Data Layer Variable Name: nonInteractionHit
      • Data Layer Version: Version 2
  • Google Analytics Settings: Choose your existing Google Analytics settings or create a new variable.
• Triggering:
  • Create new firing trigger with these settings:
    • Name: Confinity.Analytics
    • Trigger Type: Custom Event
    • Event name: Confinity.Analytics
    • This trigger fires on: All Custom Events

Matomo Tag Manager Integration

Configure Matomo for Consent Tracking with Custom Events

If you want to use the custom events provided by Confinity for consent tracking, make sure to configure Matomo correctly. For a basic setup, you can follow these instructions. With this setup, Matomo waits for user consent before setting any analytics cookies. It therefore behaves similarly to a setup where the option "Should Matomo use custom events for consent-tracking?" is disabled.

• Activate the feature by enabling "Enable Confinity consent tracking?".
  • Go to "System" → "Settings" → "Analytics" → "Matomo Tag Manager" in Confinity.
  • Enable "Enable Confinity consent tracking?"
• To require consent before setting any cookies, enable "Require cookie consent".
  • Go to "Tag Manager" → "Variables" → "Matomo Configuration" → "Edit variable" inside Matomo.
  • Enable "Require cookie consent"
• To bind the value pushed to the data-layer, add the variable "analytics_storage".
  • Go to "Tag Manager" → "Variables" → "Create New Variable" in Matomo.
  • Select "Data-Layer" as the variable type.
  • Set the "Name" to "analytics_storage".
  • Set the "Data Layer Variable Name" to "analytics_storage".
  • Confirm by clicking "Create New Variable"
• To bind the custom event sent by Confinity, add the trigger "Confinity.Consent: analytics_storage".
  • Go to "Tag Manager" → "Triggers" → "Create New Trigger" in Matomo.
  • Select "Custom Event" as the trigger type.
  • Set the "Name" to "Confinity.Consent: analytics_storage".
  • Set the "Event Name" to "Confinity.Consent".
  • Under "Only trigger when", add the condition: "analytics_storage" "equals exactly" "true".
  • Confirm by clicking "Create New Trigger"
• To enable cookies once consent is given, add the tag "cookie-consent".
  • Go to "Tag Manager" → "Tags" → "Create New Tag" in Matomo.
  • Select "Custom HTML" as the tag type.
  • Set the "Name" to "cookie-consent".
  • Insert the following HTML into the "Custom HTML" field:

    <script>
        _paq.push(['rememberCookieConsentGiven']);
    </script>
    
  • Under "Execute this tag when any of these triggers are triggered.", select "Confinity.Consent: analytics_storage".
  • Confirm by clicking "Create New Tag"
• (Optional) If your website runs exclusively over HTTPS, it's recommended to use secure cookies.
  • Go to "Tag Manager" → "Variables" → "Matomo Configuration" → "Edit variable" inside Matomo.
  • Enable "Enable Secure Cookie"

This concludes the basic setup. If you want to further configure Matomo, the custom-event "Confinity.Consent" provides the following values.

Add Custom JavaScript Events

The custom event tracking is an abstraction of the event tracking from Google Analytics and Matomo. So if you need more information about event tracking, you might want to read the documentation from Google or Matomo.

To track a custom event you can call the JavaScript method __cfyTrackEvent() which is globally available in the window scope. The function takes the following arguments.

List of Arguments

Example

// track a play event from a video player
__cfyTrackEvent('Video player', 'Video play', 'Name of my video');

// track a pause event from a video player and add current time in seconds as value
__cfyTrackEvent('Video player', 'Video paused', 'Name of the video', 30); 

Tracking 404 Pages with Matomo

If you would like to track 404 pages with Matomo, please add the following code

if (window.__cfyAnalyticsIs404) {
    _paq.push(['setDocumentTitle', '404/URL = ' + encodeURIComponent(document.location.pathname + document.location.search) + '/From = ' + encodeURIComponent(document.referrer)]);
}

just before the line

_paq.push(['trackPageView']);

in your Matomo tracking code. In the matomo admin console in Behaviour > Page Titles, you'll then see a list of all 404 pages.

More information: How to track error pages (404 pages) in Matomo?

Tracking with Microsoft Clarity

Clarity is relatively new and changing. Therefore issues might occur.

To be GDPR compatible you have to turn off the cookie. Confinity will do the rest. https://learn.microsoft.com/en-us/clarity/setup-and-installation/cookie-consent?source=recommendations

Known issues:

• Custom event tracking is supported, but are handled different by clarity. If you just use the category and action parameters everything will work as expected. If more arguments are provided it will switch to the arguments as array and put all parameters after category in the array __cfyTrackEvent()
• According to the documentation, google analytics is loaded in the frontend. This does not seem to be the case always. In the Configuration the flag to enable the Google Analytics integration just sets the CSP headers, which won't be needed if the script is not loaded.