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's private repository.
• kowal/base module.
• Permission to run setup:upgrade, because the module adds attribution fields to the quote and sales_order tables.
• A Google Tag Manager web container, if the store is to use the ready-made integration exports.
• 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

The setup:upgrade command creates the following columns:

• quote.kowal_attribution_first;
• quote.kowal_attribution_last;
• sales_order.kowal_attribution_first;
• sales_order.kowal_attribution_last.

The columns contain serialized first-touch and last-touch data. They should not be created manually.

Updating an existing installation

Before updating production, make a database backup according to the project procedure. Then update the package and Magento schema:

composer update kowal/module-datalayer --with-dependenciesphp bin/magento module:enable Kowal_DataLayerphp bin/magento setup:upgradephp bin/magento cache:flush

In production mode, run DI compilation and static assets deployment again. This is required, among other things, for the new attribution endpoint, quote/order observers, and changes in the frontend script.

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

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

After the ACL permissions are updated, the administrator may need to log back into the admin panel to see the Data Layer > GTM Exports item.

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 - leave 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 if this option is disabled.
7. Log Level - Errors only is recommended in production.
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 the 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 does not go to dataLayer.

Attribution

Capture First and Last Touch Attribution saves the customer's entry source in the quote and order. Recommended setting: Yes.

The setting works per store view. After disabling it, the module does not register new touchpoints. Data previously saved in existing orders remains in the database.

The module recognizes:

• utm_source, utm_medium, utm_campaign, utm_id, utm_term, utm_content, and utm_source_platform parameters;
• click ID types from Google Ads, Microsoft Ads, Meta, TikTok, Pinterest, X, and LinkedIn;
• visits from organic search results;
• external referrals;
• direct visits.

It saves first_touch and last_touch, meaning the last non-direct source. Regular navigation between store pages does not overwrite the source. Referrals from payment addresses, callbacks, returns, and success pages are ignored so the payment provider is not recognized as the sales source.

Capture works in two ways:

• on the Magento side for standard, non-cached visits;
• through a lightweight browser request for pages served from FPC or Varnish.

The data is kept in the checkout session, saved with the quote, and copied to the order before order placement. The mechanism covers the classic frontend, AJAX/REST checkout, and orders created from a quote that already contains attribution.

Raw gclid, fbclid, and other click identifier values are not stored. The module keeps only the parameter type, for example gclid, and the resulting source classification. Query strings are removed from the saved landing page and referrer.

You can verify attribution:

• on the order view in the Customer Attribution section;
• in dataLayer under the attribution property of the purchase event;
• directly in the kowal_attribution_first and kowal_attribution_last columns of the quote and sales_order tables.

Source capture should be included in the store's privacy documentation according to the implementation policy. The module does not create its own long-term user identifier and does not store click ID values, but it does store campaign metadata and the order source.

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 rendering GTM 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 payment provider address.
• URL Pattern - use when a URL pattern with {order_id}, {order_increment_id}, {store_id}, or {quote_id} placeholders is sufficient.
• Adapter Required - use for gateways that generate a dynamic transaction URL. Before launching in 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;
• attribution capture rules;
• service identifiers used in the imported GTM packages.

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 methods, 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.
14. In a new private window, open the store with the URL ?utm_source=test&utm_medium=cpc&utm_campaign=attribution_test.
15. Go through several pages, add a product to the cart, and place an order.
16. On the order view, check the Customer Attribution section and attribution.first_touch and attribution.last_touch in the purchase event.
17. Confirm that first_touch.source has the value test, medium has the value cpc, and campaign has the value attribution_test.
18. In the same window and session, return to the store from another tagged source and confirm that first_touch remained unchanged and last_touch was updated.
19. If the store uses an external gateway, confirm after returning from payment that the provider domain did not replace the order source.

Google Tag Manager configuration export

In the Magento admin panel, go to Kowal > Data Layer > GTM Exports. Separate packages are available for GA4, Google Ads, Meta, TikTok, Pinterest, and Microsoft Ads.

1. Download the JSON for the selected platform.
2. In GTM, create a new workspace and select Admin > Import Container.
3. Select the downloaded file and use Merge mode.
4. Review the list of added variables, rules, and tags.
5. After import, replace placeholder values in constant variables, such as Measurement ID or Pixel ID.
6. Check consent requirements and run GTM Preview.
7. Publish the container only after confirming events in the platform's diagnostic tool.

Element names are prefixed with Kowal - platform name, which allows the packages to be combined in one container. The purchase_test event is not exported as a conversion; sales are reported exclusively through purchase.

After import, fill in the following constant variables:

The exports apply to the web container and browser-side delivery. They do not replace server-side integrations such as Meta Conversions API or TikTok Events API.

Consents and GTM publishing

• Advertising tags require ad_storage, ad_user_data, and ad_personalization.
• GA4 uses the built-in consent mechanisms of the Google tag.
• If GTM is rendered by Kowal_CookieConsent, leave Render GTM From DataLayer Module set to No.
• Do not publish the container without checking Consent Mode, GTM Preview, and the event diagnostics of the relevant platform.
• With a restrictive CSP, add the script domains and endpoints of the selected platforms according to their documentation.

purchase_test integration

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

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

The method returns the module's intermediate page URL. The intermediate page sends purchase_test and then redirects the customer to the payment provider. 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 adapters array element for Kowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. The adapter is the right place for logic dependent on a specific payment provider.

Diagnostics

Missing Customer Attribution section on the order

1. Check whether Capture First and Last Touch Attribution is enabled for the correct store view.
2. Confirm that php bin/magento setup:upgrade was run and that the four attribution columns exist.
3. Clear the configuration and layout cache.
4. Run the test in a new private window with a tagged UTM URL.
5. Check var/log/kowal_datalayer.log for attribution capture failed or attribution assignment failed messages.

Attribution works without FPC but does not work with Varnish

1. Check the POST request to kowal_datalayer/attribution/capture in developer tools.
2. Confirm that the request has status 200 and is sent to the same store domain.
3. Check whether CSP, WAF, or reverse proxy rules are blocking the endpoint.
4. After deployment, make sure the current view/frontend/web/js/data-layer.js file was published.

The purchase has an incorrect payment provider source

Check whether the order was created from a quote containing attribution before the redirect. Routes containing payment, callback, return, or success should not overwrite last-touch with a referral. If a custom payment module uses a different sequence, verify when the order is created and the quote is saved.

GTM import reports conflicts

Use Merge mode and review the change details. Export elements use the Kowal - ... prefix; if the container contains modified elements with the same name, deliberately choose overwrite or rename them. After renaming, check tag references to variables and triggers.