Gatemi GA4 Developer Reference

Classic WordPress code: four GMGA_* classes in includes/ — GMGA_Settings, GMGA_Events (every payload), GMGA_Tags (everything on the page) and GMGA_Admin — plus one script, assets/js/events.js. No HTTP from PHP, no database tables, no storefront stylesheet. Constants GMGA_VERSION, GMGA_FILE, GMGA_PATH, GMGA_URL. Text domain gatemi-ga4.

Filters

gmga_consent_defaults

The Consent Mode state declared before the tag.

Argument Type
$defaults array<string,string> — signal ⇒ granted / denied
// Wait half a second for the consent banner before tags fire.
add_filter( 'gmga_consent_defaults', function ( $d ) {
	$d['wait_for_update'] = 500;
	return $d;
} );

Only applied when Declare Consent Mode v2 defaults is on.

gmga_item

One product as a GA4 item, in every event.

Argument Type
$item array — item_id, item_name, price, quantity, item_category…
$product WC_Product
// Add the brand.
add_filter( 'gmga_item', function ( $item, $product ) {
	$item['item_brand'] = 'Acme';
	return $item;
}, 10, 2 );

gmga_purchase

The purchase payload before it is printed.

Argument Type
$payload array — transaction_id, currency, value, tax, shipping, items, optional coupon
$order WC_Order

gmga_event

Any server-built event before it is printed. Return an empty array to hold it back.

Argument Type
$payload array — the ecommerce object
$name string — the event name
// No begin_checkout for logged-in staff.
add_filter( 'gmga_event', function ( $payload, $name ) {
	return ( 'begin_checkout' === $name && current_user_can( 'manage_woocommerce' ) ) ? array() : $payload;
}, 10, 2 );

gmga_event applies to view_item, view_cart, begin_checkout and purchase. add_to_cart is pushed by events.js from the payload PHP hung on the page; that payload has already passed gmga_item.

Note that the _gmga_tracked claim is written before gmga_event runs, so holding back a purchase with this filter does not let it be sent later.

The plugin fires no actions of its own.

Option

Option Keys and defaults
gmga_settings mode 'ga4' (ga4 / gtm / both), measurement_id '', container_id '', net_value 'no', consent_mode 'yes'

Ids must match ^G-[A-Z0-9]{4,20}$ and ^GTM-[A-Z0-9]{4,20}$.

Order meta

Key Holds
_gmga_tracked UTC time (Y-m-d H:i:s) the purchase was reported

Kept on uninstall. To let an order be reported again (for testing), delete it:

$order = wc_get_order( 123 );
$order->delete_meta_data( '_gmga_tracked' );
$order->save();

Script handles

Handle Source Depends on Where
gmga-consent none (inline consent defaults) — head
gmga-gtag https://www.googletagmanager.com/gtag/js?id=…, async gmga-consent head
gmga-gtm none (inline Tag Manager loader) gmga-consent head
gmga-events assets/js/events.js; server events attached inline before it — footer

All four are enqueued on wp_enqueue_scripts, only when a valid id is saved. Page events are attached on wp_footer at priority 5, before WordPress prints footer scripts.

WooCommerce and WordPress hooks used

Hook Use
wp_body_open Tag Manager <noscript> iframe
wp_footer (5) view_item, view_cart, begin_checkout
woocommerce_loop_add_to_cart_args (20) Adds data-gmga-item to shop-page buttons
woocommerce_after_add_to_cart_button Prints <span hidden data-gmga-item="…"> on product pages
woocommerce_thankyou (20) Claims and prints purchase
before_woocommerce_init HPOS and Cart & Checkout Blocks compatibility

Browser events listened for

Event Path
added_to_cart (jQuery, on document.body) Classic AJAX add-to-cart
wc-blocks_added_to_cart (DOM, on document.body) Blocks / Store API add-to-cart

dataLayer shape

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: "purchase",
  ecommerce: {
    transaction_id: "1042",
    currency: "GBP",
    value: 45,
    tax: 6.67,
    shipping: 5,
    coupon: "SPRING",
    items: [ { item_id: "MUG-B", item_name: "Mug", price: 20, quantity: 2, item_category: "Kitchen" } ]
  }
});

Admin

  • WooCommerce → GA4, slug gmga-settings, capability manage_woocommerce, nonce gmga_save_settings, posted as gmga[…].
  • Stylesheet gmga-admin on that screen only.

Uninstall

uninstall.php deletes gmga_settings only.

Shopping Cart
Scroll to Top