Google Tag Manager Integration for Hyvä Enterprise

The Hyvä Enterprise Google Tag Manager (GTM) compatibility module provides full e-commerce tracking integration between Adobe Commerce's native GTM implementation and Hyvä-based storefronts. This module tracks customer interactions including product impressions, cart activity, checkout steps, and purchases—pushing all event data to the GTM dataLayer for analytics processing.

Compatibility and Scope

Hyvä Theme version requirement

The Google Tag Manager compatibility module requires Hyvä default theme version >=1.3.10.

Adobe Commerce GTM only

This documentation covers only the core Adobe Commerce Google Tag Manager implementation and its Hyvä Enterprise compatibility module. Third-party GTM implementations are not covered here.

For GTM configuration in the Adobe Commerce admin panel, consult Adobe's official Google Tag Manager documentation.

Architecture Overview

The GTM integration consists of templates that handle specific tracking scenarios. Each template listens for user interactions or page events and pushes structured data to the dataLayer. The module uses layout XML arguments for configuration, making customizations possible without template overrides.

Key components:

• Initialization template: Loads the GTM script and initializes the dataLayer
• Event templates: Track specific interactions (cart, checkout, impressions)
• View model: Provides product and order data formatting via Hyva\MagentoGoogleTagManager\ViewModel\GoogleTagManager

Initialisation

The Hyva_MagentoGoogleTagManager::google_tagmanager_analytics.phtml template is responsible for loading the Google Tag Manager script and initializing the dataLayer object. Once initialization completes, the template dispatches the ga-initialized JavaScript event, which serves as the entry point for all subsequent GTM tracking functions.

Google Tag Manager Events

The following sections document each event type tracked by the GTM compatibility module. Each event includes the block name, template file, and available layout arguments for customization.

Banner / Dynamic Block Tracking

• Block Name: gtm.banner
• Template: Hyva_MagentoGoogleTagManager::banner.phtml
• Layout Arguments

A single script is used for handling both banner impressions and interactions. Given the possibility for banners to be present on any page, the script is included on every page. Once Google Tag Manager has been initialised, the script iterates through all banners on the current page, binding a click event listener for tracking customer interactions, and recording their impressions.

Banner impression behavior

The Adobe Commerce implementation records a banner impression when the banner exists on the page, regardless of whether the customer has actually viewed it (no viewport visibility check).

Cart Activity Tracking

Cart activity tracking monitors all cart modifications including adding products, removing products, updating quantities, and clearing the cart. These events are tracked through a combination of click handlers and custom JavaScript events.

Add to Cart

• Block Names:
• gtm.cart.add
• gtm.product.list.add
• gtm.product.detail.add
• Templates:
• Hyva_MagentoGoogleTagManager::cart/add.phtml
• Hyva_MagentoGoogleTagManager::product/add.phtml
• Hyva_MagentoGoogleTagManager::product/bundle/add.phtml
• Hyva_MagentoGoogleTagManager::product/grouped/add.phtml
• Layout Arguments

Add to cart events are tracked using the cart-item-added event whose listener is defined in the Hyva_MagentoGoogleTagManager::cart/add.phtml template and expects the event's detail object to be an array of products, even if only a single product is being added. The other templates noted above will dispatch this event when the customer attempts to add a product to their cart.

The Hyva_MagentoGoogleTagManager::product/add.phtml template is the generic template for handling the customer's intent to add a product to their cart, whether from a product listing page or a product detail page.

Product Detail Pages vs Product Listing Pages

A simple layout argument is used to flag whether the event is being triggered on a product detail page or not. The value of this flag dictates the behaviour of the template. When the flag is set to false, which is the default value, the template will do the following things differently:

• Fetching the product object
• This is obtained from the parent <block>, rather than from the Hyva\Theme\ViewModel\ProductPage view model
• Checking whether the product has any required custom options, invoking an early return if it does
• Defining an event listener for when the customer selects a different configurable product option
• Which is used to track the SKU of the product being added to the cart
• listing-configurable-selection-changed vs configurable-selection-changed
• Defining a selector for the product price element
• Fetching the quantity of the product being added to the cart
• Minimum sale quantity vs input element value
• Defining the action which triggers the event to be tracked
• Add to Cart button click vs product form submission

Bundle Product Pages

Due to potential for bundle products to have a dynamic price and/or a dynamic SKU, the gtm.product.detail.add block uses a different template on these product detail pages to ensure the correct values are tracked in the dataLayer.

Grouped Product Pages

Similarly to bundle product pages, a different template is also used for grouped product pages to ensure each of the individual products within the group are tracked in the dataLayer.

Emptying the Cart

• Block Name: gtm.cart.empty
• Template: Hyva_MagentoGoogleTagManager::cart/empty.phtml
• Layout Arguments

When the customer uses the Clear Shopping Cart button, the cart-item-removed event is dispatched and populated with the array of products being removed from the cart.

Info

The product array population is performed by the Hyva\MagentoGoogleTagManager\ViewModel\GoogleTagManager::getCartItemData() function. A plugin can be used to modify the set of attributes recorded in the dataLayer.

Remove from Cart

• Block Name: gtm.cart.remove
• Template: Hyva_MagentoGoogleTagManager::cart/remove.phtml
• Layout Arguments

This template registers an event listened for the cart-item-removed event and populates the dataLayer with the list of products being removed from the cart - even if only a single product is being removed.

This event is dispatched in:

• Hyva_MagentoGoogleTagManager::cart/empty.phtml
• Hyva_MagentoGoogleTagManager::cart/update.phtml
• Magento_Checkout/templates/php-cart/item/renderer/actions/remove.phtml (in the default theme)
• Magento_Theme/templates/html/cart/cart-drawer.phtml (in the default theme)

Updating the Cart

• Block Name: gtm.cart.update
• Template: Hyva_MagentoGoogleTagManager::cart/update.phtml
• Layout Arguments

This script binds a click event handler to the Update Shopping Cart button on the cart page. When clicked, the script will iterate through each of the products in the cart, check whether their quantity has been updated, and then dispatch either thecart-item-added event or the cart-item-removed event as appropriate, populating the event with the product information as required.

DOM replacement handling

When the cart page updates via the "Update Shopping Cart" button, the DOM content is replaced and previously bound click event listeners are lost. The GTM module automatically re-binds the listener after DOM replacement to maintain tracking continuity.

Checkout Tracking

Checkout tracking captures the customer's progression through checkout steps and records purchase completion. These events integrate with Hyvä Checkout's navigation system to track step transitions.

Checkout Success

• Block Name: gtm.checkout.success
• Template: Hyva_EnterpriseCheckout::checkout/success.phtml
• Layout Arguments

When the customer successfully places their order and is navigated to the checkout success page, the dataLayer is populated with the following data:

• Order ID
• Order Grand Total
• Tax Paid
• Shipping Costs
• Discount Code Applied
• Products Purchased

Customizing checkout item data

The product array population is performed by the Hyva\MagentoGoogleTagManager\ViewModel\GoogleTagManager::getOrderItemData() function. A plugin can be used to modify the set of attributes recorded in the dataLayer.

Checkout Step Navigation

• Block Name: checkout.gtm.navigator
• Template: Hyva_EnterpriseCheckout::checkout/gtm/navigator.phtml
• Layout Arguments

This script defines an event listener for the Hyvä Checkout's checkout:step:loaded event and populates the dataLayer with the

• Step Name
• Step Position
• Products in Cart

Customizing checkout item data

Product array population uses Hyva\MagentoGoogleTagManager\ViewModel\GoogleTagManager::getCheckoutItemData(). Create a plugin on this method to modify the attributes recorded in the dataLayer.

Product Detail Page Tracking

• Block Name: product_view_detail
• Template: Hyva_EnterpriseCheckout::detailproduct.phtml
• Layout Arguments

This script is responsible for tracking when the customer navigates to a product detail page.

Customizing product page data

Product attribute data uses Hyva\MagentoGoogleTagManager\ViewModel\GoogleTagManager::getProductPageData(). Create a plugin on this method to modify the tracked attributes.

Product List Impressions and Clicks

• Block Names:
• gtm.impression
• crosssell_products_impression
• search_result_impression
• advanced_result_impression
• Template: Hyva_EnterpriseCheckout::impression.phtml
• Layout Arguments

This script is responsible for locating product list elements, recording the products within them as impressions, and binding click event handlers for each of them so the customer's interaction with them can be tracked. The list types supported out of the box are:

• Category Pages
• Search Result Pages
• Advanced Search Result Pages
• Cross-sell Products
• Related Products
• Upsell Products

Category page special handling

When the impression script renders on a category page, it uses the category name when populating the dataLayer. The keyword category is reserved for this purpose in the impression_list argument configuration.

Reference

This section provides technical reference information for JavaScript events and layout XML arguments used by the GTM compatibility module.

JavaScript Events

The GTM module dispatches and listens for the following custom JavaScript events. Use these events to integrate custom tracking or extend the module's functionality.

cart-item-added

Dispatched when the customer attempts to add products to their cart or increases the quantity of a product already in their cart.

cart-item-removed

Dispatched when the customer attempts to remove products to their cart or reduces the quantity of a product in their cart.

ga-initialized

Dispatched once the Google Tag Manager script has been loaded and the dataLayer object has been initialized. Listen for this event to execute code that depends on GTM being ready.

Layout Arguments

The GTM module uses layout XML arguments for configurable values, enabling customization without template overrides. Override these arguments in your theme's layout XML to change event names, selectors, or behavior flags.

Banner Arguments

The following arguments configure banner impression and click tracking:

Name	Type	Default	Purpose	Notes
impression_event_name	string	promotionView	GTM event name for banner impressions.
click_event_name	string	promotionClick	GTM event name for banner interactions i.e. when a customer clicks a banner.
banner_selector	string	[data-banner-id]	Query selector to find all banners on the page.	Used as an argument for document.querySelectorAll(). The script is not rendered when this argument is missing or empty.

Cart Activity Arguments

The following arguments configure cart-related event tracking including add to cart, remove from cart, and quantity updates.

Add to Cart

Name	Type	Default	Purpose	Notes
event_name	string	addToCart	GTM event name for add to cart events.
button_selector	string	button[data-addto="cart"]	Sub-selector for the product list page product form's Add to Cart button.	Used as an argument for document.querySelector().
skip_product_types	array	bundle, giftcard, grouped	List of product types that cannot be added to cart directly from product listing pages.	These product types require further customer input to select options or quantities etc. The array keys must match the product type code and the value is a boolean true or false as to whether the product type should be skipped or not.
is_product_page	boolean	false	A simple flag to inform the template whether it is on the product detail page or not.

Emptying the Cart

Name	Type	Default	Purpose	Notes
event_name	string	removeFromCart	GTM event name for remove from cart events.
button_selector	string	#empty_cart_button	Selector for the Clear Shopping Cart button.	Used as an argument for document.querySelector().

Remove from Cart

Name	Type	Default	Purpose	Notes
event_name	string	removeFromCart	GTM event name for remove from cart events.

Updating the Cart

Name	Type	Default	Purpose	Notes
button_selector	string	button[name="update_cart_action"]	Selector for the Update Shopping Cart button.	The script is not rendered when this argument is missing or empty.
cart_item_selector	string	#shopping-cart-table tbody	Selector for the cart item rows in the cart page table.	Used as an argument for document.querySelectorAll().
cart_item_qty_selector	string	[data-role="cart-item-qty"]	Sub-selector for the cart item quantity input within each table row.	Used as an argument for element.querySelector().

Checkout Arguments

The following arguments configure checkout-related event tracking including step navigation and purchase completion.

Checkout Success

Name	Type	Default	Purpose	Notes
event_name	string	purchase	GTM event name for purchase events.

Checkout Step Navigation

Name	Type	Default	Purpose	Notes
event_name	string	checkout	GTM event name for checkout step navigation events.

Product Detail Page Arguments

The following arguments configure product detail page view tracking:

Name	Type	Default	Purpose	Notes
event_name	string	productDetail	GTM event name for product detail page views.
show_category	boolean	true	Flag whether to include the name of the category the product belongs to.	When true, the Hyva\MagentoGoogleTagManager\ViewModel\GoogleTagManager view model will use the Magento\GoogleTagManager\Block\ListJson::getCurrentCategory() function from the core Adobe Commerce implementation to attempt to populate the category name. Internally, Adobe uses the current_category registry key to get this data so its value may be missing if Magento has not loaded any of the categories the product belongs to.

Version note

The event_name argument for product detail page views is supported as of version 0.1.1.

Product Impression Arguments

The following arguments configure product list impression and click tracking. These arguments control how the module identifies product elements and tracks customer interactions with product listings:

Name	Type	Default	Purpose	Notes
impression_event_name	string	productImpression	GTM event name for product impressions.
click_event_name	string	productClick	GTM event name for product list click events.
click_selector	string	a	Sub-selector for product list element links that trigger click events. See product_selector below.	Used as an argument for element.querySelectorAll().
impression_list	array		Map system config values for list names and define selectors for product elements within a given list.	The script is not rendered when this argument is missing or empty. Each item within this argument is itself an array, though its name is largely irrelevant.
product_selector	string		Selector for product elements within the given list.	This argument is a child of the impression_list argument's inner array. It's value is used as an argument for document.querySelectorAll().
list_name	string		List type name which maps to a system configuration value.	This argument is a child of the impression_list argument's inner array. It's value is used as a lookup for the Hyva\MagentoGoogleTagManager\ViewModel\GoogleTagManager view model's listTypeConfigMap property, whose arguments are defined in di.xml.

List name configuration

For more information about the list name configuration fields, see the official Adobe Commerce Google Tag Manager documentation.

Common Customization Patterns

The GTM module provides several extension points for customizing tracked data. The most common customization patterns use plugins on the view model methods.

Modifying Product Data Attributes

To add, remove, or modify the product attributes tracked in the dataLayer, create a plugin on the appropriate method of Hyva\MagentoGoogleTagManager\ViewModel\GoogleTagManager:

Data Type	View Model Method	Use Case
Cart items	getCartItemData()	Modify attributes when adding/removing cart items
Order items	getOrderItemData()	Modify attributes on checkout success
Checkout items	getCheckoutItemData()	Modify attributes during checkout step navigation
Product page	getProductPageData()	Modify attributes on product detail pages

Overriding Layout Arguments

To change event names or selectors without modifying templates, override the layout XML arguments in your theme:

Example: Change add-to-cart event name

<referenceBlock name="gtm.cart.add">
    <arguments>
        <argument name="event_name" xsi:type="string">custom_add_to_cart</argument>
    </arguments>
</referenceBlock>