Kowal Data Layer voor Magento 2

Installatie- en configuratiehandleiding

Vereisten

• Magento Open Source / Adobe Commerce 2.4.x.
• PHP compatibel met de gebruikte Magento-versie.
• Composer-toegang tot de privérepository van de module.
• Module kowal/base.
• Machtiging om setup:upgrade uit te voeren, omdat de module attributievelden toevoegt aan de tabellen quote en sales_order.
• Webcontainer van Google Tag Manager als de webshop gebruik moet maken van kant-en-klare integratie-exports.
• Optioneel: Kowal_CookieConsent als de webshop deze gebruikt voor GTM en Consent Mode.

Installatie met Composer

De toegangsgegevens voor de Composer-repository, het e-mailadres van de klant en de licentietoken, ontvangt u na aankoop per e-mail. Ze zijn ook beschikbaar in het klantpanel na inloggen op kowal.store. Vervang TWOJ_EMAIL_KLIENTA door het e-mailadres van uw account en TWOJ_TOKEN door de ontvangen token. Voer de opdrachten uit in de hoofdmap van Magento.

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

De opdracht setup:upgrade maakt de kolommen aan:

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

De kolommen bevatten geserialiseerde first-touch- en last-touch-gegevens. Maak ze niet handmatig aan.

Een bestaande installatie bijwerken

Maak vóór het bijwerken van productie een databaseback-up volgens de projectprocedure. Werk vervolgens het pakket en het Magento-schema bij:

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

Voer in productiemodus opnieuw DI-compilatie en deployment van statische assets uit. Dit is onder andere vereist voor het nieuwe attributie-endpoint, quote/order-observers en wijzigingen in het frontend-script.

Voer in de productieomgeving, als het project dit vereist, de standaard Magento-deployment uit:

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

Na het bijwerken van ACL-machtigingen moet de beheerder mogelijk opnieuw inloggen in het panel om de positie Data Layer > GTM Exports te zien.

Basisconfiguratie

Beheerpaneel:

Stores > Configuration > Kowal > Kowal Data Layer

Menu:

kowal.store > Modules > Data Layer > Settings

General

1. Enable Module - schakel de module in voor het gekozen configuratiebereik.
2. Debug Mode - schakel alleen in tijdens tests en verificatie van de implementatie.
3. Render Mode - laat Server and JavaScript staan als er geen reden is om de werkingsmodus te beperken.
4. Missing Value Strategy - kies of ontbrekende waarden moeten worden overgeslagen of als undefined moeten worden verzonden.
5. Clear Ecommerce Before Push - aanbevolen Yes.
6. Fail-safe Mode - aanbevolen Yes; processen die kritisch zijn voor verkoop blijven ook beschermd nadat deze optie is uitgeschakeld.
7. Log Level - op productie aanbevolen Errors only.
8. Log Payloads - alleen tijdelijk inschakelen.

Product Mapping

1. Product Identifier Attribute - kies het attribuut dat als item_id wordt gebruikt. Standaard sku.
2. Brand Attribute - kies het producent-/merkattribuut. Standaard manufacturer.
3. Category Strategy - kies de manier waarop item_category wordt opgebouwd.
4. Category Attribute - alleen instellen wanneer de categoriestrategie een productattribuut gebruikt.
5. Configurable Product Strategy - beslis of gegevens van child/simple of parent/configurable worden gebruikt.
6. Include Out Of Stock Products On Lists - heeft betrekking op productlijst-events.

Events

Schakel de events in die voor de implementatie vereist zijn:

• 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, als de webshop een tussenpagina vóór betaling gebruikt.

Privacy

1. Send User ID - verzendt de Magento-klant-ID voor ingelogde klanten.
2. Send Hashed Email - verzendt alleen de SHA-256-hash van het e-mailadres. Het ruwe e-mailadres komt niet in dataLayer terecht.

Attribution

Capture First and Last Touch Attribution slaat de bron van het bezoek van de klant op in quote en bestelling. Aanbevolen instelling: Yes.

De instelling werkt per store view. Na uitschakeling registreert de module geen nieuwe touchpoints. Gegevens die eerder in bestaande bestellingen zijn opgeslagen, blijven in de database staan.

De module herkent:

• parameters utm_source, utm_medium, utm_campaign, utm_id, utm_term, utm_content en utm_source_platform;
• click ID-typen van Google Ads, Microsoft Ads, Meta, TikTok, Pinterest, X en LinkedIn;
• bezoeken vanuit organische zoekresultaten;
• externe referrals;
• directe bezoeken.

Opgeslagen worden first_touch en last_touch, dus de laatste bron anders dan direct. Normaal navigeren tussen subpagina’s van de webshop overschrijft de bron niet. Referrals vanaf betaaladressen, callbacks, returns en succespagina’s worden genegeerd, zodat de betaaloperator niet als verkoopbron wordt beschouwd.

Het vastleggen werkt op twee manieren:

• aan Magento-zijde voor standaard, niet-gecachete bezoeken;
• via een lichte browserrequest voor pagina’s die vanuit FPC of Varnish worden bediend.

Gegevens worden bewaard in de checkout-sessie, opgeslagen bij quote en vóór het plaatsen van de bestelling gekopieerd naar order. Het mechanisme omvat de klassieke frontend, AJAX/REST checkout en bestellingen die worden aangemaakt op basis van een quote die al attributie bevat.

Ruwe waarden van gclid, fbclid en andere klikidentifiers worden niet opgeslagen. De module bewaart uitsluitend het parametertype, bijvoorbeeld gclid, en de resulterende bronclassificatie. Querystrings worden verwijderd uit de opgeslagen landing page en referrer.

Attributie kan worden gecontroleerd:

• in de bestelweergave in de sectie Customer Attribution;
• in dataLayer in de eigenschap attribution van het event purchase;
• rechtstreeks in de kolommen kowal_attribution_first en kowal_attribution_last van de tabellen quote en sales_order.

Het vastleggen van de bron moet worden opgenomen in de privacydocumentatie van de webshop volgens het implementatiebeleid. De module maakt geen eigen langetermijnidentifier voor de gebruiker aan en slaat geen click ID-waarden op, maar bewaart wel campagnemetadata en de bestelbron.

Integrations

1. Integrate With Kowal Cookie Consent - schakel in als de webshop Kowal_CookieConsent gebruikt.
2. Render GTM From DataLayer Module - laat op No staan als GTM al wordt gerenderd door Cookie Consent of een andere module.
3. Google Tag Manager ID - stel alleen in wanneer GTM-rendering vanuit deze module is ingeschakeld.
4. purchase_test Redirect Rules - voeg alleen die betaalmethoden toe die de tussenpagina purchase_test moeten gebruiken.

Regelmodi voor purchase_test:

• Static URL - alleen gebruiken voor betalingen met een vast operatoradres.
• URL Pattern - gebruiken wanneer een URL-patroon met placeholders {order_id}, {order_increment_id}, {store_id} of {quote_id} voldoende is.
• Adapter Required - gebruiken voor gateways die een dynamische transactie-URL genereren. Vóór activering op productie moet een dedicated adapter voor de specifieke betaalmodule worden toegevoegd.

GTM Export Identifiers

Voer in deze sectie de identifiers in van services die in de gegenereerde JSON-bestanden moeten worden opgenomen:

Velden mogen leeg zijn als de webshop het betreffende platform niet gebruikt. Bij het opslaan van de configuratie wordt het formaat van elke ingevulde waarde gecontroleerd. De exportknop controleert alleen de set die voor het gekozen platform vereist is, daarom vereist bijvoorbeeld een GA4-export geen configuratie van Meta of TikTok.

Klik na het invullen van de velden op Save Config en vervolgens op de juiste knop Download ... JSON in het veld Generate GTM Exports. Het gedownloade bestand bevat al de definitieve identifiers. Het is niet nodig om constante variabelen na import in GTM te bewerken.

Multistore-configuratie

Configureer de module op store view-niveau als webshops verschillen in:

• taal;
• valuta;
• advertentiefeed;
• attribuut van de productidentifier;
• merkattribuut;
• categoriestructuur;
• betaalmethoden;
• regels voor het vastleggen van attributie;
• service-identifiers die in geïmporteerde GTM-pakketten worden gebruikt.

Implementatie verifiëren

1. Open Google Tag Manager Preview.
2. Controleer dataLayer in de browserconsole of met de extensie DataLayer Checker.
3. Test de productpagina en het event view_item.
4. Open een categorie of zoekresultaten en controleer view_item_list.
5. Klik op een product in de lijst en controleer select_item.
6. Voeg een product toe aan de winkelwagen en controleer add_to_cart.
7. Wijzig de hoeveelheid of verwijder een product uit de winkelwagen en controleer remove_from_cart.
8. Voeg een product toe aan de wishlist en controleer add_to_wishlist.
9. Ga naar de winkelwagen en checkout, controleer view_cart en begin_checkout.
10. Sla de verzend- en betaalmethode op, controleer add_shipping_info en add_payment_info.
11. Plaats een testbestelling en controleer purchase.
12. Vernieuw de succespagina en controleer of purchase niet wordt gedupliceerd.
13. Controleer var/log/kowal_datalayer.log.
14. Open de webshop in een nieuw privévenster met de URL ?utm_source=test&utm_medium=cpc&utm_campaign=attribution_test.
15. Ga door enkele subpagina’s, voeg een product toe aan de winkelwagen en plaats een bestelling.
16. Controleer in de bestelweergave de sectie Customer Attribution en attribution.first_touch en attribution.last_touch in het event purchase.
17. Bevestig dat first_touch.source de waarde test heeft, medium de waarde cpc heeft en campaign de waarde attribution_test heeft.
18. Keer in hetzelfde venster en dezelfde sessie terug naar de webshop vanuit een andere gemarkeerde bron en bevestig dat first_touch ongewijzigd is gebleven en last_touch is bijgewerkt.
19. Als de webshop een externe gateway gebruikt, bevestig dan na terugkeer van de betaling dat het domein van de operator de bestelbron niet heeft vervangen.

Configuratie-export van Google Tag Manager

Ga in het Magento-panel naar Stores > Configuration > Kowal > Kowal Data Layer > GTM Export Identifiers. Er zijn aparte pakketten beschikbaar voor GA4, Google Ads, Meta, TikTok, Pinterest en Microsoft Ads.

1. Kies het juiste configuratiebereik: Default Config, website of store view.
2. Vul de identifiers van de gebruikte platforms in en sla de configuratie op.
3. Klik op de knop om de JSON van het gekozen platform te downloaden in het veld Generate GTM Exports.
4. Maak in GTM een nieuwe workspace aan en kies Admin > Import Container.
5. Wijs het gedownloade bestand aan en gebruik de modus Merge.
6. Controleer de lijst met toegevoegde variabelen, regels en tags en bevestig dat constante variabelen de juiste identifiers bevatten.
7. Controleer de toestemmingsvereisten en start GTM Preview.
8. Publiceer de container pas nadat de events in de diagnostische tool van het platform zijn bevestigd.

Elementnamen worden voorafgegaan door het prefix Kowal - nazwa platformy, waardoor pakketten in één container kunnen worden gecombineerd. Het event purchase_test wordt niet als conversie geëxporteerd; verkoop wordt uitsluitend via purchase gerapporteerd.

Als een vereist veld leeg is of een onjuist formaat heeft, genereert de module geen export en toont een melding met de waarde die moet worden gecorrigeerd. Dit voorkomt dat per ongeluk een container met een placeholder wordt geïmporteerd. De alternatieve pagina Kowal > Data Layer > GTM Exports blijft beschikbaar, maar gebruikt waarden uit het bereik Default Config; voor multistore-implementaties worden de knoppen in de configuratie aanbevolen.

Exports hebben betrekking op de webcontainer en browser-side verzending. Ze vervangen geen serverintegraties zoals Meta Conversions API of TikTok Events API.

Toestemmingen en GTM-publicatie

• Advertentietags vereisen ad_storage, ad_user_data en ad_personalization.
• GA4 gebruikt de ingebouwde toestemmingsmechanismen van de Google tag.
• Als GTM Kowal_CookieConsent rendert, laat Render GTM From DataLayer Module ingesteld op No.
• Publiceer de container niet zonder Consent Mode, GTM Preview en de eventsdiagnostiek van het juiste platform te controleren.
• Voeg bij restrictieve CSP de scriptdomeinen en endpoints van de gekozen platforms toe volgens hun documentatie.

Integratie van purchase_test

Als de betaalmethode de klant buiten de webshop doorverwijst en de doel-URL van de operator kent, kan de betaalintegratie gebruiken:

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

De methode retourneert de URL van de tussenpagina van de module. De tussenpagina verzendt purchase_test en verwijst de klant vervolgens door naar de betaaloperator. Als JavaScript of DataLayer niet werkt, moet de doorverwijzing nog steeds worden uitgevoerd.

Gebruik voor een integratie waarbij de URL afhankelijk is van de bestelling of transactietoken:

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

Als de methode is ingesteld in de modus Adapter Required, moet de adapter implementeren:

Kowal\DataLayer\Api\PurchaseTestRedirectAdapterInterface

De adapter moet in DI worden geregistreerd als element van de array adapters voor Kowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. De adapter is de juiste plaats voor logica die afhankelijk is van een specifieke betaaloperator.

Diagnostiek

Geen sectie Customer Attribution bij de bestelling

1. Controleer of Capture First and Last Touch Attribution is ingeschakeld voor de juiste store view.
2. Bevestig dat php bin/magento setup:upgrade is uitgevoerd en dat de vier attributiekolommen aanwezig zijn.
3. Leeg de configuratie- en layoutcache.
4. Voer een test uit in een nieuw privévenster met een gemarkeerde UTM-URL.
5. Controleer var/log/kowal_datalayer.log op meldingen attribution capture failed of attribution assignment failed.

Attributie werkt zonder FPC, maar niet met Varnish

1. Controleer in de ontwikkelaarstools de POST-request naar kowal_datalayer/attribution/capture.
2. Bevestig dat de request status 200 heeft en naar hetzelfde domein van de webshop wordt uitgevoerd.
3. Controleer of CSP, WAF of reverse proxy-regels het endpoint niet blokkeren.
4. Controleer na deployment of het actuele bestand view/frontend/web/js/data-layer.js is gepubliceerd.

De aankoop heeft ten onrechte de betaaloperator als bron

Controleer of de bestelling is ontstaan vanuit een quote die vóór de doorverwijzing attributie bevatte. Routes met payment, callback, return of success mogen last-touch niet overschrijven met een referral. Als een aangepaste betaalmodule een andere volgorde gebruikt, verifieer dan het moment waarop order wordt aangemaakt en quote wordt opgeslagen.

GTM-import meldt conflicten

Gebruik de modus Merge en bekijk de details van de wijzigingen. Exportelementen hebben het prefix Kowal - ...; als de container gewijzigde elementen met dezelfde naam bevat, kies dan bewust voor overschrijven of hernoemen. Controleer na het hernoemen de referenties van tags naar variabelen en triggers.