Extends Google Analytics 4 by including custom data for enhanced GA4 analytics. Supports GA4 loaded directly via
gtag.jsor through a Google Tag Manager container.
- User Properties: Sets
is_subscriber(0 or 1) on all pages. - Post Data: On single post pages, outputs
post_author,post_category, andpost_tags. - Two loading modes:
- GTM mode (2.0): when a GTM container ID is set, the plugin pushes the data to
window.dataLayerbefore the container loads and outputs the GTM container snippet (head script +<noscript>body fallback). GA4 itself is configured inside the container. - Direct mode: when only a GA4 Measurement ID is set, the plugin loads
gtag.jsdirectly and passes the data viagtag('config', …)— unchanged from 1.0.
- GTM mode (2.0): when a GTM container ID is set, the plugin pushes the data to
When both are set, GTM supersedes direct GA4: the direct gtag.js output is disabled to avoid double-counting, and the GA4 ID field is shown disabled in the admin (its stored value is preserved).
In your WordPress dashboard, go to Settings → General:
- Google Analytics loaded through GTM ID — enter the GTM container ID (e.g.,
GTM-XXXXXXX) when GA4 is loaded through Tag Manager. The GA4 Measurement ID (G-XXXXXXX) is then entered inside the GTM container's Google tag, not in the plugin. - Google Analytics 4 ID — enter the GA4 Measurement ID (e.g.,
G-XXXXXXX) for the directgtag.jsmode. Disabled while a GTM ID is set.
Click Save Changes.
<script>
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
is_subscriber: 0,
post_author: "dev",
post_category: "news",
post_tags: "featured",
});
</script>
<script>
(function (w, d, s, l, i) {
/* standard GTM loader */
})(window, document, "script", "dataLayer", "GTM-XXXXXXX");
</script>
...
<body>
<noscript
><iframe
src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX"
height="0"
width="0"
style="display:none;visibility:hidden"
></iframe
></noscript>
</body>The payload push is hooked at wp_head priority 1 so the values exist at GTM's Initialization event.
The <noscript> fallback is hooked on the wp_body_open action, so the active theme must call wp_body_open() immediately after its opening <body> tag (a WordPress 5.2+ theme standard). Without it, the head container still loads but the <noscript> iframe is omitted.
<script id="ga4-ext-gtagjs-js-before">
window.dataLayer = window.dataLayer || [];
function gtag() {
dataLayer.push(arguments);
}
gtag("set", "linker", {
domains: ["example.com"],
});
gtag("js", new Date());
gtag("set", "user_properties", {
is_subscriber: 0,
});
gtag("config", "G-1234", {
post_author: "dev",
post_category: "news",
post_tags: "featured",
});
</script>
<script
src="https://www.googletagmanager.com/gtag/js?id=G-1234"
id="ga4-ext-gtagjs-js"
defer
data-wp-strategy="defer"
></script>Suppresses the plugin's GTM container output (head script + <noscript>) while keeping the dataLayer push. Use when the site already loads the GTM container elsewhere (e.g., in a theme):
add_filter( 'ga4_ext_render_gtm_container', '__return_false' );Signature: apply_filters( 'ga4_ext_render_gtm_container', bool $render, string $gtm_id ).
The plugin only makes the values available on window.dataLayer; they must be mapped inside the GTM container or the GA4 dimensions report "(not set)"/"unknown". All names must match the dataLayer keys exactly (case-sensitive). Here's how you can set it up:
- Prerequisite: the GA4 custom dimensions must be registered in the GA4 property first — see Google Analytics 4 - Configure Custom Dimensions below. This applies in GTM mode too: GTM only forwards the values; GA4 ignores them until matching dimensions are registered.
- In Google Tag Manager, open the site's container and go to Variables → User-Defined Variables → New. Create four variables of type Data Layer Variable (Data Layer Version 2, no default value), with these exact Data Layer Variable Names:
post_author,post_category,post_tags,is_subscriber. - Open the Google tag (the tag holding the
G-XXXXXXXmeasurement ID; create it if missing): a. Add event parameters:post_author,post_category,post_tags, each mapped to its Data Layer Variable from step 2. b. Add a user property:is_subscriber, mapped to its Data Layer Variable. c. Set the trigger to Initialization - All Pages, so the values attach to the automaticpage_view. - Optional: configure cross-domain linking in the Google tag settings if the GA4 property spans multiple domains. Replaces the direct mode's
gtag('set', 'linker', …). - Use Preview (Tag Assistant) on a single post page to verify the four variables resolve with values at the Initialization event, then Publish the container.
To use the custom data in Google Analytics 4, you need to register custom dimensions in the GA4 dashboard (required for both modes). Here's how you can set it up:
- Navigate to Google Analytics and sign in with your account credentials with an Administrative role.
- Select the property you want to track.
- Access the Admin Panel - Click the Admin gear icon located in the bottom-left corner of the interface.
- In the Data display section, click on
Custom definitions. - For each event-scoped custom dimension (post_author, post_category, post_tags), follow these steps: a. Click Create Custom Dimension. b. Dimension Name: Post XXX (e.g., Post Author) c. Scope: Event d. Event Parameter: post_author e. Click Save.
- For
is_subscriber, create a user-scoped custom dimension (Scope: User, User Property:is_subscriber).
- WordPress: Version 6.5 or higher.
- PHP: Version 8.1 or higher.
This plugin is licensed under GPL-3.0-or-later.