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.
• Opțional: Kowal_CookieConsent, dacă magazinul îl folosește pentru GTM și Consent Mode.

Instalare prin 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

În mediul de producție, dacă proiectul o cere, executați deployment-ul standard Magento:

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

Configurare de bază

Panou de administrare:

Stores > Configuration > Kowal > Kowal Data Layer

Meniu:

kowal.store > Modules > Data Layer > Settings

General

1. Enable Module - activați modulul pentru domeniul de configurare selectat.
2. Debug Mode - activați doar în timpul testelor și verificării implementării.
3. Render Mode - păstrați Server and JavaScript, dacă nu există un motiv pentru limitarea modului de funcționare.
4. Missing Value Strategy - alegeți 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ânzări rămân protejate și după dezactivarea acestei opțiuni.
7. Log Level - în producție este recomandat Errors only.
8. Log Payloads - activați doar temporar.

Product Mapping

1. Product Identifier Attribute - alegeți atributul folosit ca item_id. Implicit sku.
2. Brand Attribute - alegeți atributul producătorului/brandului. Implicit manufacturer.
3. Category Strategy - alegeți modul de construire a item_category.
4. Category Attribute - setați doar atunci când strategia de categorie folosește atributul produsului.
5. Configurable Product Strategy - decideți dacă folosiți datele copilului/simple sau ale părintelui/configurable.
6. Include Out Of Stock Products On Lists - se aplică evenimentelor listelor de produse.

Evenimente

Activați evenimentele necesare pentru 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 pagina 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 hash-ul SHA-256 al emailului. Emailul brut nu ajunge în dataLayer.

Integrations

1. Integrate With Kowal Cookie Consent - activați dacă magazinul folosește Kowal_CookieConsent.
2. Render GTM From DataLayer Module - lăsați No dacă GTM este deja randat de Cookie Consent sau de alt modul.
3. Google Tag Manager ID - setați doar dacă randarea GTM din acest modul este activată.
4. purchase_test Redirect Rules - adăugați doar acele metode de plată care trebuie să folosească pagina intermediară purchase_test.

Moduri pentru regulile purchase_test:

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

Configurare multistore

Configurați 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ă.

Verificarea implementării

1. Deschideți Google Tag Manager Preview.
2. Verificați dataLayer în consola browserului sau cu extensia DataLayer Checker.
3. Testați pagina de produs și evenimentul view_item.
4. Deschideți o categorie sau rezultatele căutării și verificați view_item_list.
5. Dați click pe un produs din listă și verificați select_item.
6. Adăugați produsul în coș și verificați add_to_cart.
7. Schimbați cantitatea sau eliminați produsul din coș și verificați remove_from_cart.
8. Adăugați produsul în wishlist și verificați add_to_wishlist.
9. Intrați în coș și checkout, verificați view_cart și begin_checkout.
10. Salvați metoda de livrare și de plată, verificați add_shipping_info și add_payment_info.
11. Plasați o comandă de test și verificați purchase.
12. Reîmprospătați pagina de succes și asigurați-vă că purchase nu se duplică.
13. Verificați var/log/kowal_datalayer.log.

Integrarea purchase_test

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

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 plată. Dacă JavaScript sau DataLayer nu funcționează, redirecționarea ar trebui totuși să fie executată.

Pentru o integrare în care URL-ul depinde de comandă sau de token-ul tranzacției, utilizați:

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 tabloului adapters pentru Kowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. Adapterul este locul potrivit pentru logica dependentă de operatorul de plată concret.