Documentation

5.1.1 Overview

The System - Google Tag Manager plugin integrates Google Tag Manager (gtag.js) into your Joomla website, offering a simple way to manage analytics and tracking while ensuring privacy compliance. With this plugin, you can add your Google Tag Manager measurement ID, choose which consent types to enable, set their default states, and mark specific consents as mandatory. It works seamlessly with the System - EU e-Privacy Directive plugin to let users manage their consent preferences, and with System - Google Tag Manager ACL to grant access to Joomla ACL access levels based on consent given.

This plugin is perfect for Joomla site owners who need powerful tracking with customizable privacy controls.

Requirements

• A valid Google Tag Manager Measurement ID (e.g., G-XXXXXXXXXX)
• (Optional) The System - EU e-Privacy Directive plugin for consent management integration

Installation

1. Download the Plugin: Get the plugin package from this website or the latest version is linked in the Joomla Extensions Directory.
2. Install via Joomla:
   
   • Log in to your Joomla Administrator panel.
   • Go to Extensions > Manage > Install.
   • Upload the plugin package file using the "Upload Package File" tab.
   • Look for a confirmation message once installed.
3. Enable the Plugin:
   
   • Navigate to Extensions > Plugins.
   • Search for "System - Google Tag Manager".
   • Click the status icon to enable it (don't forget to configure with your Google provided measurement id).

Configuration

Configure the plugin by going to Extensions > Plugins, finding "System - Google Tag Manager", and opening its settings. The options are grouped into three sections: Basic, Consent Types, Mandatory Types, and Events.

Basic Settings

1. Measurement ID  
   • Purpose: Specifies your Google Tag Manager Measurement ID to enable tracking.  
   • Instructions: Enter your Measurement ID (e.g., G-XXXXXXXXXX) in the provided field. You can find this in your Google Tag Manager account under "Container Settings". This is required for the plugin to work.
2. Anonymize IP  
   • Purpose: Controls whether visitor IP addresses are anonymized for privacy.  
   • Instructions: Choose between "No" or "Yes". Select "Yes" to mask the last octet of IP addresses (e.g., for GDPR compliance). The default is "No".

Consent Types

This section lets you decide which consent types to enable and their default settings. Consent types determine what tracking or storage activities are allowed on your site.

Neil Peart - Freewill: "If you choose not to decide, you still have made a choice"; System - Google Tag Manager will still operate with no enabled types.  It simply omits the consent signal, which will cause Google Analytics to complain that you have not set up consent.

1. Enabled Types  
   • Purpose: Select which consent types your site will use.  
   • Options:  
     • Ad Storage: For advertising-related storage (e.g., cookies).  
     • Ad User Data: For sending user data to Google for online ads.  
     • Ad Personalization: For personalized advertising.  
     • Analytics Storage: For analytics data (e.g., visit duration).  
     • Functionality Storage: For site functionality (e.g., language settings).  
     • Personalization Storage: For personalization (e.g., video recommendations).  
     • Security Storage: For security features (e.g., authentication, fraud prevention).
   • Instructions: Check the boxes next to the consent types you want to activate. Only selected types will apply to your site.
2. Default Consent Settings  
   • Purpose: Sets the initial state (granted or denied) for each enabled consent type.  
   • Options: For each type you enable, you’ll see a setting (e.g., "Ad Storage Default") with two choices:  
     • Denied (default)  
     • Granted
   • Instructions: For each enabled type, choose "Granted" to allow it by default or "Denied" to block it until the user consents. Users can override non-mandatory defaults via the System - EU e-Privacy Directive plugin (if installed).  
   • Details:  
     • Ad Storage Default: Controls advertising storage.  
     • Ad User Data Default: Controls sending ad-related user data.  
     • Ad Personalization Default: Controls personalized ads.  
     • Analytics Storage Default: Controls analytics storage.  
     • Functionality Storage Default: Controls functional storage.  
     • Personalization Storage Default: Controls personalization storage.  
     • Security Storage Default: Controls security storage.

Mandatory Types

1. Mandatory Types  
   • Purpose: Defines which consent types users cannot deny.  
   • Options: Same as "Enabled Types" (Ad Storage, Ad User Data, etc.).  
   • Instructions: Check the boxes for consent types that must always be "Granted". These are enforced and cannot be changed by users, ensuring essential features remain active.

Events

Events warrant special consideration, as they might be beyond the experience level of non-technical users.  This category of configuration has its own set of tutorials, however, the basics are:

Click Event Triggers

At this time, the plugin only tracks click events.  I'll add other event types as I see a need, or as requested.

This repeating field allows you to configure special click events, that send custom data to Google Analytics.  I use it to track downloads in my software repository.  I can (and do) track it here on the site, but GA allows me to see where those downloads are coming from, and more easily analyze the data.

Each event trigger has 3 settings:

• Event Name
  • This gives you something to track within analytics.  Keep it simple.
• Selector
  • This indicates WHICH elements are being tracked.  You'll need to understand how query selectors work, you can find a tutorial here:
    • https://www.javascripttutorial.net/javascript-dom/javascript-queryselector/
• Data
  • This is the data to be sent, and it can be obtained in 2 ways:
    1. Attribute List
       • Simply, a comma separated list of attribute names that the plugin will find in the clicked element.  Let's say your element has some data attributes (data-category="123" and data-product-id="123"), you would enter into the data field:
         • data-category,data-product-id
       • The plugin would send that data to GA as {"data-category":123,"data-product-id":123}
    2. Window Scoped Function
       • The plugin will determine if your window scoped function exists, and then call that function using the clicked element as an argument.  Your function is expected to return a javascript object.  If the object is empty, the plugin will NOT send it to GA.

Integration with System - EU e-Privacy Directive

When paired with the System - EU e-Privacy Directive plugin:

• System - Google Tag Manager registers its enabled consent types automatically.
• Users see a consent interface (provided by System - EU e-Privacy Directive) to accept or deny non-mandatory types.
• Mandatory types are locked as "Granted" and cannot be declined.
• Consent choices are saved in a cookie (plg_system_gtag_consent) and sent to Google Tag Manager for tracking compliance.

Integration with System - Google Tag Manager ACL

When paired with the System - Google Tag Manager ACL plugin:

• Signals sent to Google can be mapped to Joomla ACL access levels.
• Users consent to one of the signals activates the ACL for that signal - even for guests.

Usage

1. After Configuration:
   • Save your settings by clicking "Save" or "Save & Close".
   • The plugin adds the Google Tag Manager script (gtag.js) to the <head> of frontend HTML pages (not admin pages).
   • Tracking starts once a valid Measurement ID is entered and the plugin is enabled.
2. Testing:
   • Use Google Tag Manager’s "Preview" mode to confirm tracking works.
   • Check your browser’s console or network tab to see the gtag.js script loading from https://www.googletagmanager.com/gtag/js?id=[Your Measurement ID].
   • If using System - EU e-Privacy Directive, test the consent interface to ensure user choices are applied correctly.

Troubleshooting

• Tracking Not Working:  
  • Verify the Measurement ID is correct (e.g., G-XXXXXXXXXX).  
  • Ensure the plugin is enabled.  
  • Test on a frontend page, not the admin area.
• Consent Options Not Visible:  
  • Confirm System - EU e-Privacy Directive is installed and active.  
  • Check that at least one consent type is enabled under "Enabled Types".
• Unexpected Behavior:  
  • Review your "Mandatory Types" settings—mandatory consents override user choices.

Note for Third-Party Developers

If you’re managing consent outside of System - EU e-Privacy Directive, you can interface with this plugin by placing a JSON object in a cookie named plg_system_gtag_consent. The object should have this structure:

{
  "ad_storage": "granted",
  "analytics_storage": "denied",
  "security_storage": "granted"
}

• Purpose: This sets default consent states for future page loads, overriding the plugin’s configured defaults unless marked as mandatory.
• Supported Keys: ad_storage, ad_user_data, ad_personalization, analytics_storage, functionality_storage, personalization_storage, security_storage.
• Values: "granted" or "denied".
• Behavior: The plugin reads this cookie on page load and updates Google Tag Manager via gtag('consent', 'update', ...). Mandatory types (set in the plugin config) will still enforce "granted".