Kowal Data Layer per Magento 2

Istruzioni di installazione e configurazione

Requisiti

• Magento Open Source / Adobe Commerce 2.4.x.
• PHP compatibile con la versione Magento utilizzata.
• Accesso Composer al repository privato del modulo.
• Modulo kowal/base.
• Autorizzazione a eseguire setup:upgrade, perché il modulo aggiunge campi di attribuzione alle tabelle quote e sales_order.
• Container web Google Tag Manager, se lo store deve utilizzare esportazioni di integrazione pronte.
• Opzionale: Kowal_CookieConsent, se lo store lo utilizza per GTM e Consent Mode.

Installazione con Composer

I dati di accesso al repository Composer, indirizzo e-mail del cliente e token di licenza, vengono inviati via e-mail dopo l'acquisto. Sono disponibili anche nel pannello cliente dopo l'accesso a kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l'indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory principale di 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

Il comando setup:upgrade crea le colonne:

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

Le colonne contengono dati first-touch e last-touch serializzati. Non devono essere create manualmente.

Aggiornamento di un'installazione esistente

Prima di aggiornare la produzione, esegui un backup del database secondo la procedura del progetto. Quindi aggiorna il pacchetto e lo 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

In modalità produzione, esegui di nuovo la compilazione DI e il deployment degli asset statici. È necessario, tra l'altro, per il nuovo endpoint di attribuzione, gli observer quote/order e le modifiche nello script frontend.

In ambiente di produzione, se il progetto lo richiede, esegui il deployment Magento standard:

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

Dopo l'aggiornamento delle autorizzazioni ACL, l'amministratore potrebbe dover accedere nuovamente al pannello per vedere la voce Data Layer > GTM Exports.

Configurazione di base

Pannello di amministrazione:

Stores > Configuration > Kowal > Kowal Data Layer

Menu:

kowal.store > Modules > Data Layer > Settings

General

1. Enable Module - abilita il modulo per l'ambito di configurazione selezionato.
2. Debug Mode - abilita solo durante i test e la verifica dell'implementazione.
3. Render Mode - lascia Server and JavaScript, se non ci sono motivi per limitare la modalità di funzionamento.
4. Missing Value Strategy - scegli se i valori mancanti devono essere omessi o inviati come undefined.
5. Clear Ecommerce Before Push - consigliato Yes.
6. Fail-safe Mode - consigliato Yes; i processi critici per la vendita restano protetti anche dopo la disattivazione di questa opzione.
7. Log Level - in produzione consigliato Errors only.
8. Log Payloads - abilita solo temporaneamente.

Product Mapping

1. Product Identifier Attribute - scegli l'attributo usato come item_id. Predefinito sku.
2. Brand Attribute - scegli l'attributo produttore/brand. Predefinito manufacturer.
3. Category Strategy - scegli il metodo di costruzione di item_category.
4. Category Attribute - imposta solo quando la strategia categoria utilizza l'attributo prodotto.
5. Configurable Product Strategy - decidi se usare i dati del child/simple o del parent/configurable.
6. Include Out Of Stock Products On Lists - riguarda gli eventi delle liste prodotto.

Events

Abilita gli eventi richiesti dall'implementazione:

• 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, se lo store utilizza una pagina intermedia prima del pagamento.

Privacy

1. Send User ID - invia l'ID cliente Magento per i clienti autenticati.
2. Send Hashed Email - invia solo l'hash SHA-256 dell'e-mail. L'e-mail grezza non arriva in dataLayer.

Attribution

Capture First and Last Touch Attribution salva la fonte di ingresso del cliente nella quote e nell'ordine. Impostazione consigliata: Yes.

L'impostazione funziona per store view. Dopo la sua disattivazione, il modulo non registra nuovi touchpoint. I dati salvati in precedenza negli ordini esistenti restano nel database.

Il modulo riconosce:

• parametri utm_source, utm_medium, utm_campaign, utm_id, utm_term, utm_content e utm_source_platform;
• tipi di click ID Google Ads, Microsoft Ads, Meta, TikTok, Pinterest, X e LinkedIn;
• accessi dai risultati organici di ricerca;
• referral esterni;
• accessi direct.

Vengono salvati first_touch e last_touch, cioè l'ultima fonte diversa da direct. La normale navigazione tra le sottopagine dello store non sovrascrive la fonte. I referral da indirizzi di pagamento, callback, return e pagine di successo vengono ignorati, in modo che l'operatore di pagamento non venga considerato fonte della vendita.

La cattura funziona su due livelli:

• lato Magento per accessi standard non cache;
• tramite una richiesta leggera del browser per pagine servite da FPC o Varnish.

I dati vengono mantenuti nella sessione di checkout, salvati nella quote e copiati nell'order prima dell'invio dell'ordine. Il meccanismo copre il frontend classico, il checkout AJAX/REST e gli ordini creati da una quote che contiene già l'attribuzione.

I valori grezzi gclid, fbclid e degli altri identificatori di clic non vengono salvati. Il modulo conserva solo il tipo di parametro, ad esempio gclid, e la classificazione risultante della fonte. Le query string vengono rimosse dalla landing page e dal referrer salvati.

L'attribuzione può essere controllata:

• nella vista ordine, nella sezione Customer Attribution;
• in dataLayer, nella proprietà attribution dell'evento purchase;
• direttamente nelle colonne kowal_attribution_first e kowal_attribution_last delle tabelle quote e sales_order.

La cattura della fonte deve essere inclusa nella documentazione sulla privacy dello store secondo la policy di implementazione. Il modulo non crea un proprio identificatore utente a lungo termine e non salva i valori click ID, ma conserva i metadati della campagna e la fonte dell'ordine.

Integrations

1. Integrate With Kowal Cookie Consent - abilita se lo store utilizza Kowal_CookieConsent.
2. Render GTM From DataLayer Module - lascia No, se GTM è già renderizzato da Cookie Consent o da un altro modulo.
3. Google Tag Manager ID - imposta solo quando il rendering GTM da questo modulo è abilitato.
4. purchase_test Redirect Rules - aggiungi solo i metodi di pagamento che devono utilizzare la pagina intermedia purchase_test.

Modalità delle regole purchase_test:

• Static URL - usa solo per pagamenti con indirizzo fisso dell'operatore.
• URL Pattern - usa quando è sufficiente un pattern URL con placeholder {order_id}, {order_increment_id}, {store_id} o {quote_id}.
• Adapter Required - usa per gateway che generano un URL di transazione dinamico. Prima dell'avvio in produzione è necessario aggiungere un adapter dedicato per lo specifico modulo di pagamento.

GTM Export Identifiers

In questa sezione inserisci gli identificatori dei servizi che devono essere incorporati nei file JSON generati:

I campi possono essere vuoti se lo store non utilizza una determinata piattaforma. Il salvataggio della configurazione controlla il formato di ogni valore compilato. Il pulsante di esportazione controlla il set richiesto solo dalla piattaforma selezionata, quindi ad esempio l'esportazione GA4 non richiede la configurazione di Meta né TikTok.

Dopo aver compilato i campi, fai clic su Save Config, quindi sul pulsante appropriato Download ... JSON nel campo Generate GTM Exports. Il file scaricato contiene già gli identificatori finali. Non è necessario modificare le variabili costanti dopo l'importazione in GTM.

Configurazione multistore

Configura il modulo a livello di store view se gli store differiscono per:

• lingua;
• valuta;
• feed pubblicitario;
• attributo identificatore prodotto;
• attributo brand;
• struttura delle categorie;
• metodi di pagamento;
• regole di cattura dell'attribuzione;
• identificatori dei servizi usati nei pacchetti GTM importati.

Verifica dell'implementazione

1. Apri Google Tag Manager Preview.
2. Controlla dataLayer nella console del browser o con l'estensione DataLayer Checker.
3. Testa la pagina prodotto e l'evento view_item.
4. Apri una categoria o i risultati di ricerca e controlla view_item_list.
5. Fai clic su un prodotto nella lista e controlla select_item.
6. Aggiungi un prodotto al carrello e controlla add_to_cart.
7. Modifica la quantità o rimuovi un prodotto dal carrello e controlla remove_from_cart.
8. Aggiungi un prodotto alla wishlist e controlla add_to_wishlist.
9. Entra nel carrello e nel checkout, controlla view_cart e begin_checkout.
10. Salva metodo di spedizione e pagamento, controlla add_shipping_info e add_payment_info.
11. Effettua un ordine di test e controlla purchase.
12. Aggiorna la pagina di successo e assicurati che purchase non venga duplicato.
13. Controlla var/log/kowal_datalayer.log.
14. In una nuova finestra privata apri lo store con l'URL ?utm_source=test&utm_medium=cpc&utm_campaign=attribution_test.
15. Naviga attraverso alcune sottopagine, aggiungi un prodotto al carrello ed effettua un ordine.
16. Nella vista ordine controlla la sezione Customer Attribution e attribution.first_touch e attribution.last_touch nell'evento purchase.
17. Conferma che first_touch.source abbia il valore test, medium abbia il valore cpc e campaign abbia il valore attribution_test.
18. Nella stessa finestra e sessione torna allo store da un'altra fonte contrassegnata e conferma che first_touch sia rimasto invariato, mentre last_touch sia stato aggiornato.
19. Se lo store utilizza un gateway esterno, conferma dopo il ritorno dal pagamento che il dominio dell'operatore non abbia sostituito la fonte dell'ordine.

Esportazione della configurazione Google Tag Manager

Nel pannello Magento vai a Stores > Configuration > Kowal > Kowal Data Layer > GTM Export Identifiers. Sono disponibili pacchetti separati per GA4, Google Ads, Meta, TikTok, Pinterest e Microsoft Ads.

1. Scegli l'ambito di configurazione corretto: Default Config, website o store view.
2. Completa gli identificatori delle piattaforme utilizzate e salva la configurazione.
3. Fai clic sul pulsante di download JSON della piattaforma selezionata nel campo Generate GTM Exports.
4. In GTM crea un nuovo workspace e scegli Admin > Import Container.
5. Seleziona il file scaricato e usa la modalità Merge.
6. Rivedi l'elenco di variabili, regole e tag aggiunti e conferma che le variabili costanti contengano gli identificatori corretti.
7. Controlla i requisiti di consenso e avvia GTM Preview.
8. Pubblica il container solo dopo aver confermato gli eventi nello strumento diagnostico della piattaforma.

I nomi degli elementi sono preceduti dal prefisso Kowal - nazwa platformy, così i pacchetti possono essere combinati in un unico container. L'evento purchase_test non viene esportato come conversione; le vendite sono riportate esclusivamente tramite purchase.

Se un campo richiesto è vuoto o ha un formato non valido, il modulo non genererà l'esportazione e mostrerà un messaggio con l'indicazione del valore da correggere. Questo impedisce l'importazione accidentale di un container con placeholder. La pagina alternativa Kowal > Data Layer > GTM Exports resta disponibile, ma utilizza i valori dell'ambito Default Config; per implementazioni multistore sono consigliati i pulsanti nella configurazione.

Le esportazioni riguardano il container web e l'invio browser-side. Non sostituiscono integrazioni server-side, come Meta Conversions API o TikTok Events API.

Consensi e pubblicazione GTM

• I tag pubblicitari richiedono ad_storage, ad_user_data e ad_personalization.
• GA4 utilizza i meccanismi di consenso integrati del tag Google.
• Se GTM renderizza Kowal_CookieConsent, lascia Render GTM From DataLayer Module impostato su No.
• Non pubblicare il container senza controllare Consent Mode, GTM Preview e la diagnostica eventi della piattaforma appropriata.
• Con CSP restrittiva, aggiungi i domini degli script e degli endpoint delle piattaforme selezionate secondo la loro documentazione.

Integrazione purchase_test

Se il metodo di pagamento reindirizza il cliente fuori dallo store e conosce l'URL di destinazione dell'operatore, l'integrazione di pagamento può usare:

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

Il metodo restituisce l'URL della pagina intermedia del modulo. La pagina intermedia invia purchase_test e poi reindirizza il cliente all'operatore di pagamento. Se JavaScript o DataLayer non funziona, il reindirizzamento dovrebbe comunque essere eseguito.

Per un'integrazione in cui l'URL dipende dall'ordine o dal token della transazione, usa:

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

Se il metodo è impostato in modalità Adapter Required, l'adapter deve implementare:

Kowal\DataLayer\Api\PurchaseTestRedirectAdapterInterface

L'adapter deve essere registrato in DI come elemento dell'array adapters per Kowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. L'adapter è il punto corretto per la logica dipendente da uno specifico operatore di pagamento.

Diagnostica

Sezione Customer Attribution mancante nell'ordine

1. Controlla che Capture First and Last Touch Attribution sia abilitato per la store view corretta.
2. Conferma l'esecuzione di php bin/magento setup:upgrade e la presenza delle quattro colonne di attribuzione.
3. Svuota la cache di configurazione e layout.
4. Esegui un test in una nuova finestra privata con URL UTM contrassegnato.
5. Controlla var/log/kowal_datalayer.log per messaggi attribution capture failed o attribution assignment failed.

L'attribuzione funziona senza FPC, ma non funziona con Varnish

1. Controlla negli strumenti per sviluppatori la richiesta POST a kowal_datalayer/attribution/capture.
2. Conferma che la richiesta abbia stato 200 e venga eseguita verso lo stesso dominio dello store.
3. Controlla se CSP, WAF o regole reverse proxy non bloccano l'endpoint.
4. Dopo il deployment assicurati che sia stato pubblicato il file aggiornato view/frontend/web/js/data-layer.js.

L'acquisto ha una fonte errata dell'operatore di pagamento

Controlla se l'ordine è stato creato da una quote contenente attribuzione prima del reindirizzamento. Le route contenenti payment, callback, return o success non dovrebbero sovrascrivere last-touch con un referral. Se un modulo di pagamento personalizzato utilizza una sequenza diversa, verifica il momento di creazione dell'order e del salvataggio della quote.

L'importazione GTM segnala conflitti

Usa la modalità Merge e rivedi i dettagli delle modifiche. Gli elementi delle esportazioni hanno il prefisso Kowal - ...; se nel container esistono elementi modificati con lo stesso nome, scegli consapevolmente se sovrascrivere o rinominare. Dopo la modifica dei nomi, controlla i riferimenti dei tag a variabili e trigger.