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.
• Uprawnienie do wykonania setup:upgrade, ponieważ moduł dodaje pola atrybucji do tabel quote i sales_order.
• Kontener webowy Google Tag Managera, jeśli sklep ma korzystać z gotowych eksportów integracji.
• Opcjonalnie: Kowal_CookieConsent, jeżeli sklep używa go do GTM i Consent Mode.

Instalacja Composerem

Dane dostępowe do repozytorium Composer (adres e-mail klienta i token licencyjny) otrzymasz e-mailem po zakupie. Są również dostępne w panelu klienta po zalogowaniu na kowal.store. Zastąp TWOJ_EMAIL_KLIENTA adresem e-mail swojego konta, a TWOJ_TOKEN otrzymanym tokenem. Polecenia wykonaj w katalogu głównym 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

Polecenie setup:upgrade tworzy kolumny:

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

Kolumny zawierają zserializowane dane first-touch i last-touch. Nie należy tworzyć ich ręcznie.

Aktualizacja istniejącej instalacji

Przed aktualizacją produkcji wykonaj kopię bazy danych zgodnie z procedurą projektu. Następnie zaktualizuj pakiet i schemat 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

W trybie produkcyjnym wykonaj ponownie kompilację DI i deployment statycznych assetów. Jest to wymagane między innymi dla nowego endpointu atrybucji, obserwatorów quote/order i zmian w skrypcie frontendowym.

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

Po aktualizacji uprawnień ACL administrator może potrzebować ponownego zalogowania do panelu, aby zobaczyć pozycję Data Layer > GTM Exports.

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.

Attribution

Capture First and Last Touch Attribution zapisuje źródło wejścia klienta w quote i zamówieniu. Zalecane ustawienie: Yes.

Ustawienie działa per store view. Po jego wyłączeniu moduł nie rejestruje nowych touchpointów. Dane zapisane wcześniej w istniejących zamówieniach pozostają w bazie.

Moduł rozpoznaje:

• parametry utm_source, utm_medium, utm_campaign, utm_id, utm_term, utm_content i utm_source_platform;
• typy click ID Google Ads, Microsoft Ads, Meta, TikTok, Pinterest, X i LinkedIn;
• wejścia z organicznych wyników wyszukiwania;
• zewnętrzne referrale;
• wejścia direct.

Zapisywane są first_touch i last_touch, czyli ostatnie źródło inne niż direct. Zwykłe przechodzenie między podstronami sklepu nie nadpisuje źródła. Referrale z adresów płatności, callbacków, returnów i stron sukcesu są pomijane, aby operator płatności nie został uznany za źródło sprzedaży.

Przechwytywanie działa dwutorowo:

• po stronie Magento dla standardowych, niecache'owanych wejść;
• przez lekki request przeglądarkowy dla stron obsługiwanych z FPC lub Varnish.

Dane są utrzymywane w sesji checkoutowej, zapisywane przy quote i kopiowane do order przed złożeniem zamówienia. Mechanizm obejmuje klasyczny frontend, checkout AJAX/REST oraz zamówienia tworzone z quote zawierającego już atrybucję.

Surowe wartości gclid, fbclid i pozostałych identyfikatorów kliknięć nie są zapisywane. Moduł zachowuje wyłącznie typ parametru, np. gclid, i wynikową klasyfikację źródła. Query stringi są usuwane z zapisywanego landing page i referrera.

Atrybucję można sprawdzić:

• na widoku zamówienia w sekcji Customer Attribution;
• w dataLayer we właściwości attribution eventu purchase;
• bezpośrednio w kolumnach kowal_attribution_first i kowal_attribution_last tabel quote oraz sales_order.

Przechwytywanie źródła należy uwzględnić w dokumentacji prywatności sklepu zgodnie z polityką wdrożenia. Moduł nie tworzy własnego długoterminowego identyfikatora użytkownika i nie zapisuje wartości click ID, ale przechowuje metadane kampanii oraz źródło zamówienia.

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.

GTM Export Identifiers

W tej sekcji wpisz identyfikatory usług, które mają zostać osadzone w generowanych plikach JSON:

Pola mogą być puste, jeżeli sklep nie korzysta z danej platformy. Zapis konfiguracji sprawdza format każdej uzupełnionej wartości. Przycisk eksportu sprawdza komplet wymagany tylko przez wybraną platformę, dlatego np. eksport GA4 nie wymaga konfiguracji Meta ani TikToka.

Po uzupełnieniu pól kliknij Save Config, a następnie odpowiedni przycisk Download ... JSON w polu Generate GTM Exports. Pobrany plik zawiera już finalne identyfikatory. Nie trzeba edytować zmiennych stałych po imporcie do GTM.

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;
• zasadami przechwytywania atrybucji;
• identyfikatorami usług używanymi w importowanych paczkach GTM.

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.
14. W nowym oknie prywatnym otwórz sklep z URL-em ?utm_source=test&utm_medium=cpc&utm_campaign=attribution_test.
15. Przejdź przez kilka podstron, dodaj produkt do koszyka i złóż zamówienie.
16. Na widoku zamówienia sprawdź sekcję Customer Attribution oraz attribution.first_touch i attribution.last_touch w evencie purchase.
17. Potwierdź, że first_touch.source ma wartość test, medium ma wartość cpc, a campaign ma wartość attribution_test.
18. W tym samym oknie i sesji wróć do sklepu z innego oznaczonego źródła i potwierdź, że first_touch pozostał bez zmian, a last_touch został zaktualizowany.
19. Jeżeli sklep używa zewnętrznej bramki, potwierdź po powrocie z płatności, że domena operatora nie zastąpiła źródła zamówienia.

Eksport konfiguracji Google Tag Managera

W panelu Magento przejdź do Stores > Configuration > Kowal > Kowal Data Layer > GTM Export Identifiers. Dostępne są osobne paczki dla GA4, Google Ads, Meta, TikTok, Pinterest i Microsoft Ads.

1. Wybierz właściwy zakres konfiguracji: Default Config, website albo store view.
2. Uzupełnij identyfikatory używanych platform i zapisz konfigurację.
3. Kliknij przycisk pobrania JSON wybranej platformy w polu Generate GTM Exports.
4. W GTM utwórz nowy workspace i wybierz Admin > Import Container.
5. Wskaż pobrany plik i użyj trybu Merge.
6. Przejrzyj listę dodawanych zmiennych, reguł i tagów oraz potwierdź, że zmienne stałe zawierają właściwe identyfikatory.
7. Sprawdź wymagania zgód i uruchom GTM Preview.
8. Opublikuj kontener dopiero po potwierdzeniu eventów w narzędziu diagnostycznym platformy.

Nazwy elementów są poprzedzone prefiksem Kowal - nazwa platformy, dzięki czemu paczki można łączyć w jednym kontenerze. Event purchase_test nie jest eksportowany jako konwersja; sprzedaż jest raportowana wyłącznie przez purchase.

Jeżeli wymagane pole jest puste albo ma nieprawidłowy format, moduł nie wygeneruje eksportu i wyświetli komunikat ze wskazaniem wartości do poprawy. Zapobiega to przypadkowemu importowi kontenera z placeholderem. Alternatywna strona Kowal > Data Layer > GTM Exports pozostaje dostępna, ale korzysta z wartości z zakresu Default Config; do wdrożeń multistore zalecane są przyciski w konfiguracji.

Eksporty dotyczą kontenera webowego i wysyłki browser-side. Nie zastępują integracji serwerowych, takich jak Meta Conversions API lub TikTok Events API.

Zgody i publikacja GTM

• Tagi reklamowe wymagają ad_storage, ad_user_data i ad_personalization.
• GA4 korzysta z wbudowanych mechanizmów zgód Google tagu.
• Jeśli GTM renderuje Kowal_CookieConsent, pozostaw Render GTM From DataLayer Module ustawione na No.
• Nie publikuj kontenera bez sprawdzenia Consent Mode, GTM Preview oraz diagnostyki eventów właściwej platformy.
• Przy restrykcyjnym CSP dodaj domeny skryptów i endpointów wybranych platform zgodnie z ich dokumentacją.

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.

Diagnostyka

Brak sekcji Customer Attribution na zamówieniu

1. Sprawdź, czy Capture First and Last Touch Attribution jest włączone dla właściwego store view.
2. Potwierdź wykonanie php bin/magento setup:upgrade i obecność czterech kolumn atrybucji.
3. Wyczyść cache konfiguracji i layoutu.
4. Wykonaj test w nowym oknie prywatnym z oznaczonym URL-em UTM.
5. Sprawdź var/log/kowal_datalayer.log pod kątem komunikatów attribution capture failed lub attribution assignment failed.

Atrybucja działa bez FPC, ale nie działa z Varnish

1. Sprawdź w narzędziach deweloperskich request POST do kowal_datalayer/attribution/capture.
2. Potwierdź, że request ma status 200 i jest wykonywany do tej samej domeny sklepu.
3. Sprawdź, czy CSP, WAF albo reguły reverse proxy nie blokują endpointu.
4. Po deploymentcie upewnij się, że został opublikowany aktualny plik view/frontend/web/js/data-layer.js.

Zakup ma błędne źródło operatora płatności

Sprawdź, czy zamówienie powstało z quote zawierającego atrybucję przed przekierowaniem. Trasy zawierające payment, callback, return lub success nie powinny nadpisywać last-touch referralem. Jeżeli niestandardowy moduł płatności używa innej sekwencji, zweryfikuj moment utworzenia order i zapisu quote.

Import GTM zgłasza konflikty

Użyj trybu Merge i przejrzyj szczegóły zmian. Elementy eksportów mają prefiks Kowal - ...; jeśli w kontenerze istnieją zmodyfikowane elementy o tej samej nazwie, wybierz świadomie nadpisanie albo zmianę nazwy. Po zmianie nazw sprawdź referencje tagów do zmiennych i triggerów.