Guide d’installation et de configuration

Prérequis

• Magento Open Source / Adobe Commerce 2.4.x.
• PHP compatible avec la version de Magento utilisée.
• Accès Composer au dépôt privé du module.
• Module kowal/base.
• En option : Kowal_CookieConsent, si la boutique l’utilise pour GTM et Consent Mode.

Installation avec 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

En environnement de production, si le projet l’exige, exécutez le déploiement Magento standard :

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

Configuration de base

Panel d’administration :

Stores > Configuration > Kowal > Kowal Data Layer

Menu :

kowal.store > Modules > Data Layer > Settings

General

1. Enable Module - activez le module pour la portée de configuration sélectionnée.
2. Debug Mode - activez uniquement pendant les tests et la vérification du déploiement.
3. Render Mode - laissez Server and JavaScript, sauf s’il existe une raison de limiter le mode de fonctionnement.
4. Missing Value Strategy - choisissez si les valeurs manquantes doivent être ignorées ou envoyées comme undefined.
5. Clear Ecommerce Before Push - Yes recommandé.
6. Fail-safe Mode - Yes recommandé ; les processus critiques pour les ventes restent protégés même si cette option est désactivée.
7. Log Level - en production, Errors only recommandé.
8. Log Payloads - à activer uniquement temporairement.

Product Mapping

1. Product Identifier Attribute - choisissez l’attribut utilisé comme item_id. Par défaut sku.
2. Brand Attribute - choisissez l’attribut fabricant/marque. Par défaut manufacturer.
3. Category Strategy - choisissez la méthode de construction de item_category.
4. Category Attribute - à définir uniquement si la stratégie de catégorie utilise un attribut produit.
5. Configurable Product Strategy - décidez si vous souhaitez utiliser les données de l’enfant/simple ou du parent/configurable.
6. Include Out Of Stock Products On Lists - concerne les événements des listes de produits.

Events

Activez les événements requis pour l’implémentation :

• 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, si la boutique utilise une page intermédiaire avant le paiement.

Privacy

1. Send User ID - envoie l’ID client Magento pour les clients connectés.
2. Send Hashed Email - envoie uniquement le hash SHA-256 de l’email. L’email brut n’est pas envoyé dans dataLayer.

Integrations

1. Integrate With Kowal Cookie Consent - activez si la boutique utilise Kowal_CookieConsent.
2. Render GTM From DataLayer Module - laissez No si GTM est déjà rendu par Cookie Consent ou un autre module.
3. Google Tag Manager ID - à définir uniquement si le rendu de GTM depuis ce module est activé.
4. purchase_test Redirect Rules - ajoutez uniquement les méthodes de paiement qui doivent utiliser la page intermédiaire purchase_test.

Modes des règles purchase_test :

• Static URL - à utiliser uniquement pour les paiements avec une adresse opérateur fixe.
• URL Pattern - à utiliser lorsqu’un modèle d’URL avec les placeholders {order_id}, {order_increment_id}, {store_id} ou {quote_id} est suffisant.
• Adapter Required - à utiliser pour les passerelles qui génèrent une URL de transaction dynamique. Avant la mise en production, il faut ajouter un adaptateur dédié pour le module de paiement concerné.

Configuration multistore

Configurez le module au niveau du store view si les boutiques diffèrent par :

• la langue ;
• la devise ;
• le flux publicitaire ;
• l’attribut d’identifiant produit ;
• l’attribut de marque ;
• la structure des catégories ;
• les méthodes de paiement.

Vérification du déploiement

1. Ouvrez Google Tag Manager Preview.
2. Vérifiez dataLayer dans la console du navigateur ou avec l’extension DataLayer Checker.
3. Testez la page produit et l’événement view_item.
4. Ouvrez une catégorie ou les résultats de recherche et vérifiez view_item_list.
5. Cliquez sur un produit dans une liste et vérifiez select_item.
6. Ajoutez un produit au panier et vérifiez add_to_cart.
7. Modifiez la quantité ou supprimez un produit du panier et vérifiez remove_from_cart.
8. Ajoutez un produit à la wishlist et vérifiez add_to_wishlist.
9. Accédez au panier et au checkout, puis vérifiez view_cart et begin_checkout.
10. Enregistrez la méthode de livraison et de paiement, puis vérifiez add_shipping_info et add_payment_info.
11. Passez une commande de test et vérifiez purchase.
12. Rafraîchissez la page de succès et assurez-vous que purchase n’est pas dupliqué.
13. Vérifiez var/log/kowal_datalayer.log.

Intégration purchase_test

Si la méthode de paiement redirige le client hors de la boutique et connaît l’URL cible de l’opérateur, l’intégration de paiement peut utiliser :

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

La méthode renvoie l’URL de la page intermédiaire du module. Cette page intermédiaire envoie purchase_test, puis redirige le client vers l’opérateur de paiement. Si JavaScript ou DataLayer ne fonctionne pas, la redirection doit tout de même être exécutée.

Pour une intégration dans laquelle l’URL dépend de la commande ou du token de transaction, utilisez :

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

Si la méthode est définie en mode Adapter Required, l’adaptateur doit implémenter :

Kowal\DataLayer\Api\PurchaseTestRedirectAdapterInterface

L’adaptateur doit être enregistré dans le DI comme élément du tableau adapters pour Kowal\DataLayer\Model\PurchaseTest\RedirectAdapterPool. L’adaptateur est l’emplacement approprié pour la logique dépendante d’un opérateur de paiement spécifique.