Ultimate Cart Recovery - Guide utilisateur (FR)

Récupérez les paniers abandonnés sur Adobe Commerce / Magento Open Source grâce à des séquences multicanales automatisées (email, SMS, WhatsApp, webhook), des coupons dynamiques, des campagnes de win-back et un tableau de bord du chiffre d'affaires récupéré.

• Compatibilité : Magento 2.4.6 / 2.4.7+, PHP 8.1 / 8.2 / 8.3, Luma + Hyvä.
• Licence : 1 domaine de production par licence (les environnements de dev/staging sont gratuits et ne consomment pas la licence).

Ce guide couvre l'utilisation quotidienne du module côté marchand. Pour l'installation détaillée, voir Installation ou le guide d'installation Marketplace. Pour étendre le module (canaux personnalisés, événements), voir le guide développeur.

1. Installation rapide

Via Composer (recommandé)

composer require visicrea/module-ultimate-cart-recovery
bin/magento module:enable Visicrea_UltimateCartRecovery
bin/magento setup:upgrade
bin/magento setup:di:compile        # mode production uniquement
bin/magento cache:flush

Via package (.zip)

Décompressez l'archive dans app/code/Visicrea/UltimateCartRecovery, puis lancez la même séquence module:enable → setup:upgrade → cache:flush.

Vérifiez l'activation :

bin/magento module:status Visicrea_UltimateCartRecovery

2. Activation de la licence

1. Achetez une licence sur le portail Visicrea - vous recevez une clé au format VCR-XXXX-XXXX-XXXX-XXXX.
2. Saisissez-la dans Stores → Configuration → Visicrea → Ultimate Cart Recovery → License (champs « License server URL » et « License key »). L'activation se fait via cet écran de configuration ; il n'existe pas de commande CLI dédiée à l'activation en V1.
3. Le module vérifie la licence une fois toutes les 24 h (cron ValidateLicense). Si le serveur est injoignable, une période de grâce de 7 jours s'applique, suivie d'une bannière croissante pendant 30 jours. Au-delà, l'envoi des messages est désactivé (le tableau de bord et les données restent consultables). Les hôtes de dev/staging (dev, staging, preprod, test, local, localhost, ou le mode developer) ne consomment jamais la licence.

Vous pouvez consulter l'état de la licence à tout moment :

bin/magento ucr:debug:license

3. Assistant de configuration (Setup Wizard)

À la première ouverture d'Ultimate Cart Recovery dans l'admin (tant que wizard_completed = 0), un assistant en 8 étapes vous guide :

1. Licence - saisie et validation de votre clé.
2. Périmètre boutique - quelles vues de boutique sont actives.
3. Expéditeurs - identité d'expéditeur, réglages Mailgun/SMTP.
4. Canaux - activation de l'email et, en option, du SMS/WhatsApp/webhook.
5. Règle - création de votre première séquence de relance.
6. Cron - confirmation que le cron Magento tourne (un contrôle de santé non bloquant est exécuté).
7. Test - envoi d'un véritable email de test à l'adresse de votre choix.
8. Fin - validation et passage en production.

Vous pouvez relancer la configuration à tout moment via Stores → Configuration ou rouvrir l'assistant depuis le menu Visicrea → Setup Wizard.

4. Fonctionnement de la détection

Trois crons (toutes les 10 minutes) animent le pipeline :

• DetectAbandonedCarts signale les paniers (quote) restés inactifs au-delà de votre seuil et insère une ligne dans la table de tracking.
• ProcessSequences évalue vos règles et envoie l'étape arrivée à échéance.
• CheckConversions rapproche le panier d'une commande passée dans la fenêtre d'attribution (7 jours par défaut) et enregistre le chiffre d'affaires récupéré.

Trois crons quotidiens complètent le dispositif : DetectInactiveCustomers (win-back), CleanupExpiredCoupons (purge des coupons expirés), PurgeOldData (rétention) et ValidateLicense.

Mode dry-run (Ultimate Cart Recovery → General → Dry-run mode) : exécute tout le pipeline sans envoyer quoi que ce soit - idéal pour valider vos règles en toute sécurité. Les messages sont journalisés en queued puis jamais avancés.

5. Création de règles de relance

Sous Ultimate Cart Recovery → Rules :

• Déclencheur & conditions - ciblez selon le montant du panier, le groupe client, la boutique, la devise, la langue, le statut « invité », etc.
• Étapes (1 à 5) - chaque étape porte un canal, un délai (ex. +1 h, +24 h, +72 h), un template et un coupon optionnel.
• Priorité - lorsque plusieurs règles correspondent, c'est la priorité la plus élevée qui l'emporte.

Arbre de conditions

Les conditions sont stockées en JSON (conditions_serialized). Champs autorisés : cart_total, initial_cart_total, cart_items_count, currency_code, language_code, is_guest, customer_id, store_id, status, current_step. Opérateurs : eq, neq, gteq, lteq, gt, lt, in, nin, contains. Tout champ hors de cette liste blanche est évalué à false (sécurité par défaut).

Variables de template

Les variables disponibles dans les templates incluent {{customer_firstname}}, {{cart_items}}, {{cart_total}}, {{restore_url}}, {{coupon.code}} et {{unsubscribe_url}} (la liste complète figure dans l'éditeur de template).

Le délai (delay_minutes) est compté depuis l'heure d'envoi de l'étape précédente (étapes 2 à 5) ou depuis first_seen_at (étape 1).

6. Canaux

• Email - s'appuie sur l'email transactionnel de Magento. Le suivi d'ouverture (pixel) et le suivi de clic (redirections signées en HMAC) sont intégrés.
• SMS / WhatsApp - via Twilio ou Brevo ; renseignez les identifiants de votre provider (stockés chiffrés via EncryptorInterface). Un plafond journalier protège contre les dérives de coûts.
• Webhook - POST de charges utiles signées (X-Visicrea-Signature) vers votre propre endpoint, pour des canaux sur mesure.

Tester rapidement l'envoi SMS :

bin/magento ucr:test:sms

7. Coupons

Une règle peut attacher un coupon généré dynamiquement (format VCR{tracking_id}-{hex}), construit sur une règle de prix panier (Cart Price Rule) Magento existante. Lorsque use_coupon = 1, l'étape doit pointer vers un coupon_sales_rule_id ; le module crée un code par couple (tracking_id, step_id). Le champ coupon_validity_hours fixe l'expiration. Les coupons expirés sont purgés chaque jour par CleanupExpiredCoupons - uniquement ceux préfixés VCR, jamais les autres codes du marchand partageant la même règle.

bin/magento ucr:cleanup-coupons   # forcer la purge à la demande

8. RGPD

• Désinscription en un clic via /abandoned-cart/unsubscribe/{token} ; la liste de désinscription n'est jamais purgée et est consultée avant chaque envoi.
• Export / effacement des données : bash bin/magento ucr:export:gdpr client@exemple.com bin/magento ucr:delete:gdpr client@exemple.com Après effacement, l'email reste dans la table de désinscription (conservation légale) mais sa source est marquée gdpr_deletion.
• Rétention configurable : le cron PurgeOldData supprime les anciens journaux (12 mois par défaut) ; les enregistrements de désinscription sont conservés.
• Principe de minimisation : en cas de doute sur une donnée à journaliser, le module ne la journalise pas.

9. Tableau de bord

Ultimate Cart Recovery → Dashboard affiche le chiffre d'affaires récupéré, le taux de conversion et la performance par canal (orientée CTR). Le revenu est enregistré dans la devise de base de la boutique, à partir du base_grand_total figé de la commande (montant réellement encaissé, cohérent avec les rapports de ventes natifs Magento).

10. Droits d'accès (ACL)

Trois niveaux, sous Ultimate Cart Recovery :

• Visicrea_UltimateCartRecovery::view - tableau de bord, grilles, logs (lecture).
• Visicrea_UltimateCartRecovery::manage - règles, templates, désinscriptions.
• Visicrea_UltimateCartRecovery::configure - Stores → Configuration.

11. Dépannage

Journaux : var/log/visicrea_ucr.log (et var/log/visicrea_ucr_debug.log en mode debug).

12. Support

Contact : florent@visicrea.fr. Indiquez vos versions Magento / PHP, la version du module, et l'extrait de log pertinent.