GTM4WP – A Google Tag Manager (GTM) plugin for WordPress

By Thomas Geiger

★ 4.5/5 (155 ratings)700,000+ active installationsVersion 2.1.1

Advanced tag management for WordPress with Google Tag Manager

Description

Google Tag Manager (GTM) is Google’s free tool for everyone to manage and deploy analytics and marketing tags as well as other code snippets
using an intuitive web UI. To learn more about this tool, visit the official website.

This plugin places the GTM container code snippets onto your WordPress website so that you do not need to add them manually.
Multiple containers are also supported, and each container can have its own environment parameters, custom domain and custom path.

The plugin complements your GTM setup by pushing page meta data and user information into the so-called data layer.
Google’s official help pages include more details about the data layer.

PHP 8.0 and WordPress 6.3 are required to use this plugin.

GTM container code placement

The original GTM container code is divided into two parts:

The first part is a javascript code snippet that is added to the <head> section of every page of the website.
This part is critical to enable all features of GTM, and this plugin helps to place this part
correctly on your site.

The second part is an iframe snippet that acts as a failsafe/fallback should users’ JavaScript be disabled.
Google recommends – for best performance – to place this code snippet directly after the opening <body> tag on each page.

Albeit not ideal, it will work when placed lower in the code. This plugin provides a code placement option for the second code snippet.

If your WordPress theme is compatible with the additions of WordPress 5.2, then this plugin will place this second snippet in the right place.
Users of the Genesis theme, GeneratePress theme, Elementor, Oxygen Builder and Beaver Builder Theme will also have it placed correctly.
To utilize this, set the compatibility mode in the plugin options to off.

All other users can place this second code snippet using custom PHP code (the “Manually coded” option), or select the so-called “Footer” option
to add the code lower on the page (this is not the recommended way, but it will work).

Basic data included

  • post/page titles
  • post/page dates
  • post/page category slugs
  • post/page tag slugs
  • post/page author ID and name
  • post/page ID
  • post types
  • post format
  • post count on the current page + in the current category/tag/taxonomy
  • custom terms associated with any post type
  • logged in status
  • logged in user role
  • logged in user ID (to track cross device behavior in Google Analytics)
  • logged in user email address (both unhashed and SHA256 hashed values to be used with tracking)
  • logged in user creation date
  • site search data
  • site name and id (for WordPress multisite instances)
  • IP address of the visitor (please obtain the visitor’s explicit consent before using this)
  • post author data from PublishPress Authors, including co-authors and guest authors

Content & engagement data

Optional page variables that help with behavior tracking and Google Analytics 4 content grouping:

  • content word count and estimated reading time
  • last modified date and content age in days
  • comment count and comment status
  • page template, featured image presence, page hierarchy and sticky flag
  • primary category, detected from Yoast SEO or Rank Math
  • page language, detected from WPML or Polylang
  • optionally, titles, categories and terms in the default language of a WPML or Polylang site, so reports combine across translations

Browser / OS / Device data

  • browser data (name, version, engine)
  • OS data (name, version)
  • device data (type, manufacturer, model)

Data is collected in the browser using User-Agent Client Hints and pushed as a gtm4wp.deviceData event.
Note that Safari and Firefox expose less detail than Chromium based browsers.

Media player events

Track users’ interactions with any embedded media:

  • YouTube
  • Vimeo
  • Soundcloud
  • HTML5 audio and video
  • Dailymotion
  • Mixcloud
  • Cloudflare Stream
  • Wistia
  • JW Player
  • VideoPress
  • Spotify
  • Twitch

You can choose to fire data layer events when the media player loads, when the media is played, when it is paused or stopped,
and optionally when the user reaches 10, 20, 30, …, 90, 100% of the media duration. Each event also populates Google Tag
Manager’s built-in Video variables (Video Status, Video URL, Video Title, Video Provider, Video Duration, Video Current Time,
Video Percent, Video Visible).

Tracking is supported for embedded media using the built-in oEmbed feature of WordPress, as well as most other media plugins
and copy/pasted embed codes. Players inserted into the page after it has loaded (for example in a popup, a lightbox or via
AJAX) can also be tracked by turning on the optional “Track dynamically inserted players” setting.

Tag restrictions: allowlist & blocklist Tag Manager tags, triggers and variables

To increase website security, you have the option to allowlist or blocklist tags, triggers and variables.
You can prevent specific tags from firing, or prevent the use of certain variable types, regardless of your GTM setup.

If the Google account associated with your GTM account is compromised, an attacker could easily
execute malware on your website without accessing its code on your hosting server. By blocklisting custom HTML tags,
custom JavaScript variables and sandboxed scripts (custom tag and variable templates), you can secure the Tag Manager container.

Integration

Google Tag Manager for WordPress integrates with several popular plugins. More integrations to come!

  • Contact Form 7: fire an event when a form is submitted with any result (mail sent, mail failed, spam detected, invalid input, submission aborted or terms not accepted). Optionally push the Google Analytics 4 recommended form events (form_start, form_submit, generate_lead) as well
  • WooCommerce:
    • Implementation of GA4 E-commerce
    • Support for the Cart, Checkout, Mini-Cart, Product Collection and cross-sell blocks, not only the classic shortcode based pages
    • Enhanced Conversions user data on the purchase event for Google Ads
    • Compatibility with High Performance Order Storage (HPOS)
    • Refunds reported from the server through the Google Data Manager API (see below)
    • Does not support promotions, since WooCommerce does not have such a feature (yet)
  • Easy Digital Downloads (EDD 3.0+, beta): the same GA4 e-commerce events from view_item to purchase for the classic shortcodes and the EDD blocks, with Enhanced Conversions user data and reliable purchase tracking
  • CheckoutWC: optional support for its multi step checkout template
  • PublishPress Authors: co-author and guest author data in the page variables
  • WPML and Polylang: page language detection, plus optional default-language values for page variables, WooCommerce and EDD items and Contact Form 7 form names
  • AMP: load your AMP container on the AMP version of your pages
  • Google Consent Mode v2: fire the “default” command with specific consent flags to integrate with non-certified Consent Management Platforms (CMPs) and plugins
  • Cookiebot: use automatic cookie blocking mode if needed
  • Axeptio: load the Axeptio SDK and push every consent change into the data layer
  • CookieYes: push a data layer event whenever the visitor’s consent changes

Server side containers

If you are using a server side container,
you can enter your custom domain name and custom path to load gtm.js from there. Both can be set per container, so you can mix
server side and standard containers on the same site.

Cache-safe data layer

(experimental, off by default)

On sites using a full page cache (LiteSpeed, WP Rocket, Varnish, Cloudflare APO), the HTML generated for one visitor is served
to everyone else as well. Any visitor specific value written into the data layer would therefore leak to other visitors – the
classic example being a page cached while an editor was logged in, then served to anonymous visitors with that editor’s email
address and role still in the data layer.

When this option is enabled, the visitor-specific data layer variables (IP address, logged-in user, store customer and cart) are
left out of cacheable HTML and delivered in the browser instead, under the same names, so your existing Google Tag Manager setup
keeps working. An anonymous page keeps the fixed logged-out values of visitorLoginState and visitorType.

Export & import your settings

You can export all plugin settings into a JSON file and import them on another site, which makes it easy to roll out the same
configuration across several websites. Imported files are treated as untrusted and every value is validated before it is stored.

Server-side events with the Google Data Manager API

(experimental, off by default)

Some signals never reach a browser tag. A refund is issued in the store admin, where no page is loaded and no tag fires, so
Google Analytics keeps counting revenue you have given back. The plugin can send such events from the server through the
Google Data Manager API:

  • Google service accounts: upload the JSON key of a Google Cloud service account, several side by side. Keys are stored encrypted and never shown again.
  • Data Manager destinations: one row per GA4 property, each with a Test button that validates the setup before anything is sent.
  • Attribution capture: each new WooCommerce or EDD order stores the Analytics client and session IDs, the Google Ads click IDs and the consent state it was placed with, so a later server-side event is matched to the right session.
  • Refund events: a refund issued in WooCommerce or EDD is sent to every destination as a GA4 refund event with amount, items, shipping and tax. Google Analytics itself currently processes only the first of several refunds on one order; this is reported to Google.
  • Consent requirement: choose whether orders from the EEA, the UK and Switzerland, every order, or no order need analytics consent before anything is sent.
  • Recent sends: what was sent, what Google did with it, and the reason for every deliberate skip. Failed refunds can be queued again.

Site Health

Tools → Site Health reports the whole plugin: every module’s option states, the containers and their placement, the data
layer name and any wp-config.php overrides in the Info section, plus status tests for the configuration, the Google service
account keys and Data Manager sending. The copied text carries no keys, addresses or visitor data, so it can be pasted into a
support thread as it is.

AI assistants (WordPress Abilities API)

(experimental)

On WordPress 6.9 and newer the plugin registers eleven abilities with the WordPress Abilities API, so an AI assistant
connected through the WordPress MCP Adapter or another client can read the configuration, help work out why an event is
not firing, and change a setting once you have confirmed it. Six abilities are read-only, every one requires the settings
capability, and none returns keys or visitor data. Two filters switch the surface off or keep it read-only.

Exclude specific user roles from being tracked

You can set which user roles need to be excluded from tracking when a user with that role visits the frontend. This will completely disable the container code for that user.

Staging and development sites

The container can be limited to production environments only, so a cloned or staging copy of your site does not send data into
your production Google Tag Manager container. This relies on the WP_ENVIRONMENT_TYPE setting of WordPress.

For developers

Version 2.0 is a complete object oriented rewrite. Every feature is a module, and third party plugins can register their own
modules through the gtm4wp_register_modules action. All public template functions, filter and action names, wp-config constants
and the option storage key of the 1.x versions are unchanged, so existing integrations keep working. A third party module can
report into Site Health and register its own abilities through the same interfaces the built-in modules use.

Installation

  1. Upload duracelltomi-google-tag-manager-for-wordpress to the /wp-content/plugins/ directory
  2. Activate the plugin through the ‘Plugins’ menu in WordPress
  3. Go to Settings / Google Tag Manager and enter your Google Tag Manager container ID and set additional options

FAQ

How can I …

Tutorials for various Google Tag Manager settings and implementation are available on the plugin’s website:
https://gtm4wp.com/setup-gtm4wp-features

PayPal / 3rd party payment gateway transactions in WooCommerce are not being tracked in Google Analytics

PayPal and some other 3rd party payment gateways do not redirect users back to your website after a successful transaction by default.
They offer a route back for your customer, but it can happen that users close the browser before arriving at your thank you page
(also known as the order received page). This means that neither Google Analytics tags nor any other tags have a chance to fire.

Enable auto-return in your payment gateway settings. This will instruct the gateway to show a quick info page after payment
and redirect the user back to your site. This will improve the accuracy and frequency of tracked transactions.

Purchase event is not tracked with WooCommerce

This can happen if you are using a 3rd party plugin that alters the default order received page in a way that does not use
WooCommerce’s integration hooks. Either stop using that plugin, or ask its authors to mimic the behavior of the default order
received page more closely by supporting the woocommerce is_order_received_page function and the woocommerce_thankyou action.

Since version 2.0 the plugin also offers two settings that work around this without changing the 3rd party plugin: “Custom order
received (thank-you) page” fires the purchase event on a bespoke confirmation page, and “Reliable purchase tracking” emits a
missed purchase event on the next page the customer views in the same browser session. Both are de-duplicated, so an order is
never counted twice.

Can the plugin report refunds to Google Analytics?

Yes, since 2.1, from the server: a refund is issued in the store admin where no tag can fire, so the plugin sends a GA4 refund
event through the Google Data Manager API instead. It needs a Google Cloud service account with access to your GA4 property and
refund sending switched on before the order was placed. Note that Google Analytics itself currently processes only the
first of several refunds on one order; this has been reported to Google and needs no plugin change once fixed.

Does the plugin support Easy Digital Downloads?

Yes, since 2.1: Easy Digital Downloads 3.0 and newer gets the same GA4 e-commerce events as WooCommerce, for the classic
shortcodes and the EDD blocks alike, with its own settings section.

Why isn’t there an option to blocklist tag/variable classes

Although Google recommends blocklisting tags and variables using classes, people struggle to know
which tags and variables get affected. Therefore I opted for individual tags and variables rather than classes
on the tag restriction tabs.

Regarding variables: ensure they are not part of any critical tags, as blocklisting such variables will render those tags useless.

How can I track scroll events in Google Tag Manager?

Google Tag Manager supports basic scroll depth tracking based on percentage or pixels natively. Add a Scroll Depth
trigger in your container and use it to fire your Google Analytics 4 and/or Google Ads remarketing/conversion tags.
(The plugin’s own scroll tracking feature was removed in 2.0 in favor of this built-in GTM functionality.)

I use a page cache. Can visitor data leak between visitors?

Yes, this is a real risk with any full page cache, and it is not specific to this plugin: the HTML generated for one visitor is
stored and served to everyone else. If visitor specific values (email address, user role, IP address) are written into the data
layer, the cached copy will contain the values of whoever happened to trigger the caching.

Turn on the “Cache-safe data layer” option to avoid this. With it enabled, the visitor-specific data layer variables are left out
of cacheable HTML and delivered in the browser instead, under the same names.

Why does the plugin load several separate JavaScript files instead of one?

Each tracking feature (WooCommerce, each media player, Contact Form 7, device data, etc.) is its own small
JavaScript file, and the plugin loads only the files a page actually needs – the YouTube tracker, for instance,
loads only on pages that embed a YouTube video, and with the “defer” strategy so it never blocks rendering.
Those files are already minified by the plugin’s build.

Merging several files into one is intentionally left to a caching / performance plugin (WP Rocket, Autoptimize,
LiteSpeed Cache, etc.), which can combine scripts across your whole site and in a way that suits your hosting and
HTTP setup. On modern HTTP/2 hosting, many small conditionally-loaded files usually perform as well as one combined
file. (1.x combined its own scripts; 2.0 delegates this.)

Screenshots

Changelog

The full changelog of every version is on gtm4wp.com: https://gtm4wp.com/changelog

2.1.1

  • Fixed: some sites received an incomplete 2.1.0 package and stopped with a fatal error naming EasyDigitalDownloadsModule. 2.1.1 is the same code as a complete package. A site already showing the error needs the plugin folder removed and the plugin installed again.

2.1.0

  • Changed: for developers, ContainerCode::header_top() always prints its block; the never-used argument that made it return the block instead is gone.
  • Changed: the container loader requests gtm.js over https:// instead of the protocol-relative // form the plugin has emitted since 1.x, matching the snippet Google publishes today. Only a site still served over plain http sees a difference; the <noscript> iframe already used https://.
  • Fixed: the <noscript> part of the container code stays on the page on WordPress 7.2, whose new HTML filter would have removed it. Sites verified in Search Console through Tag Manager rely on this part.
  • Fixed: with the container code placement set to “Off” and no container ID entered, the data layer and the server-side WooCommerce events, purchase included, were not written. “Off” is the data-layer-only setup and needs no container ID, so these sites now get the full data layer.
  • Fixed: the plugin no longer buffers every WooCommerce template part on every page. That buffering only fed the classic “Products” widget, whose tracking had been dead since 2017. If a GTM trigger filters on an item_list_name ending in “(widget)”, remove that condition.
  • Fixed: the description of the WooCommerce “Order data in data layer” setting now says it needs “Track e-commerce” and where orderData appears: the order received page, even for a tracked order, the next page of the reliable purchase fallback without the cache-safe data layer, and theme or builder thank-you pages with the purchase.
  • Fixed: the description of the WooCommerce “Customer data in data layer” setting now names everything it adds: the logged-in customer’s account name and hashed billing email, and the Enhanced Conversions user_data block (hashed email, phone and name, plain billing address) on the purchase event. It also says guests get the customer* variables empty.
  • Fixed: a settings import file with a checkbox written as the text “false” switched that option on; it now means off, as it does when saving the settings screen.
  • Fixed: every REST API request on the site built the plugin’s settings schema, and with WooCommerce that loaded every published page for the custom order received page selector. On sites with many pages and a persistent object cache, this slowed down every request.
  • Fixed: a request to the plugin’s settings REST route from someone without access to the settings is refused as unauthorized before its values are checked, instead of answering with a validation error.
  • Changed: a settings export carries only the plugin’s own options. Keys another plugin wrote into GTM4WP’s option row, and 1.x options not yet cleaned up, are left out; importing the file gives the same settings as before.
  • Fixed: a password-protected WooCommerce product no longer reports view_item or its product data before the password is entered.
  • Fixed: with “Exclude tax” on and the shop showing prices with tax, WooCommerce product (selected variation included), list, add_to_cart and cart prices included tax while the purchase did not. They now use the purchase’s basis, so on such stores an Ads or Meta tag reading add_to_cart values sees prices without tax.
  • Fixed: WooCommerce items the gtm4wp_eec_cart_item or gtm4wp_eec_order_item filter excludes are left out of every event, including remove_from_cart, the block cart and checkout, and Undo. Classic cart and checkout views and the purchase also follow WooCommerce’s own item visibility filters, and server-side refunds leave out the same items.
  • Fixed: a WooCommerce order is flagged as tracked only when its purchase event is really printed, on the order received page, a third-party thank-you page and the reliable purchase fallback alike, so a site filter that breaks the event no longer suppresses the purchase for good.
  • Fixed: WooCommerce add_to_cart and remove_from_cart events now always report value and the item price as numbers, rounded to cents and 0 when a price is missing, on every product, list, cart and block path. Check your GTM setup if a trigger or variable compares value against a string.
  • Fixed: with “Do not flag orders as being tracked” and the cache-safe data layer on, WooCommerce’s “Reliable purchase tracking” could report the same purchase again on later pages. It now has no effect in that combination, as in Easy Digital Downloads.
  • Fixed: page-caching issues in WooCommerce purchase tracking. Details are withheld until the fix reaches every supported version.
  • Fixed: with the cache-safe data layer on, a site filter putting a value JSON cannot encode (such as NAN) into one visitor data field no longer empties the whole response; only that field is left out.
  • Fixed: a site filter returning a non-numeric product price, or something other than an item, order data or purchase array, no longer stops WooCommerce pages with a PHP error or adds an empty item to the data layer. A non-numeric price counts as zero; anything else leaves that item, orderData or purchase out.
  • Fixed: a gtm4wp_compile_datalayer or gtm4wp_visitor_scoped_fields filter callback that returns something other than an array no longer stops WooCommerce pages, pages with tag restrictions, or every page with the cache-safe data layer on, with a PHP error.
  • Fixed: on a site whose address uses non-Latin characters (an internationalised domain), the WooCommerce and Easy Digital Downloads purchase and re-add confirmations from the browser were refused, so orders could be counted again on another device.
  • Fixed: behind a server that reports visitors’ IPv4 addresses in IPv6 form (::ffff:…), visitorIP was left out and the trusted proxy list and the Cloudflare country code did not match.
  • Fixed: the WooCommerce add_to_cart for an item restored with “Undo” now reports the product the cart shows, as the matching remove_from_cart does, for bundle and composite products.
  • Fixed: a Yoast SEO or Rank Math primary category that was deleted or removed from the post is skipped, so pagePrimaryCategory falls back to the next source instead of being left out.
  • Fixed: the user login and registration events could be lost when the first request after logging in was not a page, such as the browser fetching /favicon.ico after a login to wp-admin.
  • Fixed: a Mixcloud show embedded through WordPress reported a malformed URL (https://www.mixcloud.comhttps://…) and a different id than the same show embedded with Mixcloud’s own code.
  • Fixed: the Twitch tracker stopped polling only when the video paused or ended, so a player removed while playing kept its timer running for the rest of the page view.
  • Fixed: device data now names Chrome, Firefox and Edge on iOS, and asks the browser only for the detailed client hints the enabled device data options report.
  • Fixed: with the cache-safe data layer on, siteSearchFrom is cleaned and encoded exactly like the classic data layer, and is empty instead of missing on a search with no referring page, so both report the same value.
  • Fixed: the descriptions of the “Post type”, “Logged in user creation date”, “Site ID”, “Site name” and “Spotify events” settings now say what they report.
  • Changed: Wistia percentage milestones follow the playhead, like every other video provider, instead of the share of the video watched, so seeking ahead now fires the milestones passed.
  • Fixed: with the cache-safe data layer on, an anonymous visitor gets visitorLoginState logged-out and visitorType visitor-logged-out again, in the page’s first data layer push, as with the classic data layer. Logged-in visitors get theirs from gtm4wp.visitorData, so keep them out of anonymous cached pages, where the logged-out values can stay.
  • Changed: device data reports Chrome and Edge instead of Google Chrome and Microsoft Edge, Windows osVersion as 10.0 or 11.0, tablet as a deviceType again, and Samsung Internet, Silk, Yandex Browser and Chrome OS by name instead of as Chrome or nothing, as 1.x did. Update GTM triggers that match the old values.
  • Fixed: when a stored option or another plugin’s module holds a value the settings screen cannot send to the browser, the screen now says so instead of blaming an ad blocker.
  • Fixed: the WooCommerce “Order statuses that trigger the purchase event” description now says that an empty list counts every order except failed ones.
  • Changed: with the cache-safe data layer on, the WooCommerce customer and cart data are re-read only when the cart fragment changed, not on every change to the page.
  • Added: an optional “Output values in the default language” setting (Page variables → Content & engagement data): pageTitle, pageCategory, pageAttributes, pagePostTerms and pagePrimaryCategory report the master language, so Google Analytics combines reports across translations. Needs WPML, Polylang or the gtm4wp_master_language_post_id / gtm4wp_master_language_term_id filters (the three settings below: post filter only). Off by default (experimental). Thanks to @loran750 (#145).
  • Added: an optional “Report products in the default language” setting (WooCommerce → Product data): the whole GA4 item, item_id included, reports the master language, so one product combines across its translations. Review any product feed or dynamic-remarketing setup keyed on the translated id before switching it on. Off by default (experimental) (#145).
  • Added: an optional “Report downloads in the default language” setting (Easy Digital Downloads → Product data), the EDD counterpart of the WooCommerce option above and with the same caveat about setups keyed on the translated item_id. Off by default (experimental) (#145).
  • Added: an optional “Report the form name in the default language” setting (Contact Form 7), so form_name carries the master-language title and submissions of one form combine across languages. Works for forms translated as separate entries. Off by default (experimental) (#145).
  • Changed: pagePostTerms and pagePrimaryCategoryName report term names as they were typed, the same string the e-commerce items have carried since 2.0.2. A GTM trigger that matched the encoded form on either variable needs the plain text now; the slug variables are unchanged.
  • Changed: pagePostTerms is omitted when the post has no terms and no reported meta, instead of being an empty list.
  • Changed: on a single site siteID and siteName carry the site’s own id and name instead of 0 and an empty string, and only the variable whose option is on is reported.
  • Changed: visitorEmail, visitorEmailHash, visitorUsername and visitorRegistrationDate are omitted for a logged-out visitor or an empty value, and visitorIP when no address can be determined. visitorEmailHash is now normalised the way Google matches user-provided data, so it changes for mixed-case and Gmail addresses.
  • Changed: with trusted proxy addresses configured, the Cloudflare country code is read only for requests that arrived through one of them, so add Cloudflare’s IP ranges to the list; one admin notice asks for it while either proxy header is read without one. geoCloudflareCountryCode only ever carries Cloudflare’s two-letter form (plus XX and T1).
  • Changed: a gtm4wp_admin_page_capability callback returning something other than a capability name is reported through _doing_it_wrong() and the default applies instead of locking every administrator out.
  • Fixed: a role given the settings through the gtm4wp_admin_page_capability filter but without manage_options saw only the “settings screen could not start” notice; the screen now loads for them.
  • Changed: the Axeptio project ID field looks up the cookie versions 400 ms after typing stops instead of on every keystroke.
  • Added: a Services for agencies and freelancers section on the settings screen, with no options, introducing the services the developers of GTM4WP offer to agencies and freelancers and linking to them on gtm4wp.com; the link is left out when a site removes the documentation links with gtm4wp_admin_doc_url.
  • Removed: the $gtp4wp_plugin_url, $gtp4wp_plugin_basename and $gtp4wp_script_path globals, deprecated in 2.0 as announced. Third-party code still reading them uses plugin_dir_url( GTM4WP_PLUGIN_FILE ), plugin_basename( GTM4WP_PLUGIN_FILE ) and plugin_dir_url( GTM4WP_PLUGIN_FILE ) . 'build/' instead.
  • Removed: the WebToffee GDPR Cookie Consent (v2.x) integration, deprecated in 2.0. WebToffee v3.x and later connect to Google Tag Manager on their own, so upgrade WebToffee if a site still runs v2.x. The stored setting is deleted on upgrade, and the cookie_consent_update and cookie_consent_<category> events it pushed stop; review GTM triggers built on them.
  • Removed: the “YouTube video events” option, deprecated in 2.0 as announced. Use Google Tag Manager’s built-in YouTube Video trigger with its “Add JavaScript API support to all YouTube videos” setting on, since the plugin no longer adds enablejsapi to YouTube embeds. Triggers on the plugin’s YouTube gtm4wp.media* events stop firing; the gtm4wp_youtube filter is gone too.
  • Removed: orderData.customer.billing.emailhash, deprecated since 1.20. GTM variables still reading it switch to orderData.customer.billing.email_hash, which carries the same value.

Easy Digital Downloads

  • Added: Easy Digital Downloads integration (EDD 3.0+, beta) as its own settings section, covering the classic shortcodes and the EDD blocks with the full GA4 event set from view_item to purchase, deduplicated three ways. The purchase-status default includes Pending for buyers returning from offsite gateways; reliable purchase tracking waits until a pending order is paid.
  • Added: Easy Digital Downloads settings mirroring the WooCommerce ones: orderData in the same key names, persistent list attribution, Enhanced Conversions user_data (phone via EDD’s field or the new gtm4wp_edd_order_phone filter) and reliable purchase tracking; the cache-safe data layer also delivers the customer, the cart and missed purchases. Customer identity reaches only a visitor EDD would show the receipt to.
  • Added: for developers, the Easy Digital Downloads filters gtm4wp_eec_edd_cart_item (cart and checkout rows), gtm4wp_eec_edd_order_item (purchase and refunds), gtm4wp_eec_edd_order_data, gtm4wp_edd_purchase_datalayer, gtm4wp_edd_datalayer_on_pageload and gtm4wp_edd_purchase_trackable_statuses.
  • Added: an admin notice when WooCommerce and Easy Digital Downloads both track e-commerce on one site. Running both stores together is not supported: they share settings the browser trackers read, such as the currency and clearing the ecommerce object, so some events may not be tracked as intended.

Google service accounts

  • Added: a Google service accounts section on the settings screen (experimental): upload, label, test, replace the key of and delete Google Cloud service accounts; the Data Manager destinations authenticate with one. Keys are stored encrypted (needs PHP OpenSSL) and never shown again. Define GTM4WP_ENCRYPTION_KEY in wp-config.php to keep them readable when a security plugin rotates WordPress security keys.

Google Data Manager

  • Added: a Google Data Manager section on the settings screen (experimental), where each destination row names a GA4 property ID, a measurement ID and the service account authenticating to it. A per-row Test button sends a validation-only request, so a missing permission or mistyped ID is reported before anything is saved. Repeated failures raise an admin notice.
  • Added: attribution capture (experimental): while refund sending is on, each new order, whichever checkout or payment gateway created it, stores the Analytics client and session IDs, the Google Ads click IDs and the consent state for matching server-side events. A GA4 tag has to fire in your container. Storing is consent-gated, and gtm4wp_gdm_order_consent overrides the recorded state.
  • Added: server-side refund events (experimental): each store refund is sent to every Data Manager destination as a GA4 refund event, matched by transaction ID and client ID; its value follows the exclude tax/shipping settings in force at purchase. Google Analytics itself processes only the first of several refunds on one order; reported to Google, no update needed once fixed.
  • Changed: the settings screen shows Unsaved changes next to the Save button while anything is waiting, and the browser asks before a tab with unsaved edits is closed or reloaded.
  • Changed: removing a row from a settings table now asks first: the trash icon becomes a Remove/Cancel pair for that row. A row nobody has typed into is still removed straight away.
  • Changed: with “Only output the container on production environments” on, a non-production copy of the site also holds back Google Data Manager refunds, so a staging clone does not send real orders’ refunds to the live property.
  • Added: a Recent sends list under the destinations table: what was sent to Google from the server and what became of it, skips and their reason included, with a switch that hides everything Google applied. Failed or fixable refunds can be sent again, one row or all, and show as queued until the background job runs.
  • Added: a “Require consent before sending” setting (experimental): which orders need analytics storage granted before anything about them is sent. By default, buyers in the EEA (EU territories with their own country code included), the UK and Switzerland, by billing country; or every order, or none. Without consent nothing is sent and the reason is recorded.

Site Health

  • Added: Tools → Site Health reports the whole plugin: option states, containers, placement, data layer name and wp-config overrides (no keys, addresses or visitor data), plus status tests for the configuration, Google service account keys, Data Manager sending and an allowlist blocking every tag; on multisite, who can change the container. Modules report through SiteHealthInfoInterface / SiteHealthTestsInterface.

AI assistants (WordPress Abilities API)

  • Added: the plugin registers abilities with the WordPress Abilities API (WordPress 6.9+; nothing changes below that), so an AI assistant connected through the WordPress MCP Adapter or another client can read the configuration, help work out why tracking is not firing, and change a setting once you have confirmed it. Eleven abilities, six of them read-only, all requiring the settings capability and returning no keys and no visitor data. gtm4wp_abilities_enabled and gtm4wp_abilities_allow_write switch the surface off or keep it read-only. Experimental.
  • Changed: the admin notices about a missing container ID, an incomplete environment configuration, a malformed GTM4WP_HARDCODED_* constant, a visitor IP header with no trusted proxies and an unusable data layer variable name now carry a separate “Open the setting” link after the message. The same checks feed gtm4wp/get-status, so an assistant and the screen report the same problems.

2.0.6

  • Fixed: visitors browsing in the in-app browser of an Android app such as Facebook or Instagram got no WooCommerce data layer, so their purchase and other e-commerce events were missing. Thanks to @sw33tr for the report (#477).
  • Fixed: on the classic cart page, re-adding a removed product with “Undo” now sends add_to_cart. WooCommerce restores it in the background and discarded the page part that carried the event.
  • Fixed: with “Clear ecommerce object before new event” on, the e-commerce events GTM4WP adds as the page loads (view_item, view_cart, begin_checkout, purchase, the cart “Undo” add_to_cart) and the Quick View view_item are now cleared before too, not only the events fired in the browser.
  • Fixed: the plugin conflict notice now calls Google Analytics for WooCommerce by its current name.
  • Fixed: WooCommerce Mini-Cart tracking (remove_from_cart from the Mini-Cart drawer) now loads only on pages that show the Mini-Cart block. Stores using the Cart or Checkout block no longer load the WordPress data scripts on every page, and stores with a classic cart now track removals from a Mini-Cart block too.
  • Fixed: a WooCommerce Product Bundles bundle reported stockstatus as instock in the e-commerce items even when one of its bundled products was out of stock and the bundle could not be bought; it now reports outofstock. Thanks to @KingWehsops for the report (#474).
  • Fixed: a gtm4wp_overwrite_consent_mode_flag filter callback returning the string denied set that consent signal to granted; the filter now also accepts granted and denied.
  • Fixed: a WooCommerce checkout total that is not a finite number no longer breaks the inline checkout script; gtm4wp_checkout_value is null then.
  • Fixed: hardened how the plugin’s REST endpoints answer requests made from other pages.
  • Changed: siteSearchTerm carries the search term as typed; the classic data layer used to HTML-encode it while the cache-safe one did not. A GTM trigger matching the encoded form needs the plain text now.
  • Changed: pageTitle carries the title as the visitor reads it: WordPress’s encoding of ampersands, quotes and dashes is decoded. A GTM trigger matching the encoded form needs the plain text now.
  • Changed: the Contact Form 7 tracker script is no longer loaded while Contact Form 7 is not installed.
  • Changed: for developers, gtm4wp_datalayer_push() returns false for a non-string $js_before/$js_after argument instead of printing Array into the page.
  • Fixed: thank-you pages that show the purchase are now kept out of page caches. The page set as “Custom order received page” is treated the same way WooCommerce treats its own order received page; a thank-you page built by a theme or page builder is excluded from page-cache plugins.
  • Fixed: on a password-protected post, the post meta, word count and reading time variables are left out of the data layer for visitors who have not entered the password.
  • Fixed: when the Contact Form 7 tracker’s settings do not reach the page (for example an optimisation plugin drops inline scripts), it no longer falls back to sending the submitted form values.
  • Fixed: a PHP error when woocommerce_thankyou fired with an id that is not an order, or on a product page whose product could not be loaded.
  • Updated: tested with WooCommerce 11.2.0.

2.0.5

  • Fixed: the data layer initialisation block no longer contains the word gtag. Since 2.0.3, a JavaScript delay plugin with gtag on its keyword list, such as Flying Scripts, delayed the whole block and the browser console showed dataLayer is not defined. The Google tag developer ID is still set.
  • Fixed: a page with no data layer variables to report no longer pushes an empty array into the data layer; dataLayer_content is then an empty object and is not pushed. Content that is pushed is always an object, never an array, which GTM would read as a command.

2.0.1 to 2.0.4

Bug fix releases of the 2.0 line. Their changes are listed in the full changelog: https://gtm4wp.com/changelog#v2-0-4

2.0.0

Major rewrite of the plugin. Please read the announcement post on gtm4wp.com before upgrading. This section is a summary; wordpress.org truncates a changelog after 5,000 words, so the complete list of 2.0.0 changes with every detail lives in the full changelog: https://gtm4wp.com/changelog

  • Changed: complete object-oriented rewrite. Every feature is a module that third-party plugins can extend. All public template functions, filter and action names, wp-config constants and the options storage key are unchanged, so existing integrations keep working.
  • Changed: minimum requirements raised to PHP 8.0 and WordPress 6.3.
  • Added: modern React-based settings screen with left pane navigation, tabbed option groups, option search, inline validation, a help link on every option, bookmarkable addresses and settings export and import.
  • Added: every Google Tag Manager container ID has its own environment parameters, custom domain and custom path; a production-only kill switch for staging copies; validation of the hard-coded wp-config constants with a warning that names the wrong one.
  • Changed: the tag restriction list is written under the documented gtm.allowlist / gtm.blocklist keys, the entity list is refreshed from Google’s documentation, and blocklist mode no longer blocks every tag.
  • Added: cache-safe data layer mode for sites behind a full page cache, with the visitor specific values fetched separately.
  • Changed: GA4 e-commerce tracking reworked for WooCommerce: reliable purchase tracking, custom order received page, order statuses that trigger the purchase event, list attribution across the funnel, block cart and checkout support, Store API data for the block trackers, and numeric-looking text values no longer turned into numbers.
  • Added: an Axeptio consent management platform integration and a CookieYes consent bridge; the WebToffee v2.x integration is deprecated. Media events cover more embedded players, and a player’s script is requested only on pages that contain one of its embeds.
  • Removed: the weather and geo data features and the scroll tracking feature (use the built-in Scroll Depth trigger of Google Tag Manager instead). Browser, OS and device data is now collected in the browser with User-Agent Client Hints, which replaces the bundled WhichBrowser library.
  • Deprecated: the “YouTube video events” option (Google Tag Manager ships a native YouTube Video trigger) and the $gtp4wp_plugin_url, $gtp4wp_plugin_basename and $gtp4wp_script_path global variables, which will be removed in 2.1.

Older releases are listed in the full changelog: https://gtm4wp.com/changelog/1-x