Google Tag Manager
Warning
Our Google Tag Manager compatibility module requires version >=1.3.10 of the Hyvä default theme.
Note
This documentation relates solely to the core Adobe Commerce Google Tag Manager implementation and the Hyvä Enterprise compatibility module for it. It does NOT consider any other Google Tag Manager implementations.
This documentation aims to provide mostly technical insights for the purpose of customising and extending the compatibility module features. Please consult Adobe's official Google Tag Manager documentation for configuration details.
Initialisation
The Hyva_MagentoGoogleTagManager::google_tagmanager_analytics.phtml template is responsible for loading the Google Tag
Manager script and initialising the dataLayer object. Following this, the ga-initialized JavaScript event is
dispatched - which could be considered as the entry point for Google Tag Manager related functions.
Google Tag Manager Events
Banners/Dynamic Blocks
- 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 attempts to locate all banners on the current page before iterating through them, binding a click event listener for tracking customer interactions, and recording their impressions.
Info
It's worth noting that the Adobe Commerce implementation records a banner impression simply by virtue of the fact that it exists on the page, regardless of whether the customer has actually seen it or not.
Cart Activity
Add to Cart
- Block Names:
gtm.cart.addgtm.product.list.addgtm.product.detail.add
- Templates:
Hyva_MagentoGoogleTagManager::cart/add.phtmlHyva_MagentoGoogleTagManager::product/add.phtmlHyva_MagentoGoogleTagManager::product/bundle/add.phtmlHyva_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 theHyva\Theme\ViewModel\ProductPageview model
- This is obtained from the parent
- 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-changedvsconfigurable-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 Cartbutton 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 simply registers an event listened for the cart-item-removed event 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.phtmlHyva_MagentoGoogleTagManager::cart/update.phtmlMagento_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.
Info
Due to the fact that the DOM content is replaced when updating the cart using the Update Shopping Cart button, the
previously bound click event listener will no longer trigger because the button element no longer exists. Therefore,
we need to re-bind the listener so that we can continue to track the customers use of the button.
Checkout
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
Info
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.
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
Info
The product array population is performed by the
Hyva\MagentoGoogleTagManager\ViewModel\GoogleTagManager::getCheckoutItemData() function. A plugin can be used to
modify the set of attributes recorded in the dataLayer.
Product Detail Page Views
- 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.
Info
The array of product attribute data populated in the dataLayer is performed by the
Hyva\MagentoGoogleTagManager\ViewModel\GoogleTagManager::getProductPageData() function. A plugin can be used to
modify the set of attributes tracked.
Product Impressions
- Block Names:
gtm.impressioncrosssell_products_impressionsearch_result_impressionadvanced_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
Info
If the impression script is told that it is being rendered on a category page then it will attempt to use the
category's name when populating the dataLayer. For this reason, category can be considered a special case or
reserved keyword when used as the name of the impression_list argument's inner array argument.
Reference
JavaScript Events
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 initialised.
Layout Arguments
In order to improve extensibility, we have made use of layout XML arguments for values we have anticipated people may wish to change. Additionally, the hope is that, by doing so, we can also reduce the maintenance burden of any such customisations. We have tried to make the purpose of each argument obvious through it's naming however the documentation below should clear up any potential ambiguities.
Banners
| 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
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
Checkout Success
| Name | Type | Default | Purpose | Notes |
|---|---|---|---|---|
event_name |
string | purchase |
GTM event name for purchase events. |
Step Navigation
| Name | Type | Default | Purpose | Notes |
|---|---|---|---|---|
event_name |
string | checkout |
GTM event name for checkout step navigation events. |
Product Detail Page Views
| 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. |
Info
The event_name argument for product detail page views is supported as of version 0.1.1.
Product Impressions
| 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. |
Info
More information about the list name configuration fields can be found in the official Adobe Commerce Google Tag Manager documentation.