GA4 & Google Tag Manager

GA4 ecommerce tracking for Luma and Hyvä: Google Tag Manager or gtag.js, a complete GA4 dataLayer, Google Consent Mode, refunds sent from the server through the Measurement Protocol, and a GTM container you can import in one step. This guide covers installation, every setting and day-to-day use.

• Admin demo: https://demo.softawarecommerce.com/try-admin/ga4-gtm
• Composer access: https://softawarecommerce.com/shop/composer-access/
• Changelog: Release notes · Questions: FAQ

1. Requirements

2. Installation

With Composer. Use the Composer keys from your account on softawarecommerce.com (see https://softawarecommerce.com/shop/composer-access/):

composer config repositories.softaware composer https://repo.softawarecommerce.com
composer config --auth http-basic.repo.softawarecommerce.com PUBLIC_KEY PRIVATE_KEY
composer require softaware/module-ga4-gtm
bin/magento setup:upgrade
bin/magento setup:di:compile            # production mode only
bin/magento setup:static-content:deploy # production mode only
bin/magento cache:flush

To update later: composer update softaware/module-ga4-gtm, then the same bin/magento commands.

Magento cron must run (it sends the refunds). Nothing else is needed on Hyvä: the module ships its own Hyvä layout handles.

3. Quick start with Google Tag Manager

1. Go to Stores > Configuration > Softaware > GA4 & Google Tag Manager (also under Softaware > GA4 & GTM > Settings).
2. General > Enabled = Yes, Tag Type = Google Tag Manager.
3. Enter your GTM Container ID (for example GTM-AB12CDE) and your GA4 Measurement ID (for example G-AB12CD34EF). Save and flush the cache.
4. Open Softaware > GA4 & GTM > GTM Container Export, pick the store view in Settings From and click Download GTM Container JSON.
5. In Google Tag Manager open Admin > Import Container, choose the file, your workspace, Merge and "Rename conflicting tags, triggers and variables". Check the measurement ID in the variable "Const - GA4 Measurement ID", preview the container on your shop, then publish.

With gtag.js instead: set Tag Type = gtag.js (GA4 directly) and the measurement ID; there is no container to import.

4. Settings

All settings are under Stores > Configuration > Softaware > GA4 & Google Tag Manager and can be set per website and per store view.

General

Ecommerce Data

Refunds (Measurement Protocol)

5. The events

How events reach the dataLayer

• Page events (view_item_list, view_item, view_cart, begin_checkout, purchase, search) are printed in the page as JSON and pushed when the page loads.
• Events that belong to the visitor (cart changes, wish list, login, sign-up) are queued on the server and delivered through the private customer-data section softaware-ga4, so they work with the full-page cache.
• Cart changes are detected by comparing each cart line with its stored quantity. An AJAX add and a full page reload are both counted once, and a guest cart merged at login is not counted.
• Every event has an id, and the browser remembers the ids it has already pushed. If a page navigates away before the section response arrives, the next page fetches the section once.
• Purchase is flagged in the table softaware_ga4_order and never output twice for the same order.
• Cart events use the cart's own currency. Lines with a custom price (for example free gifts) are reported at that price, even when it is 0.

To check the events, switch on Debug Mode and open the browser console: every push is logged as [Softaware GA4] <event>. You can also inspect window.dataLayer, or use GTM Preview and GA4 DebugView.

6. Consent

• With Softaware Cookie Consent: the Consent Mode defaults come from that module and are printed before the tag. Nothing else is needed. The GTM <noscript> iframe is left out, because a visitor without JavaScript cannot give consent. With Load Tags = After "Analytics" consent (or Marketing), GTM or gtag.js is loaded only after the visitor accepts that category.
• With another consent tool: set Consent Mode Defaults to Denied until updated if your tool sends gtag('consent', 'update', ...) but does not set the defaults itself, or Do not set if it sets them.
• Without consent requirements: choose Granted (no consent required).

The defaults cover ad_storage, ad_user_data, ad_personalization, analytics_storage, functionality_storage and personalization_storage. The GTM container includes a trigger "CE - softaware_consent_update" and variables for the Softaware Cookie Consent categories, for your own tags that should wait for consent.

7. Refunds

1. Create a GA4 Measurement Protocol API secret (GA4 Admin > Data streams > your web stream).
2. In Refunds (Measurement Protocol) set Send Refunds = Yes and paste the API Secret. The GA4 Measurement ID in General must be set.
3. From then on, every credit memo queues a refund event with the order number as transaction_id, the value, tax, shipping, affiliation and the refunded items. Cron sends queued refunds every five minutes.

The GA client ID and session ID are saved when the order is placed, so GA4 can link the refund to the visitor. If no client ID was available (consent denied, orders created in the admin), a generated one is used: the refund is attributed to the transaction but not to a session. The refund value follows the purchase value settings (tax and shipping), so a full refund cancels the purchase revenue exactly. A failed send is retried up to five times, and a refund is claimed before it is sent, so cron and the CLI cannot send it twice.

8. CLI commands

9. For developers

• Push your own events in the browser: window.swGa4.push('event_name', {currency: 'GBP', value: 10, items: [...]}).
• Queue an event on the server (delivered on the next section load): Softaware\Ga4\Model\EventQueue::add($event, $params).
• Register a product list for view_item_list and select_item: Softaware\Ga4\Model\ListRegistry::add($id, $name, $products).
• Add page events: implement Softaware\Ga4\Api\PageEventProviderInterface and add it to the providers argument of the block softaware.ga4.datalayer in a layout handle.
• Build items: Softaware\Ga4\Model\ItemBuilder::fromProduct(), fromQuoteItem(), fromOrderItem().

10. Permissions (ACL)

Under System > Permissions > User Roles > Role Resources > Softaware > GA4 & GTM:

11. Troubleshooting

• No events in the dataLayer: check Enabled for the store view, the container or measurement ID, and flush the cache. With Load Tags set to an "after consent" option, nothing loads until the visitor accepts that category.
• Events in the dataLayer but not in GA4: with GTM, the container must be published and contain the GA4 tags (import the export file). Use GTM Preview and GA4 DebugView with Debug Mode = Yes.
• No add_shipping_info or add_payment_info: these are implemented for the Magento (Luma) checkout. A one-step checkout needs an adapter that calls window.swGa4.push(). add_payment_info also fires for a method the checkout pre-selects.
• A CMS product widget sends no view_item_list: its block HTML is cached, so these lists are not reported.
• Refunds are not arriving: check Send Refunds, the API secret and the measurement ID, make sure Magento cron runs, then run bin/magento softaware:ga4:refunds to see the queue and its last error. --dry-run shows the payload.
• Enhanced conversions without phone numbers: Google requires E.164, so phone numbers are only sent when stored in international format (+44...).

12. Uninstall

bin/magento module:disable Softaware_Ga4
composer remove softaware/module-ga4-gtm
bin/magento setup:upgrade
bin/magento cache:flush

Then remove the imported tags from your GTM container if you no longer need them. The tables softaware_ga4_order and softaware_ga4_refund can be dropped once the module is removed.