How Gatemi GA4 Works

Three rules shape the plugin.

  1. A purchase is reported once per order. The purchase event is what GA4 computes revenue and return on ad spend from. A duplicate is a doubled conversion, and a merchant who sees it may raise a bid on it.
  2. Consent Mode defaults run before the tag, or they mean nothing. A default declared after the tag has loaded is a default for a tag that has already fired.
  3. Every event is built in one place. WooCommerce's classic checkout and its Checkout block are two different code paths. A plugin that builds a payload for each can report two different shapes for the same order. Here one class, GMGA_Events, builds every payload, and the one small storefront script builds none of its own.

Nothing without an id

Until a valid id for the chosen mode is saved, the plugin prints nothing on the storefront: no tag, no dataLayer, no script. An empty container would be a request every visitor pays for and nobody reads.

When Declare Consent Mode v2 defaults is on, the plugin adds this before anything from Google:

gtag('consent','default',{"ad_storage":"denied","ad_user_data":"denied",
"ad_personalization":"denied","analytics_storage":"denied",
"functionality_storage":"granted","security_storage":"granted"});

The order is guaranteed by WordPress itself, not by hook priorities. The defaults are attached to a script handle called gmga-consent, and both the gtag.js handle (gmga-gtag) and the Tag Manager handle (gmga-gtm) are registered as depending on it. WordPress always prints a dependency first, however the queue is reordered.

The plugin never shows a consent banner. It sets the defaults and stands back. Your consent plugin updates them with gtag('consent','update', …) when the visitor chooses. Two banners on one shop means the wrong one is in charge.

The tag

  • GA4 — gtag.js from www.googletagmanager.com, loaded async in the head, with gtag('js', …) and gtag('config', 'G-…') attached.
  • Tag Manager — Google's container loader, attached to the gmga-gtm handle in the head, and Tag Manager's <noscript> iframe printed on wp_body_open (your theme must call wp_body_open(), as current themes do).

Every snippet goes through WordPress's script functions; the plugin prints no raw <script> tags.

When each event is sent

Every event is pushed onto the dataLayer as:

dataLayer.push({ ecommerce: null });
dataLayer.push({ event: "begin_checkout", ecommerce: { … } });

The first line clears the previous ecommerce object, which is Google's recommended pattern.

Event When Built from
view_item A single product page loads The product
add_to_cart An item is added without a page load (see below) The product's own payload
view_cart The cart page loads The cart as it stands
begin_checkout The checkout page loads with something in the cart (not the order-received or order-pay page) The cart as it stands
purchase The order-received page, once per order, unless the order failed or was cancelled The order

view_item, view_cart and begin_checkout are printed in the page footer. begin_checkout is printed on the checkout page itself rather than on a classic-only hook, so the classic checkout and the Checkout block both report it in the same shape.

add_to_cart

Adding to the cart without a page load happens on two paths, and the plugin's script, events.js, listens to both:

  • Classic AJAX add — WooCommerce's added_to_cart jQuery event, fired by shop-page buttons. The payload is read from the button's data-gmga-item attribute, which the plugin adds through woocommerce_loop_add_to_cart_args.
  • Blocks / Store API add — the wc-blocks_added_to_cart browser event.

The payload is always built in PHP and hung on the page, never built in the script. Points to know in version 1.0.0:

  • The payload carries a quantity of 1.
  • The Blocks event names no product, so the script reads the payload off the button the shopper pressed (or, on a product page, the marker in the same form). Where it cannot tell which product was added, it sends nothing rather than guess.
  • WooCommerce's Mini-Cart, Cart and Product button blocks re-announce every classic add as a Blocks add. The script counts that as one add, not two.
  • A classic single product page that adds to the cart by submitting the form (a full page load) sends no add_to_cart.

Not sent in version 1.0.0

view_item_list and remove_from_cart appear in the plugin's list of event names and on the settings screen, and a builder for view_item_list exists, but nothing in this version sends either event.

The item

Every item in every event has the same shape:

{
  "item_id": "HOODIE-BLUE",
  "item_name": "Hoodie - Blue",
  "price": 45,
  "quantity": 1,
  "item_category": "Clothing",
  "item_category2": "Hoodies"
}
  • item_id is the SKU, or the product id when there is no SKU.
  • Up to five categories are sent as item_category … item_category5. A variation takes its parent product's categories.

The purchase, once

On the order-received page WooCommerce resolves the order from the URL's order id and order key, and hands it to the woocommerce_thankyou hook. The plugin uses that order; it never reads the order id from the query string itself. An order id is a guessable number, and a plugin that trusted one could report a stranger's basket as your conversion.

Then:

  1. If the order's status is Failed or Cancelled, nothing is sent and nothing is marked. WooCommerce shows the order-received page for a declined payment too; the purchase is reported when the customer pays the order and comes back to that page.
  2. If the order already carries _gmga_tracked, nothing is sent.
  3. Otherwise the plugin writes _gmga_tracked (the time, in UTC) on the order and saves the order.
  4. Only then is the purchase event added to the page.

Refreshing the order-received page — the commonest cause of doubled conversions — finds the mark and sends nothing. The transaction_id is the order number (what you see in WooCommerce → Orders), which GA4 also uses to discard duplicates.

The purchase payload:

Field Value
transaction_id The order number
currency The order's currency
value Gross or net, per the setting
tax, shipping Always sent
coupon The first coupon code, when one was used
items One per line, priced at what was actually charged per unit

Because the order is marked before the event reaches the browser, a visitor who closes the page before Google's script runs — or whose consent blocks storage — is not retried on a later visit. Reporting once is the rule.

What the plugin stores

  • The option gmga_settings.
  • _gmga_tracked on each order whose purchase was reported.

Uninstalling deletes the option and keeps _gmga_tracked, so a later reinstall does not report every past order again.

Shopping Cart
Scroll to Top