Kowal Data Layer for Magento 2

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 private module repository.
• The 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 ready-made integration exports.
• Optional: Kowal_CookieConsent, if the store uses it for GTM and Consent Mode.

Installation with Composer

You will receive Composer repository access data, meaning the customer email address and license token, by email after purchase. They are also available in the customer panel after logging in at kowal.store. Replace TWOJ_EMAIL_KLIENTA with the email address of your account and TWOJ_TOKEN with the received token. Run the commands in the Magento root directory.

composer config repositories.kowal composer https://repo.kowal.store
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'
composer require kowal/module-datalayer
php bin/magento module:enable Kowal_DataLayer
php bin/magento setup:upgrade
php bin/magento cache:flush

The setup:upgrade command creates the 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, create a database backup according to the project procedure. Then update the package and Magento schema:

composer update kowal/module-datalayer --with-dependencies
php bin/magento module:enable Kowal_DataLayer
php bin/magento setup:upgrade
php bin/magento cache:flush

In production mode, run DI compilation and static asset 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 the project requires it, run the standard Magento deployment:

php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:flush

After updating ACL permissions, the administrator may need to log in to the panel again 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 if there is no reason to limit the operating mode.
4. Missing Value Strategy - choose whether missing values should be omitted or sent as undefined.
5. Clear Ecommerce Before Push - recommended Yes.
6. Fail-safe Mode - recommended Yes; sales-critical processes remain protected even after disabling this option.
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 how to build item_category.
4. Category Attribute - set only when 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.

Attribution

Capture First and Last Touch Attribution saves the source of the customer visit in the quote and order. Recommended setting: Yes.

The setting works per store view. After it is disabled, the module no longer records 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;
• Google Ads, Microsoft Ads, Meta, TikTok, Pinterest, X, and LinkedIn click ID types;
• visits from organic search results;
• external referrals;
• direct visits.

first_touch and last_touch, meaning the last non-direct source, are saved. Regular navigation between store pages does not overwrite the source. Referrals from payment URLs, callbacks, returns, and success pages are ignored so that the payment operator is not considered the sales source.

Capture works in two ways:

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

Data is maintained in the checkout session, saved with the quote, and copied to the order before the order is placed. 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 saved. The module stores only the parameter type, for example gclid, and the resulting source classification. Query strings are removed from the saved landing page and referrer.

Attribution can be checked:

• in the order view in the Customer Attribution section;
• in dataLayer in 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 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 when rendering GTM from this module is enabled.
4. purchase_test Redirect Rules - add only the payment methods that should use the intermediate purchase_test page.

purchase_test rule modes:

• Static URL - use only for payments with a fixed operator URL.
• 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 in production, a dedicated adapter must be added for the specific payment module.

GTM Export Identifiers

In this section, enter the service identifiers that should be embedded in the generated JSON files:

Fields may be empty if the store does not use a given platform. Saving the configuration checks the format of each completed value. The export button checks only the set required by the selected platform, so for example a GA4 export does not require Meta or TikTok configuration.

After completing the fields, click Save Config, then the appropriate Download ... JSON button in the Generate GTM Exports field. The downloaded file already contains the final identifiers. You do not need to edit constant variables after importing to GTM.

Multistore configuration

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

• language;
• currency;
• advertising feed;
• product identifier attribute;
• brand attribute;
• category structure;
• payment methods;
• attribution capture rules;
• service identifiers used in 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, and check view_cart and begin_checkout.
10. Save the shipping and payment method, and 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. Browse several pages, add a product to the cart, and place an order.
16. In 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 operator domain did not replace the order source.

Google Tag Manager configuration export

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

1. Select the appropriate configuration scope: Default Config, website, or store view.
2. Complete the identifiers for the platforms in use and save the configuration.
3. Click the JSON download button for the selected platform in the Generate GTM Exports field.
4. In GTM, create a new workspace and select Admin > Import Container.
5. Select the downloaded file and use Merge mode.
6. Review the list of added variables, rules, and tags, and confirm that constant variables contain the correct identifiers.
7. Check consent requirements and launch GTM Preview.
8. Publish the container only after confirming the events in the platform diagnostic tool.

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

If a required field is empty or has an invalid format, the module will not generate the export and will display a message indicating the value that needs correction. This prevents accidental import of a container with a placeholder. The alternative Kowal > Data Layer > GTM Exports page remains available, but it uses values from the Default Config scope; for multistore implementations, the buttons in the configuration are recommended.

The exports apply to the web container and browser-side sending. 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 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 must be registered in DI as an element of the adapters array for Kowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. The adapter is the right place for logic dependent on a specific payment operator.

Diagnostics

Customer Attribution section missing 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 a 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 made 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 has been published.

Purchase has an incorrect payment operator source

Check whether the order was created from a quote that contained 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 have the Kowal - ... prefix; if modified elements with the same name already exist in the container, deliberately choose whether to overwrite or rename them. After renaming, check tag references to variables and triggers.