Three rules shape the plugin.
- 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.
- 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.
- 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.
Consent Mode
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, loadedasyncin the head, withgtag('js', …)andgtag('config', 'G-…')attached. - Tag Manager — Google's container loader, attached to the
gmga-gtmhandle in the head, and Tag Manager's<noscript>iframe printed onwp_body_open(your theme must callwp_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_cartjQuery event, fired by shop-page buttons. The payload is read from the button'sdata-gmga-itemattribute, which the plugin adds throughwoocommerce_loop_add_to_cart_args. - Blocks / Store API add — the
wc-blocks_added_to_cartbrowser 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_idis 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:
- 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.
- If the order already carries
_gmga_tracked, nothing is sent. - Otherwise the plugin writes
_gmga_tracked(the time, in UTC) on the order and saves the order. - Only then is the
purchaseevent 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_trackedon 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.
