# 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…

- Page: <https://www.datafirefly.com/documentation/dffreegift/>
- Langue: fr
- Mis à jour le: 2026-07-01
- Autres langues: [en](https://www.datafirefly.com/en/documentation/dffreegift/index.md), [es](https://www.datafirefly.com/es/documentation/dffreegift/index.md), [de](https://www.datafirefly.com/de/documentation/dffreegift/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffreegift/index.md), [it](https://www.datafirefly.com/it/documentation/dffreegift/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffreegift/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffreegift/index.md)
- Index: <https://www.datafirefly.com/documentation/llms.txt>

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**.

**Note.** La CartRule créée à l'installation n'a pas encore de produit cadeau assigné (`gift_product = 0`) et n'est donc pas active fonctionnellement. Elle sera synchronisée dès que vous enregistrerez un ID de produit cadeau dans l'écran de configuration.

## 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.

**Astuce.** Si vous changez de produit cadeau plus tard, la CartRule est automatiquement resynchronisée à l'enregistrement. Vous n'avez pas à toucher manuellement à la règle dans la section Réductions.

### 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.

**Recommandation.** Laisser cette vérification activée. Désactiver le contrôle peut conduire à des commandes bloquées au checkout pour cause de rupture de stock du cadeau — expérience client dégradée et intervention manuelle nécessaire.

### 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).

**Note.** Le seuil de dffreegift est évalué sur le total _hors cadeau_. Si vous avez un autre cart rule qui remise le total avant que dffreegift ne l'évalue, la comparaison se fait sur le total _après_ remise. Un panier de 60 € avec remise de 15 € tombe à 45 € et ne déclenchera pas un seuil de 50 €.

## 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_`.

**Attention.** La désinstallation ne restaure pas les cadeaux dans les commandes passées — celles-ci gardent leur snapshot d'origine avec le cadeau bien enregistré. Seuls les paniers en cours sont impactés.

## 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](https://www.datafirefly.com/contact/) 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]`)