Kowal Data Layer pentru Magento 2

Instrucțiuni de instalare și configurare

Cerințe

• Magento Open Source / Adobe Commerce 2.4.x.
• PHP compatibil cu versiunea Magento utilizată.
• Acces Composer la repository-ul privat al modulului.
• Modulul kowal/base.
• Permisiunea de a executa setup:upgrade, deoarece modulul adaugă câmpuri de atribuire în tabelele quote și sales_order.
• Container web Google Tag Manager, dacă magazinul urmează să folosească exporturile de integrare gata pregătite.
• Opțional: Kowal_CookieConsent, dacă magazinul îl folosește pentru GTM și Consent Mode.

Instalare cu Composer

Datele de acces la repository-ul Composer (adresa de e-mail a clientului și tokenul de licență) le vei primi prin e-mail după achiziție. Sunt disponibile și în panoul clientului după autentificarea pe kowal.store. Înlocuiește TWOJ_EMAIL_KLIENTA cu adresa de e-mail a contului tău, iar TWOJ_TOKEN cu tokenul primit. Execută comenzile în directorul rădăcină 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

Comanda setup:upgrade creează coloanele:

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

Coloanele conțin date serializate first-touch și last-touch. Nu trebuie create manual.

Actualizarea unei instalări existente

Înainte de actualizarea producției, fă o copie a bazei de date conform procedurii proiectului. Apoi actualizează pachetul și schema Magento:

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

În modul producție, rulează din nou compilarea DI și deploymentul asseturilor statice. Acest lucru este necesar, printre altele, pentru noul endpoint de atribuire, observerele quote/order și modificările din scriptul frontend.

În mediul de producție, dacă proiectul o cere, efectuează deploymentul standard Magento:

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

După actualizarea permisiunilor ACL, administratorul poate avea nevoie să se autentifice din nou în panou, pentru a vedea poziția Data Layer > GTM Exports.

Configurare de bază

Panou de administrare:

Stores > Configuration > Kowal > Kowal Data Layer

Meniu:

kowal.store > Modules > Data Layer > Settings

General

1. Enable Module - activează modulul pentru domeniul de configurare selectat.
2. Debug Mode - activează doar în timpul testelor și verificării implementării.
3. Render Mode - lasă Server and JavaScript, dacă nu există un motiv pentru limitarea modului de funcționare.
4. Missing Value Strategy - alege dacă valorile lipsă trebuie omise sau trimise ca undefined.
5. Clear Ecommerce Before Push - recomandat Yes.
6. Fail-safe Mode - recomandat Yes; procesele critice pentru vânzare rămân protejate și după dezactivarea acestei opțiuni.
7. Log Level - în producție este recomandat Errors only.
8. Log Payloads - activează doar temporar.

Product Mapping

1. Product Identifier Attribute - alege atributul folosit ca item_id. Implicit sku.
2. Brand Attribute - alege atributul producătorului/brandului. Implicit manufacturer.
3. Category Strategy - alege modul de construire a item_category.
4. Category Attribute - setează doar atunci când strategia categoriei folosește un atribut de produs.
5. Configurable Product Strategy - decide dacă folosești datele copil/simple sau părinte/configurable.
6. Include Out Of Stock Products On Lists - se aplică evenimentelor listelor de produse.

Events

Activează evenimentele cerute de implementare:

• 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, dacă magazinul folosește o pagină intermediară înainte de plată.

Privacy

1. Send User ID - trimite ID-ul clientului Magento pentru clienții autentificați.
2. Send Hashed Email - trimite doar hashul SHA-256 al e-mailului. E-mailul brut nu ajunge în dataLayer.

Attribution

Capture First and Last Touch Attribution salvează sursa intrării clientului în quote și în comandă. Setare recomandată: Yes.

Setarea funcționează per store view. După dezactivarea ei, modulul nu înregistrează touchpointuri noi. Datele salvate anterior în comenzile existente rămân în baza de date.

Modulul recunoaște:

• parametrii utm_source, utm_medium, utm_campaign, utm_id, utm_term, utm_content și utm_source_platform;
• tipurile click ID Google Ads, Microsoft Ads, Meta, TikTok, Pinterest, X și LinkedIn;
• intrările din rezultatele organice ale căutării;
• referralurile externe;
• intrările direct.

Sunt salvate first_touch și last_touch, adică ultima sursă diferită de direct. Navigarea obișnuită între subpaginile magazinului nu suprascrie sursa. Referralurile din adresele de plată, callbackuri, returnuri și pagini de succes sunt omise, astfel încât operatorul de plăți să nu fie considerat sursă a vânzării.

Capturarea funcționează pe două căi:

• pe partea Magento pentru intrările standard, necachuite;
• printr-un request ușor din browser pentru paginile servite din FPC sau Varnish.

Datele sunt păstrate în sesiunea de checkout, salvate la quote și copiate în order înainte de plasarea comenzii. Mecanismul acoperă frontendul clasic, checkoutul AJAX/REST și comenzile create dintr-un quote care conține deja atribuirea.

Valorile brute gclid, fbclid și ale celorlalți identificatori de click nu sunt salvate. Modulul păstrează doar tipul parametrului, de ex. gclid, și clasificarea rezultată a sursei. Query stringurile sunt eliminate din landing page-ul și referrerul salvat.

Atribuirea poate fi verificată:

• în vizualizarea comenzii, în secțiunea Customer Attribution;
• în dataLayer în proprietatea attribution a evenimentului purchase;
• direct în coloanele kowal_attribution_first și kowal_attribution_last ale tabelelor quote și sales_order.

Capturarea sursei trebuie inclusă în documentația de confidențialitate a magazinului conform politicii de implementare. Modulul nu creează un identificator de utilizator propriu pe termen lung și nu salvează valorile click ID, dar stochează metadatele campaniei și sursa comenzii.

Integrations

1. Integrate With Kowal Cookie Consent - activează dacă magazinul folosește Kowal_CookieConsent.
2. Render GTM From DataLayer Module - lasă No, dacă GTM este deja randat prin Cookie Consent sau alt modul.
3. Google Tag Manager ID - setează doar atunci când randarea GTM din acest modul este activată.
4. purchase_test Redirect Rules - adaugă doar acele metode de plată care trebuie să folosească pagina intermediară purchase_test.

Modurile regulilor purchase_test:

• Static URL - folosește doar pentru plăți cu adresă fixă a operatorului.
• URL Pattern - folosește când este suficient un model URL cu placeholderi {order_id}, {order_increment_id}, {store_id} sau {quote_id}.
• Adapter Required - folosește pentru gateway-uri care generează un URL dinamic al tranzacției. Înainte de lansarea în producție trebuie adăugat un adapter dedicat pentru modulul de plată concret.

GTM Export Identifiers

În această secțiune introdu identificatorii serviciilor care trebuie încorporați în fișierele JSON generate:

Câmpurile pot rămâne goale, dacă magazinul nu folosește platforma respectivă. Salvarea configurației verifică formatul fiecărei valori completate. Butonul de export verifică setul necesar doar pentru platforma selectată, de aceea, de ex., exportul GA4 nu necesită configurarea Meta sau TikTok.

După completarea câmpurilor, fă clic pe Save Config, apoi pe butonul corespunzător Download ... JSON în câmpul Generate GTM Exports. Fișierul descărcat conține deja identificatorii finali. Nu este nevoie să editezi variabilele constante după importul în GTM.

Configurare multistore

Configurează modulul la nivel de store view, dacă magazinele diferă prin:

• limbă;
• monedă;
• feed publicitar;
• atributul identificatorului de produs;
• atributul brandului;
• structura categoriilor;
• metodele de plată;
• regulile de capturare a atribuirii;
• identificatorii serviciilor folosiți în pachetele GTM importate.

Verificarea implementării

1. Deschide Google Tag Manager Preview.
2. Verifică dataLayer în consola browserului sau cu extensia DataLayer Checker.
3. Testează pagina produsului și evenimentul view_item.
4. Deschide o categorie sau rezultatele căutării și verifică view_item_list.
5. Fă clic pe un produs din listă și verifică select_item.
6. Adaugă produsul în coș și verifică add_to_cart.
7. Schimbă cantitatea sau elimină produsul din coș și verifică remove_from_cart.
8. Adaugă produsul în wishlist și verifică add_to_wishlist.
9. Intră în coș și checkout, verifică view_cart și begin_checkout.
10. Salvează metoda de livrare și de plată, verifică add_shipping_info și add_payment_info.
11. Plasează o comandă de test și verifică purchase.
12. Reîmprospătează pagina de succes și asigură-te că purchase nu se dublează.
13. Verifică var/log/kowal_datalayer.log.
14. Într-o fereastră privată nouă, deschide magazinul cu URL-ul ?utm_source=test&utm_medium=cpc&utm_campaign=attribution_test.
15. Navighează prin câteva subpagini, adaugă produsul în coș și plasează comanda.
16. În vizualizarea comenzii, verifică secțiunea Customer Attribution și attribution.first_touch și attribution.last_touch în evenimentul purchase.
17. Confirmă că first_touch.source are valoarea test, medium are valoarea cpc, iar campaign are valoarea attribution_test.
18. În aceeași fereastră și sesiune, revino în magazin dintr-o altă sursă marcată și confirmă că first_touch a rămas neschimbat, iar last_touch a fost actualizat.
19. Dacă magazinul folosește un gateway extern, confirmă după revenirea de la plată că domeniul operatorului nu a înlocuit sursa comenzii.

Exportul configurării Google Tag Manager

În panoul Magento, mergi la Stores > Configuration > Kowal > Kowal Data Layer > GTM Export Identifiers. Sunt disponibile pachete separate pentru GA4, Google Ads, Meta, TikTok, Pinterest și Microsoft Ads.

1. Alege domeniul de configurare corespunzător: Default Config, website sau store view.
2. Completează identificatorii platformelor utilizate și salvează configurația.
3. Fă clic pe butonul de descărcare JSON al platformei selectate în câmpul Generate GTM Exports.
4. În GTM, creează un workspace nou și alege Admin > Import Container.
5. Indică fișierul descărcat și folosește modul Merge.
6. Revizuiește lista variabilelor, regulilor și tagurilor adăugate și confirmă că variabilele constante conțin identificatorii corecți.
7. Verifică cerințele privind consimțămintele și pornește GTM Preview.
8. Publică containerul numai după confirmarea evenimentelor în instrumentul de diagnosticare al platformei.

Numele elementelor sunt precedate de prefixul Kowal - nazwa platformy, datorită căruia pachetele pot fi combinate într-un singur container. Evenimentul purchase_test nu este exportat ca o conversie; vânzarea este raportată exclusiv prin purchase.

Dacă un câmp obligatoriu este gol sau are un format incorect, modulul nu va genera exportul și va afișa un mesaj care indică valoarea de corectat. Acest lucru previne importul accidental al unui container cu placeholder. Pagina alternativă Kowal > Data Layer > GTM Exports rămâne disponibilă, dar folosește valorile din domeniul Default Config; pentru implementările multistore sunt recomandate butoanele din configurare.

Exporturile se referă la containerul web și trimiterea browser-side. Nu înlocuiesc integrările server-side, precum Meta Conversions API sau TikTok Events API.

Consimțăminte și publicarea GTM

• Tagurile publicitare necesită ad_storage, ad_user_data și ad_personalization.
• GA4 folosește mecanismele integrate de consimțământ ale tagului Google.
• Dacă GTM randează Kowal_CookieConsent, lasă Render GTM From DataLayer Module setat pe No.
• Nu publica containerul fără verificarea Consent Mode, GTM Preview și diagnosticarea evenimentelor platformei corespunzătoare.
• În cazul unui CSP restrictiv, adaugă domeniile scripturilor și endpointurilor platformelor selectate conform documentației acestora.

Integrarea purchase_test

Dacă metoda de plată redirecționează clientul în afara magazinului și cunoaște URL-ul țintă al operatorului, integrarea de plată poate folosi:

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

Metoda returnează URL-ul paginii intermediare a modulului. Pagina intermediară trimite purchase_test, apoi redirecționează clientul către operatorul de plăți. Dacă JavaScript sau DataLayer nu funcționează, redirecționarea ar trebui totuși executată.

Pentru integrări în care URL-ul depinde de comandă sau de tokenul tranzacției, folosește:

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

Dacă metoda este setată în modul Adapter Required, adapterul ar trebui să implementeze:

Kowal\DataLayer\Api\PurchaseTestRedirectAdapterInterface

Adapterul trebuie înregistrat în DI ca element al arrayului adapters pentru Kowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. Adapterul este locul potrivit pentru logica dependentă de operatorul de plăți concret.

Diagnosticare

Lipsește secțiunea Customer Attribution în comandă

1. Verifică dacă Capture First and Last Touch Attribution este activat pentru store view-ul corespunzător.
2. Confirmă executarea php bin/magento setup:upgrade și prezența celor patru coloane de atribuire.
3. Golește cache-ul configurației și al layoutului.
4. Execută un test într-o fereastră privată nouă cu un URL marcat UTM.
5. Verifică var/log/kowal_datalayer.log pentru mesajele attribution capture failed sau attribution assignment failed.

Atribuirea funcționează fără FPC, dar nu funcționează cu Varnish

1. Verifică în instrumentele pentru dezvoltatori requestul POST către kowal_datalayer/attribution/capture.
2. Confirmă că requestul are status 200 și este executat către același domeniu al magazinului.
3. Verifică dacă CSP, WAF sau regulile reverse proxy nu blochează endpointul.
4. După deployment, asigură-te că a fost publicat fișierul actual view/frontend/web/js/data-layer.js.

Achiziția are sursa greșită a operatorului de plăți

Verifică dacă comanda a fost creată dintr-un quote care conținea atribuirea înainte de redirecționare. Rutele care conțin payment, callback, return sau success nu ar trebui să suprascrie last-touch cu referralul. Dacă un modul de plată personalizat folosește o altă secvență, verifică momentul creării order și salvării quote.

Importul GTM raportează conflicte

Folosește modul Merge și revizuiește detaliile modificărilor. Elementele exporturilor au prefixul Kowal - ...; dacă în container există elemente modificate cu același nume, alege conștient suprascrierea sau redenumirea. După schimbarea numelor, verifică referințele tagurilor către variabile și triggere.