Instrukcja instalacji i konfiguracji

Wymagania

• Magento Open Source / Adobe Commerce 2.4.x.
• PHP zgodne z używaną wersją Magento.
• Dostęp Composer do prywatnego repozytorium modułu.
• Moduł kowal/base.
• Opcjonalnie: Kowal_CookieConsent, jeżeli sklep używa go do GTM i Consent Mode.

Instalacja Composerem

composer config repositories.kowal-datalayer vcs <PRIVATE_REPOSITORY_URL>
composer require kowal/module-datalayer
php bin/magento module:enable Kowal_DataLayer
php bin/magento setup:upgrade
php bin/magento cache:flush

W środowisku produkcyjnym, jeśli projekt tego wymaga, wykonaj standardowy deployment Magento:

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

Konfiguracja podstawowa

Panel administracyjny:

Stores > Configuration > Kowal > Kowal Data Layer

Menu:

kowal.store > Modules > Data Layer > Settings

General

1. Enable Module - włącz moduł dla wybranego zakresu konfiguracji.
2. Debug Mode - włącz tylko podczas testów i weryfikacji wdrożenia.
3. Render Mode - pozostaw Server and JavaScript, jeśli nie ma powodu do ograniczenia trybu działania.
4. Missing Value Strategy - wybierz, czy brakujące wartości mają być pomijane, czy wysyłane jako undefined.
5. Clear Ecommerce Before Push - zalecane Yes.
6. Fail-safe Mode - zalecane Yes; procesy krytyczne dla sprzedaży pozostają chronione również po wyłączeniu tej opcji.
7. Log Level - na produkcji zalecane Errors only.
8. Log Payloads - włączaj tylko tymczasowo.

Product Mapping

1. Product Identifier Attribute - wybierz atrybut używany jako item_id. Domyślnie sku.
2. Brand Attribute - wybierz atrybut producenta/marki. Domyślnie manufacturer.
3. Category Strategy - wybierz sposób budowania item_category.
4. Category Attribute - ustaw tylko wtedy, gdy strategia kategorii korzysta z atrybutu produktu.
5. Configurable Product Strategy - zdecyduj, czy używać danych dziecka/simple czy rodzica/configurable.
6. Include Out Of Stock Products On Lists - dotyczy eventów list produktowych.

Events

Włącz eventy wymagane przez wdrożenie:

• 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, jeśli sklep używa strony pośredniej przed płatnością.

Privacy

1. Send User ID - wysyła ID klienta Magento dla zalogowanych klientów.
2. Send Hashed Email - wysyła tylko hash SHA-256 emaila. Surowy email nie trafia do dataLayer.

Integrations

1. Integrate With Kowal Cookie Consent - włącz, jeśli sklep używa Kowal_CookieConsent.
2. Render GTM From DataLayer Module - zostaw No, jeśli GTM jest już renderowany przez Cookie Consent albo inny moduł.
3. Google Tag Manager ID - ustaw tylko wtedy, gdy renderowanie GTM z tego modułu jest włączone.
4. purchase_test Redirect Rules - dodaj tylko te metody płatności, które mają używać strony pośredniej purchase_test.

Tryby reguł purchase_test:

• Static URL - używaj tylko dla płatności ze stałym adresem operatora.
• URL Pattern - używaj, gdy wystarczy wzorzec URL z placeholderami {order_id}, {order_increment_id}, {store_id} lub {quote_id}.
• Adapter Required - używaj dla bramek, które generują dynamiczny URL transakcji. Przed uruchomieniem na produkcji trzeba dodać dedykowany adapter dla konkretnego modułu płatności.

Konfiguracja multistore

Konfiguruj moduł na poziomie store view, jeżeli sklepy różnią się:

• językiem;
• walutą;
• feedem reklamowym;
• atrybutem identyfikatora produktu;
• atrybutem brandu;
• strukturą kategorii;
• metodami płatności.

Weryfikacja wdrożenia

1. Otwórz Google Tag Manager Preview.
2. Sprawdź dataLayer w konsoli przeglądarki albo rozszerzeniem DataLayer Checker.
3. Przetestuj stronę produktu i event view_item.
4. Otwórz kategorię lub wyniki wyszukiwania i sprawdź view_item_list.
5. Kliknij produkt na liście i sprawdź select_item.
6. Dodaj produkt do koszyka i sprawdź add_to_cart.
7. Zmień ilość lub usuń produkt z koszyka i sprawdź remove_from_cart.
8. Dodaj produkt do wishlisty i sprawdź add_to_wishlist.
9. Wejdź do koszyka i checkoutu, sprawdź view_cart oraz begin_checkout.
10. Zapisz metodę dostawy i płatności, sprawdź add_shipping_info oraz add_payment_info.
11. Złóż zamówienie testowe i sprawdź purchase.
12. Odśwież stronę sukcesu i upewnij się, że purchase nie duplikuje się.
13. Sprawdź var/log/kowal_datalayer.log.

Integracja purchase_test

Jeżeli metoda płatności przekierowuje klienta poza sklep i zna docelowy URL operatora, integracja płatności może użyć:

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

Metoda zwraca URL strony pośredniej modułu. Strona pośrednia wysyła purchase_test, a następnie przekierowuje klienta do operatora płatności. Jeśli JavaScript lub DataLayer nie zadziała, przekierowanie nadal powinno zostać wykonane.

Dla integracji, w której URL zależy od zamówienia albo tokenu transakcji, użyj:

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

Jeżeli metoda jest ustawiona w trybie Adapter Required, adapter powinien implementować:

Kowal\DataLayer\Api\PurchaseTestRedirectAdapterInterface

Adapter należy zarejestrować w DI jako element tablicy adapters dla Kowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. Adapter jest właściwym miejscem na logikę zależną od konkretnego operatora płatności.