Istruzioni di installazione e configurazione

Requisiti

• Magento Open Source / Adobe Commerce 2.4.x.
• PHP compatibile con la versione di Magento in uso.
• Accesso Composer al repository privato del modulo.
• Modulo kowal/base.
• Opzionale: Kowal_CookieConsent, se il negozio lo utilizza per GTM e Consent Mode.

Installazione con 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

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

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

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 - abilitalo solo durante i test e la verifica dell’implementazione.
3. Render Mode - lascia Server and JavaScript, se non c’è motivo di 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 le vendite restano protetti anche dopo la disattivazione di questa opzione.
7. Log Level - in produzione è consigliato Errors only.
8. Log Payloads - abilitalo solo temporaneamente.

Product Mapping

1. Product Identifier Attribute - seleziona l’attributo usato come item_id. Predefinito sku.
2. Brand Attribute - seleziona l’attributo produttore/brand. Predefinito manufacturer.
3. Category Strategy - seleziona il metodo di costruzione di item_category.
4. Category Attribute - impostalo solo se la strategia di categoria utilizza un attributo del 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 il negozio 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’email. L’email in chiaro non viene inserita in dataLayer.

Integrations

1. Integrate With Kowal Cookie Consent - abilitalo se il negozio 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 - impostalo solo se il rendering di GTM da questo modulo è abilitato.
4. purchase_test Redirect Rules - aggiungi solo quei metodi di pagamento che devono usare la pagina intermedia purchase_test.

Modalità delle regole purchase_test:

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

Configurazione multistore

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

• lingua;
• valuta;
• feed pubblicitario;
• attributo identificativo del prodotto;
• attributo brand;
• struttura delle categorie;
• metodi di pagamento.

Verifica dell’implementazione

1. Apri Google Tag Manager Preview.
2. Controlla dataLayer nella console del browser oppure 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. Clicca 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 il metodo di spedizione e di pagamento, controlla add_shipping_info e add_payment_info.
11. Effettua un ordine di test e controlla purchase.
12. Ricarica la pagina di successo e assicurati che purchase non si duplichi.
13. Controlla var/log/kowal_datalayer.log.

Integrazione purchase_test

Se il metodo di pagamento reindirizza il cliente fuori dal negozio e conosce l’URL finale 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 funzionano, il reindirizzamento dovrebbe comunque essere eseguito.

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

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

Se il metodo è impostato in modalità Adapter Required, l’adapter dovrebbe 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.