Installation and configuration guide

Requirements

• Magento Open Source / Adobe Commerce 2.4.x.
• PHP compatible with the Magento version in use.
• Composer access to the module private repository.
• kowal/base module.
• Optional: Kowal_CookieConsent, if the store uses it for GTM and Consent Mode.

Installation via Composer

composer config repositories.kowal-datalayer vcs composer require kowal/module-datalayerphp bin/magento module:enable Kowal_DataLayerphp bin/magento setup:upgradephp bin/magento cache:flush

In a production environment, if required by the project, perform the standard Magento deployment:

php bin/magento setup:di:compilephp bin/magento setup:static-content:deployphp bin/magento cache:flush

Basic configuration

Admin panel:

Stores > Configuration > Kowal > Kowal Data Layer

Menu:

kowal.store > Modules > Data Layer > Settings

General

1. Enable Module - enable the module for the selected configuration scope.
2. Debug Mode - enable only during testing and implementation verification.
3. Render Mode - keep Server and JavaScript unless there is a reason to limit the operating mode.
4. Missing Value Strategy - choose whether missing values should be skipped or sent as undefined.
5. Clear Ecommerce Before Push - recommended Yes.
6. Fail-safe Mode - recommended Yes; sales-critical processes remain protected even after this option is disabled.
7. Log Level - on production, Errors only is recommended.
8. Log Payloads - enable only temporarily.

Product Mapping

1. Product Identifier Attribute - choose the attribute used as item_id. Default: sku.
2. Brand Attribute - choose the manufacturer/brand attribute. Default: manufacturer.
3. Category Strategy - choose the method for building item_category.
4. Category Attribute - set only if the category strategy uses a product attribute.
5. Configurable Product Strategy - decide whether to use child/simple or parent/configurable data.
6. Include Out Of Stock Products On Lists - applies to product list events.

Events

Enable the events required by the implementation:

• user_data
• view_item_list
• select_item
• view_item
• add_to_cart
• remove_from_cart
• view_cart
• add_to_wishlist
• begin_checkout
• add_shipping_info
• add_payment_info
• purchase
• purchase_test, if the store uses an intermediate page before payment.

Privacy

1. Send User ID - sends the Magento customer ID for logged-in customers.
2. Send Hashed Email - sends only the SHA-256 hash of the email. The raw email is not sent to dataLayer.

Integrations

1. Integrate With Kowal Cookie Consent - enable if the store uses Kowal_CookieConsent.
2. Render GTM From DataLayer Module - leave No if GTM is already rendered by Cookie Consent or another module.
3. Google Tag Manager ID - set only if GTM rendering from this module is enabled.
4. purchase_test Redirect Rules - add only those payment methods that should use the purchase_test intermediate page.

purchase_test rule modes:

• Static URL - use only for payments with a fixed operator address.
• URL Pattern - use when a URL pattern with placeholders {order_id}, {order_increment_id}, {store_id}, or {quote_id} is sufficient.
• Adapter Required - use for gateways that generate a dynamic transaction URL. Before launching on production, a dedicated adapter must be added for the specific payment module.

Multistore configuration

Configure the module at the store view level if the stores differ in:

• language;
• currency;
• advertising feed;
• product identifier attribute;
• brand attribute;
• category structure;
• payment methods.

Implementation verification

1. Open Google Tag Manager Preview.
2. Check dataLayer in the browser console or with the DataLayer Checker extension.
3. Test the product page and the view_item event.
4. Open a category or search results and check view_item_list.
5. Click a product on the list and check select_item.
6. Add a product to the cart and check add_to_cart.
7. Change the quantity or remove a product from the cart and check remove_from_cart.
8. Add a product to the wishlist and check add_to_wishlist.
9. Go to the cart and checkout, then check view_cart and begin_checkout.
10. Save the shipping and payment method, then check add_shipping_info and add_payment_info.
11. Place a test order and check purchase.
12. Refresh the success page and make sure purchase is not duplicated.
13. Check var/log/kowal_datalayer.log.

purchase_test integration

If the payment method redirects the customer outside the store and knows the target operator URL, the payment integration can use:

Kowal\DataLayer\Model\PurchaseTestRedirect::prepare($paymentRedirectUrl)

The method returns the module intermediate page URL. The intermediate page sends purchase_test and then redirects the customer to the payment operator. If JavaScript or DataLayer does not work, the redirect should still be performed.

For an integration where the URL depends on the order or transaction token, use:

Kowal\DataLayer\Model\PurchaseTestRedirect::prepareForOrder($order, $fallbackRedirectUrl)

If the method is set to Adapter Required mode, the adapter should implement:

Kowal\DataLayer\Api\PurchaseTestRedirectAdapterInterface

The adapter should be registered in DI as an array item in adapters for Kowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. The adapter is the proper place for logic that depends on a specific payment operator.