Instructions de configuration de Kowal Analytics

Navigation dans le panneau d’administration

Principaux points d’entrée du module :

• Kowal -> Analytics -> Dashboard
• Stores -> Configuration -> Analytics

Structure de la configuration

Actuellement, le module propose trois principaux groupes de paramètres.

1. General

Chemin :

• Stores -> Configuration -> Analytics -> General

Champ :

• Enable Analytics

Signification :

• active ou désactive le tracking frontend et le traitement analytics ultérieur pour le scope sélectionné.

Recommandation :

• il est préférable de l’activer par store view après avoir vérifié le bon fonctionnement des trackers et des consumers.

2. Debug

Chemin :

• Stores -> Configuration -> Analytics -> Debug

Champs :

• Enable Backend Debug Log
• Enable Frontend Console Log

Signification :

• backend debug enregistre les logs techniques dans :
  • var/log/kowal_analytics_debug.log
• frontend debug enregistre les logs du tracker dans la console du navigateur.

Utilisation :

• installation,
• QA,
• analyse des erreurs,
• tests du selector assistant,
• confirmation que les événements arrivent dans le pipeline.

Recommandation :

• l’activer pendant le déploiement et les tests,
• le désactiver sur l’environnement de production après la validation.

3. Tools

Chemin :

• Stores -> Configuration -> Analytics -> Tools

Champ :

• Enable Frontend Selector Assistant

Signification :

• affiche un helper sur le storefront qui aide à indiquer et préparer la configuration des area personnalisées basées sur des sélecteurs.

Utilisation :

• mapping de custom section,
• analyse de la structure DOM,
• préparation des définitions d’area sans modification manuelle du code.

Comment comprendre la configuration en pratique

Scope

Le module fonctionne dans le scope Magento, la configuration peut donc être différente pour :

• default,
• website,
• store view.

Le plus sûr est de considérer le module comme un outil par store view, car :

• différentes boutiques peuvent avoir un layout différent,
• différentes boutiques peuvent avoir d’autres sections de blog, de CMS et de merchandising,
• les rapports par store view sont beaucoup plus fiables sur le plan opérationnel.

Comment comprendre les notions de base du module

Area

Area est une zone délimitée de la page que vous souhaitez mesurer comme source d’influence sur les ventes.

Exemples :

• related_products
• upsell_products
• crosssell_products
• category_listing
• search_results
• wishlist_products
• compare_products
• blog_post_listing
• blog_sidebar_categories
• homepage_promo_box

Object

Object est un élément précis à l’intérieur d’une area.

Exemples :

• un produit individuel dans une liste,
• un article de blog,
• une catégorie de blog,
• un tag,
• une bannière,
• une slide.

Source Page

Source Page est la page depuis laquelle l’utilisateur a effectué une interaction menant ensuite à une vente.

Exemples :

• fiche du produit source pour related_products,
• article de blog pour un produit cliqué,
• listing de catégorie pour un produit cliqué,
• résultats de recherche pour un produit.

Dashboard et rapports

Analytics Dashboard

C’est l’écran principal de synthèse. Il affiche :

• attributed revenue,
• attributed orders,
• average order value,
• CTR,
• top areas,
• top supported products,
• top blog sources,
• des liens vers les rapports détaillés.

Cet écran répond à la question :

• co działa najlepiej

Area Report

Ce rapport répond aux questions :

• quelle area génère du chiffre d’affaires,
• quels object dans cette area vendent,
• de quelles source page proviennent les ventes.

Exemple :

• related_products compte 18 commandes,
• Zing Jump Rope y est le produit qui se vend le mieux,
• la source la plus fréquente de ce parcours est la fiche produit Affirm Water Bottle.

Product Context Report

C’est un rapport pour les zones produit telles que :

• related_products
• upsell_products
• crosssell_products
• category_listing
• search_results

Il montre la relation :

• source product -> clicked object -> purchased SKU

Exemple :

• l’utilisateur se trouve sur la PDP Affirm Water Bottle,
• il clique sur WB05-S-Orange dans related_products,
• il achète WB05-S-Orange.

Blog Commerce Report

C’est un rapport pour les zones de blog :

• blog_post_listing
• blog_recent_posts_widget
• blog_sidebar_recent_posts
• blog_sidebar_categories
• blog_sidebar_tags
• blog_post_view

Il répond aux questions :

• quel post vend,
• quelle catégorie de blog vend,
• quel tag soutient les ventes,
• quels SKU sont achetés après une entrée depuis le blog.

Object Report

C’est un rapport pour un object précis.

Exemple :

• un produit dans related_products,
• un article de blog de blog_post_listing,
• une catégorie de blog de blog_sidebar_categories.

Il affiche :

• le nombre d’impressions,
• le nombre de clics,
• le nombre de commandes générées,
• le chiffre d’affaires qui lui a été attribué,
• les source page d’où provenaient ces parcours.

Source Page Report

C’est un rapport pour une page source précise.

Exemple :

• fiche produit Affirm Water Bottle,
• article de blog Jak wybrać bidon treningowy,
• listing de catégorie Buty do biegania.

Il affiche :

• quels clicked object depuis cette page vendent,
• quels SKU sont achetés après une entrée depuis cette page,
• combien de commandes et de chiffre d’affaires cette page précise génère comme point de départ du parcours.

Modèles d’attribution

Modèles disponibles :

• Last Click
• First Click
• Assisted
• View Through

Comment les lire :

Last Click

Idéal pour répondre à la question :

• quel élément a directement conclu la vente.

First Click

Idéal pour répondre à la question :

• quel élément a lancé le parcours menant à l’achat.

Assisted

Idéal pour répondre à la question :

• quel élément a participé au parcours, même s’il n’était pas le dernier clic.

View Through

Idéal pour répondre à la question :

• si la simple exposition de la section a eu un impact sur les ventes, même sans clic.

Configuration d’une custom area

Vous pouvez préparer une custom area avec Frontend Selector Assistant.

Workflow typique :

1. Activez Enable Frontend Selector Assistant.
2. Ouvrez le storefront.
3. Lancez l’assistant.
4. Indiquez la zone.
5. Vérifiez le container selector proposé.
6. Vérifiez le item selector proposé.
7. Vérifiez le link selector.
8. Enregistrez la définition.
9. Confirmez que runtime apply a ajouté data-kowal-track-*.
10. Testez le clic et le passage aux rapports.

Exemple de custom area

Supposons que votre page d’accueil dispose d’un box promotionnel avec trois tuiles.

Vous pouvez définir :

• area_code = homepage_promo_box
• object_type = promotion
• container_selector = .homepage-promo
• item_selector = .homepage-promo__item
• link_selector = .homepage-promo__link

Le rapport affichera alors :

• quelle tuile a été cliquée,
• laquelle a mené à un achat,
• quel chiffre d’affaires elle a généré.

Workflow de test après configuration

L’ordre le plus pertinent :

1. activer analytics,
2. activer backend debug,
3. activer frontend console log,
4. parcourir un scénario utilisateur,
5. vérifier le dashboard,
6. vérifier le rapport area,
7. descendre jusqu’à l’object report ou au source page report,
8. désactiver le debug après confirmation du bon fonctionnement.

Recommandations opérationnelles

• maintenez les consumers sous supervisor ou systemd,
• assurez-vous que Magento cron fonctionne en continu,
• après des changements de thème, vérifiez que les sélecteurs des custom area correspondent toujours au DOM,
• après des changements de merchandising, comparez les résultats par area,
• n’interprétez pas le CTR seul comme un succès sans vérifier le chiffre d’affaires et les commandes.

Instructions d’installation de Kowal Analytics

Prérequis

Avant l’installation, assurez-vous que :

• l’instance Magento 2 fonctionne correctement,
• Composer a accès au dépôt de packages Kowal,
• vous disposez d’un accès CLI à bin/magento,
• l’environnement permet d’exécuter cron et les queue consumers,
• l’environnement écrit correctement dans la base de données et dans var/log.

Installation via Composer

Ajoutez le dépôt Composer :

Les identifiants d’accès au dépôt Composer, à savoir l’adresse e-mail du client et le token de licence, vous seront envoyés par e-mail après l’achat. Ils sont également disponibles dans l’espace client après connexion sur kowal.store. Remplacez TWOJ_EMAIL_KLIENTA par l’adresse e-mail de votre compte et TWOJ_TOKEN par le token reçu. Exécutez les commandes dans le répertoire racine de Magento.

composer config repositories.kowal composer https://repo.kowal.store

Ajoutez les identifiants d’accès au dépôt privé :

composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

Installez le module :

composer require kowal/module-analytics

Activation du module

Exécutez les commandes Magento standard :

bin/magento module:enable Kowal_Analyticsbin/magento setup:upgradebin/magento cache:flush

Si la boutique fonctionne en production mode, exécutez également :

bin/magento setup:di:compilebin/magento setup:static-content:deploy -fbin/magento cache:flush

Lancement des processus asynchrones

Le module utilise des files d’attente et un traitement asynchrone. Sans cela, le dashboard et les rapports ne seront pas complets.

Lancez les consumers requis :

bin/magento queue:consumers:start kowal_analytics.raw_eventsbin/magento queue:consumers:start kowal_analytics.conversionbin/magento queue:consumers:start kowal_analytics.attribution

Magento cron doit également fonctionner correctement, car le module utilise retry et backfill pour l’attribution.

Contrôle de base :

bin/magento cron:run

Que se passe-t-il après l’installation ?

Après une installation correcte, le module :

• charge le tracker sur le storefront,
• enregistre les événements frontend,
• associe la session analytics à quote,
• transfère les identifiants analytics vers sales_order,
• enregistre les conversions et les lignes de conversion,
• calcule l’attribution des commandes aux area et object,
• met à disposition un dashboard et des rapports détaillés dans le panneau Magento.

Où vérifier que le module fonctionne ?

Après l’installation, vérifiez :

• Kowal -> Analytics -> Dashboard
• Stores -> Configuration -> Analytics

Si le module est correctement actif, vous devriez voir :

• le dashboard du module,
• le widget de synthèse sur le dashboard natif de Magento,
• la section de configuration dans Stores -> Configuration.

Test technique recommandé après déploiement

Effectuez un test end-to-end simple :

1. Ouvrez la page de la boutique.
2. Accédez à une fiche produit.
3. Cliquez sur un élément tracké, par exemple un produit dans related_products ou un article de blog.
4. Ajoutez le produit au panier.
5. Passez commande.
6. Vérifiez que les événements, les conversions et l’attribution ont été enregistrés.

Si le debug est activé, vérifiez :

• les logs dans la console du navigateur,
• var/log/kowal_analytics_debug.log

Ce qu’il est utile de vérifier dans le HTML

Si vous souhaitez confirmer que le tracking fonctionne au rendu de la page, vérifiez la présence des attributs :

• data-kowal-track-area
• data-kowal-track-area-id
• data-kowal-track-object
• data-kowal-track-id
• data-kowal-track-sku

Exemple :

• le conteneur de la section related_products doit avoir data-kowal-track-area='related_products'
• un produit individuel dans cette section doit avoir data-kowal-track-object='product' et son propre data-kowal-track-id

Problèmes typiques après l’installation

Le dashboard est visible, mais il n’y a pas de données

Vérifiez :

• si les consumers fonctionnent,
• si cron fonctionne,
• si analytics est activé dans la configuration,
• si le tracker se charge sur le frontend,
• si la page contient réellement des area trackées.

Les événements sont enregistrés, mais l’attribution est incomplète

Vérifiez :

• si le consumer kowal_analytics.attribution fonctionne,
• si cron retry fonctionne,
• si les événements sources arrivent dans la base avant le recalcul final de l’attribution.

La custom area n’apparaît pas dans les rapports

Vérifiez :

• si la définition de l’area a été correctement enregistrée,
• si les sélecteurs correspondent au DOM réel,
• si runtime apply ajoute data-kowal-track-*,
• si la zone dispose des identifiants d’objets nécessaires à l’analyse ultérieure.

Recommandation de déploiement

L’ordre le plus sûr est le suivant :

1. installer le module,
2. lancer les consumers et cron,
3. activer le debug,
4. tester un scénario produit simple,
5. vérifier le dashboard,
6. puis seulement étendre le tracking aux custom area.