dffreegift — Cadeau offert au seuil panier — Guide complet

Guide complet du module dffreegift pour PrestaShop 8 et 9 : installation, configuration, fonctionnement interne (CartRule native), personnalisation, dépannage et désinstallation. Toutes les étapes sont accompagnées de captures conceptuelles et des paramètres exacts à utiliser en production.

Aperçu

dffreegift ajoute automatiquement un produit cadeau au panier dès qu’un seuil configuré est atteint, et le retire si le panier redescend en dessous. La mécanique s’appuie intégralement sur le système natif CartRule de PrestaShop (champ gift_product) : le module ne manipule jamais directement les prix des produits, ne crée pas de SpecificPrice temporaire, et n’injecte rien dans les hooks de calcul de prix. Résultat : compatibilité complète avec vos autres promotions, codes promo, taxes et le multi-devise.

Le module affiche également un bloc de progression sur la page panier avec le message « Ajoutez X € pour recevoir votre cadeau », une barre colorée qui se remplit à mesure que le seuil approche, et une animation au franchissement.

Prérequis

• PrestaShop 8.0 à 9.x (testé sur 8.0, 8.1, 8.2, 9.0)
• PHP 8.1 minimum (8.2 et 8.3 supportées)
• Un produit actif dans votre catalogue qui servira de cadeau (produit simple ou avec déclinaisons)
• Accès administrateur au back office PrestaShop

Installation

1. Dans le back office, aller dans Modules → Gestionnaire de modules → Envoyer un module.
2. Uploader le fichier dffreegift-1.0.0.zip.
3. Cliquer sur Installer puis Configurer.

À l’installation, le module effectue les opérations suivantes en arrière-plan :

• Enregistrement de 5 hooks : actionCartSave, actionObjectCartRuleDeleteBefore, displayShoppingCart, displayCartExtraProductActions, displayHeader.
• Écriture des valeurs de configuration par défaut (seuil 50 €, calcul TTC, sans frais de port, vérification stock activée).
• Création d’une CartRule « fantôme » avec un code unique du type DFFREEGIFT_A7B3F2D9, visible dans Catalogue → Réductions → Règles panier.

Configuration

L’écran de configuration se trouve dans Modules → DataFirefly Free Gift → Configurer. Tous les paramètres sont regroupés dans un seul formulaire.

Activer le module

Le switch Activer le module agit comme un interrupteur maître. En position Non, le module reste installé mais ne fait rien : pas d’auto-ajout, pas de bloc frontend, pas de calcul de seuil. Utile pour désactiver temporairement l’offre (fin d’une opération saisonnière par exemple) sans perdre la configuration.

Produit cadeau et déclinaison

Deux champs à renseigner dans l’ordre :

1. ID du produit cadeau : saisir l’ID PrestaShop du produit à offrir. L’ID se trouve dans Catalogue → Produits (colonne ID). Après avoir enregistré une première fois, le nom du produit s’affiche en aide sous le champ pour confirmation.
2. Déclinaison : liste déroulante des combinaisons disponibles pour le produit. Se remplit automatiquement après avoir enregistré l’ID produit. Choisir une déclinaison spécifique (par exemple « Taille M, couleur noire ») ou laisser sur — Sans déclinaison — pour un produit simple.

Seuil de déclenchement

Le champ Seuil de déclenchement définit le montant panier à partir duquel le cadeau est ajouté. Deux paramètres associés déterminent la base de calcul :

• Calcul TTC : si activé, le total inclut toutes les taxes appliquées au panier. Si désactivé, le seuil est comparé au total HT. La plupart des boutiques B2C fonctionnent en TTC ; les boutiques B2B raisonnent souvent en HT.
• Inclure les frais de port : si activé, les frais de livraison estimés sont ajoutés au total avant comparaison. En pratique, on l’active rarement puisque les frais de port ne sont pas toujours calculés au moment où le client consulte son panier (aucun transporteur choisi = 0 €).

Concrètement, le total évalué correspond à un appel PrestaShop natif :

Cart::getOrderTotal(
    $with_taxes = (bool) CFG_TAX_INCL,
    $type = CFG_INCLUDE_SHIPPING ? Cart::BOTH : Cart::ONLY_PRODUCTS
);

Cela garantit que la valeur utilisée pour la comparaison est strictement identique à celle affichée dans le récapitulatif panier de PrestaShop.

Vérification du stock

Le switch Vérifier le stock du cadeau (activé par défaut) suspend l’auto-ajout si le produit cadeau est indisponible. Le contrôle respecte la stratégie out of stock configurée globalement dans PrestaShop :

• Si le produit est marqué « autoriser la commande hors stock », l’auto-ajout reste actif même à quantité 0.
• Si le produit refuse les commandes hors stock, l’auto-ajout est suspendu quand la quantité atteint 0.

Restriction par groupes clients

La grille Groupes clients éligibles liste tous les groupes de la boutique avec une case à cocher par groupe. Deux comportements :

• Aucune case cochée : tous les clients sont éligibles, y compris les visiteurs non identifiés (à condition que le groupe par défaut PS_UNIDENTIFIED_GROUP ne soit pas exclu, ce qui est le comportement par défaut).
• Une ou plusieurs cases cochées : seuls les clients membres d’au moins un groupe coché voient le bloc de progression et bénéficient de l’auto-ajout.

Cas d’usage typiques :

• Cadeau réservé au groupe « Professionnels » pour une clientèle B2B.
• Cadeau réservé au groupe « VIP » pour un programme de fidélité.
• Cadeau proposé à tous sauf aux revendeurs (cocher tous les groupes sauf le groupe revendeur).

Options d’affichage

Deux switches indépendants contrôlent l’apparence du bloc frontend :

• Afficher le message de progression : active ou désactive complètement le bloc sur la page panier. En position Non, l’auto-ajout continue de fonctionner mais aucun message n’apparaît côté client (utile si vous voulez piloter l’affichage via votre propre thème).
• Afficher la barre de progression : active ou désactive la barre colorée sous le message. Le message texte reste visible.

Comment ça marche techniquement

La CartRule fantôme

Au lieu de manipuler les prix produits, dffreegift exploite le mécanisme natif PrestaShop de cadeau via CartRule. À l’installation, une règle avec les propriétés suivantes est créée :

• code = DFFREEGIFT_A7B3F2D9 (suffixe généré aléatoirement à l’installation)
• gift_product = 0 (mis à jour à chaque enregistrement de configuration)
• gift_product_attribute = 0 (mis à jour à chaque enregistrement de configuration)
• quantity = 999 999 et quantity_per_user = 999 999 (pratiquement illimité)
• date_from = maintenant, date_to = +50 ans
• active = 1, aucun code, aucune réduction, aucune restriction produit ni catégorie

Quand le seuil est atteint, le module attache cette règle au panier via Cart::addCartRule($id). PrestaShop se charge ensuite du reste :

• Insertion d’une ligne panier avec gift = 1 et price = 0.
• Affichage dans le récapitulatif panier avec un badge « Cadeau ».
• Prise en compte au moment de la conversion en commande.
• Snapshot dans l’historique de commande (le cadeau reste visible même si vous changez de produit cadeau plus tard).

Quand le panier redescend sous le seuil, le module détache la règle via Cart::removeCartRule($id). La ligne cadeau est retirée dans la même requête.

Les hooks utilisés

• actionCartSave : hook principal. Appelé à chaque sauvegarde du panier (ajout, modification, retrait, login client avec fusion de panier). Le module calcule le total, décide d’attacher ou de détacher la règle. Un drapeau statique self::$syncing empêche la récursion si l’attachement de la règle déclenche à son tour un save.
• actionObjectCartRuleDeleteBefore : auto-réparation. Si un administrateur supprime manuellement la règle fantôme depuis Catalogue → Réductions, ce hook détecte la suppression et remet l’ID à zéro dans la configuration. La prochaine sync recréera une règle propre.
• displayHeader : enregistre le CSS et le JS frontend (views/css/dffreegift.css et views/js/dffreegift.js).
• displayShoppingCart : rend le bloc de progression sur la page panier.
• displayCartExtraProductActions : réservé pour évolutions futures (badge sur la ligne cadeau).

Le calcul du seuil

À chaque appel de syncCartGift(), le module vérifie dans l’ordre :

1. Le module est-il activé ? (sinon on sort)
2. Le client est-il éligible selon les groupes configurés ? (sinon on détache si attaché)
3. Le produit cadeau est-il valide (existe, actif, en stock si vérification activée) ? (sinon on détache)
4. Calcul du total selon TTC/HT et frais de port inclus/exclus.
5. Comparaison au seuil avec tolérance d’arrondi de 0,001 €.
6. Attacher la règle si seuil atteint et pas encore attachée. Détacher si sous le seuil et attachée.

Bloc de progression frontend

Le bloc s’affiche automatiquement sur la page panier, entre le récapitulatif produits et le total. Deux états visuels :

• En attente (seuil non atteint) : fond gris clair, message « Ajoutez X,XX € pour recevoir votre cadeau », barre orange qui se remplit à mesure que le seuil approche.
• Objectif atteint (seuil franchi) : fond vert clair, message « Cadeau ajouté à votre panier ! », barre pleine en vert. Une animation pulse se déclenche lors de la transition de l’état en attente vers atteint.

Personnaliser les couleurs

Les couleurs sont définies dans views/css/dffreegift.css. Pour personnaliser sans modifier le module (ce qui écraserait vos changements aux mises à jour), surcharger les classes dans le CSS de votre thème :

.dffreegift-progress {
    border-color: #votre-couleur;
    background: #votre-fond;
}
.dffreegift-progress--reached {
    background: #votre-vert-clair;
    border-color: #votre-vert;
}
.dffreegift-progress__bar-fill {
    background: linear-gradient(90deg, #couleur1, #couleur2);
}

Personnaliser les textes

Les textes affichés côté client sont traduisibles via le mécanisme PrestaShop standard. Aller dans International → Traductions, sélectionner « Traductions du module », choisir dffreegift et la langue, puis chercher le domaine Modules.Dffreegift.Shop. Les chaînes disponibles :

• « Ajoutez %amount% pour recevoir votre cadeau » — message en attente (%amount% est remplacé automatiquement par le montant restant formaté selon la devise et la locale).
• « Cadeau ajouté à votre panier ! » — message objectif atteint.
• « Progression vers le cadeau » — label ARIA de la barre (lu par les lecteurs d’écran).

Cohabitation avec d’autres promotions

Le cadeau étant ajouté via une CartRule native, il cohabite normalement avec toute autre CartRule. Comportements attendus :

• Autres codes promo client (réduction pourcentage, montant fixe, livraison gratuite) : s’appliquent normalement en parallèle du cadeau. Le cadeau ne consomme pas la remise, et inversement.
• Autre règle avec gift_product configuré ailleurs : PrestaShop traite les deux comme des règles indépendantes et ajoute les deux cadeaux. Attention si vous cumulez plusieurs modules cadeaux.
• Règle avec product_restriction excluant le produit cadeau : la règle qui restreint l’emporte. Le cadeau n’est pas ajouté si une autre règle active l’exclut explicitement.
• Règle avec cart_rule_restriction : si une autre règle interdit l’usage de la nôtre par restriction croisée, l’auto-ajout est bloqué (comportement PrestaShop natif).

Multi-boutique

Le module fonctionne avec la configuration multi-boutique de PrestaShop sur le contexte boutique par défaut. Les configurations (seuil, produit cadeau, options) sont stockées via Configuration::updateValue, qui respecte le contexte boutique courant. La CartRule créée à l’installation est associée à la boutique active au moment de l’installation.

Pour un déploiement multi-boutique avec des cadeaux différents par boutique, il faut actuellement installer et configurer le module dans chaque contexte boutique séparément. Contacter le support pour une variante avec scoping explicite par id_shop.

Dépannage

Le cadeau ne s’ajoute pas au panier

Vérifier dans l’ordre :

1. Le module est-il bien activé ? (Modules → Configurer → switch Activer le module).
2. Le produit cadeau est-il valide ? (ID correct, produit actif, en stock si vérification stock activée).
3. Le client est-il dans un groupe autorisé ? (si vous avez restreint aux groupes, un visiteur non identifié qui n’est dans aucun groupe autorisé ne verra rien).
4. Le seuil est-il réellement atteint ? Recalculer manuellement le total selon vos paramètres (TTC/HT, avec/sans port).
5. La CartRule fantôme existe-t-elle et est-elle active ? Aller dans Catalogue → Réductions → Règles panier et chercher DFFREEGIFT_.

Le bloc de progression ne s’affiche pas sur la page panier

Causes courantes :

• Le switch Afficher le message de progression est en position Non.
• Le client n’est pas éligible selon les groupes clients configurés.
• Le produit cadeau est invalide (n’existe pas, inactif, ou en rupture avec vérification stock activée).
• Votre thème custom n’appelle pas le hook displayShoppingCart. Vérifier avec la commande grep -r "displayShoppingCart" themes/votre-theme/ ou dans Modules → Positions.

La CartRule a disparu du back office

Si quelqu’un a supprimé la règle depuis Catalogue → Réductions, le hook actionObjectCartRuleDeleteBefore a détecté la suppression et remis la configuration à zéro. À la prochaine synchronisation panier (donc au prochain ajout de produit par un client), une nouvelle règle est créée automatiquement avec un nouveau code DFFREEGIFT_xxxxxxxx.

Pour forcer la régénération immédiatement sans attendre un client :

1. Aller dans Modules → DataFirefly Free Gift → Désactiver.
2. Puis Activer à nouveau. Cela recrée une règle propre.

Erreurs dans les logs PrestaShop

Le module logue les exceptions dans Paramètres avancés → Logs avec le préfixe [dffreegift]. Un message typique en cas de problème :

[dffreegift] actionCartSave error: <description de l'erreur>

Ces erreurs n’interrompent jamais le fonctionnement du panier — elles sont uniquement informatives. En cas de log récurrent, transmettre le message complet au support.

Le seuil semble mal calculé

Le calcul dépend strictement de vos paramètres Calcul TTC et Inclure les frais de port. Pour vérifier ce que PrestaShop retourne :

• TTC + sans port : correspond au Sous-total produits TTC affiché dans le récap panier.
• TTC + avec port : correspond au Total TTC (produits + frais de port si un transporteur est sélectionné).
• HT + sans port : correspond au Sous-total produits HT.
• HT + avec port : correspond au Total HT (produits + frais de port HT).

Si vous constatez un écart, comparer avec la ligne exacte du récap panier — il y a de fortes chances que l’écart vienne des frais de port qui n’ont pas encore été calculés (le client n’a pas encore choisi de transporteur, donc les frais sont à 0 €).

Désinstallation

Aller dans Modules → Gestionnaire de modules → DataFirefly Free Gift → Désinstaller. La désinstallation supprime :

• La CartRule fantôme et toutes ses associations aux paniers (les paniers en cours perdront leur cadeau automatiquement).
• Toutes les clés de configuration avec le préfixe DFFREEGIFT_.

FAQ rapide

• Le cadeau apparaît-il dans le mini-panier du header ? Non, uniquement sur la page panier (hook displayShoppingCart). Le mini-panier est géré différemment par chaque thème et une intégration spécifique thème par thème serait nécessaire. Sur demande au support.
• Puis-je offrir plusieurs cadeaux avec plusieurs seuils (ex. cadeau A à 50 €, cadeau B à 100 €) ? Non, la version 1.0.0 gère un seul cadeau avec un seul seuil. Pour plusieurs paliers, contacter le support.
• Le cadeau est-il inclus dans les remboursements ? Comme tout produit cadeau PrestaShop natif, le cadeau apparaît dans la commande à prix 0. En cas de remboursement partiel, le cadeau reste dans la commande sans impact financier.
• Puis-je modifier le fichier dffreegift.php directement ? Techniquement oui (code non chiffré), mais les mises à jour officielles écraseront vos changements. Créer un module override pour toute personnalisation profonde.

Support et mises à jour

Le module inclut 12 mois de mises à jour et de support à partir de la date d’achat. Support par email en français ou en anglais, réponse sous 24 heures ouvrées.

Pour toute question ou anomalie, contacter le support DataFirefly en précisant :

• Version de PrestaShop (visible dans Paramètres avancés → Information)
• Version de PHP
• Version du module dffreegift installé
• Description du comportement observé vs comportement attendu
• Extrait des logs PrestaShop si applicable ([dffreegift])