# Barre de livraison gratuite (dffreeshipbar) : guide complet
> Guide complet du module dffreeshipbar 2.3.0 pour PrestaShop 8 et 9 : installation, seuils par pays et par état, emplacements d'affichage (dont la fiche produit et le tiroir panier Creative…
- Page:
- Langue: fr
- Mis à jour le: 2026-09-28
- Autres langues: [en](https://www.datafirefly.com/en/documentation/dffreeshipbar/index.md), [es](https://www.datafirefly.com/es/documentation/dffreeshipbar/index.md), [de](https://www.datafirefly.com/de/documentation/dffreeshipbar/index.md), [it](https://www.datafirefly.com/it/documentation/dffreeshipbar/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffreeshipbar/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffreeshipbar/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffreeshipbar/index.md)
- Index:
Guide complet du module **dffreeshipbar** 2.3.0 pour PrestaShop 8 et 9 : installation, seuils par pays et par état, emplacements d'affichage (dont la fiche produit et le tiroir panier Creative Elements), messages, apparence, transporteurs, multi-devise et dépannage.
## Aperçu
dffreeshipbar affiche une barre de progression indiquant au client combien il lui reste à dépenser pour bénéficier de la livraison gratuite. Lorsque le seuil est atteint, le message bascule sur une confirmation.
Le module fonctionne avec **ses propres seuils**, stockés dans ses tables. Il n'interroge jamais la variable native `PS_SHIPPING_FREE_PRICE` : vous pouvez la laisser à 0 et piloter votre franco par des tranches transporteur sans conflit.
Sa particularité est la **résolution territoriale à deux niveaux** : un seuil peut être défini au niveau du pays et au niveau de l'état PrestaShop. Des territoires rattachés au même pays, comme les départements d'outre-mer rattachés à la France, peuvent ainsi être traités différemment.
## Prérequis
- PrestaShop 8.0 à 9.x
- PHP 7.4 minimum (8.0 à 8.3 supportées)
- Thème Classic, Hummingbird ou thème personnalisé appelant les hooks standards
- Creative Elements (facultatif) pour l'emplacement tiroir panier
## Installation
1. Dans le back office, aller dans **Modules → Gestionnaire de modules → Envoyer un module**.
2. Uploader le fichier `dffreeshipbar-2.3.0.zip`.
3. Cliquer sur **Installer** puis **Configurer**.
Le module crée deux tables (`PREFIX_dffreeshipbar_country` et `PREFIX_dffreeshipbar_state`, chacune avec une colonne `id_shop`) et enregistre les hooks `displayHeader`, `displayBanner`, `displayNav2`, `displayNavFullWidth`, `displayShoppingCartFooter`, `displayCheckoutSummaryTop`, `displayProductAdditionalInfo`, `displayCEShoppingCartFooter` et `actionCarrierUpdate`.
**Note.** Le seuil global de repli est désactivé par défaut. Tant qu'aucun territoire n'a de seuil, la barre ne s'affiche nulle part, et le bandeau de synthèse du back office le signale. Mieux vaut une barre absente qu'une barre qui promet un franco inexistant.
## L'écran de configuration
L'écran se trouve dans **Modules → DataFirefly - Barre de livraison gratuite → Configurer**. En tête, un bandeau de synthèse indique l'état du module, le nombre de territoires avec seuil et de territoires exclus, le seuil de repli, le filtrage transporteur et les emplacements actifs. Chaque tuile ouvre l'onglet concerné.
La configuration est répartie en cinq onglets : **Général**, **Territoires**, **Transporteurs**, **Messages** et **Apparence**. L'onglet actif est conservé après un enregistrement.
## Onglet Général
### Seuil global de repli
- **Utiliser un seuil global par défaut** : sur _Non_, la barre n'apparaît que dans les territoires configurés. Sur _Oui_, tout territoire non configuré reçoit le montant saisi.
- **Seuil global par défaut** : le montant appliqué en dernier recours.
### Multi-devise
Tous les montants du module se saisissent dans la **devise par défaut** de la boutique. Pour un visiteur qui paie dans une autre devise, le seuil est converti au taux de change de PrestaShop avant la comparaison avec son panier, et les montants affichés sont formatés dans sa devise.
### Exiger une adresse de livraison
Avant la saisie d'une adresse, la destination n'est qu'une estimation et l'état reste inconnu. Trois modes :
- **Jamais** : la barre s'affiche dès la navigation, sur la base du pays estimé.
- **Pour les pays comportant des états** (recommandé) : la barre reste visible partout, sauf dans les pays dont les états peuvent porter des conditions différentes, où elle attend l'adresse.
- **Toujours** : rien tant qu'aucune adresse n'existe sur le panier.
### Base de calcul
- **Comparer les totaux TTC** : doit correspondre à la base de vos tranches transporteur, sinon la barre et le tunnel de commande divergent.
- **Inclure les bons de réduction dans le total** : un panier de 70 € avec un bon de 10 € est alors évalué à 60 €.
Les frais de port ne comptent jamais dans la progression.
### Groupes clients
Sans case cochée, tous les clients voient la barre. Cochez des groupes pour la réserver à ceux-ci, par exemple aux particuliers quand les professionnels ont d'autres conditions de livraison. Un visiteur non connecté appartient au groupe « Visiteur ».
### Masquer tant que le panier est vide
La barre apparaît au premier produit ajouté. La fiche produit la conserve dans tous les cas, puisque c'est l'endroit où le client décide d'ajouter.
### Emplacements d'affichage
- **Haut de page** : bannière visible sur tout le site.
- **Fiche produit** : voir la section dédiée ci-dessous.
- **Panier et commande** : bloc affiché sur la page panier et dans le tunnel.
- **Tiroir panier Creative Elements** : voir la section dédiée ci-dessous.
Pour un placement libre, le module implémente `WidgetInterface` :
```
{widget name='dffreeshipbar'}
{widget name='dffreeshipbar' position='cart'}
```
## La barre sur la fiche produit
La barre s'affiche sous le bouton d'ajout au panier (hook `displayProductAdditionalInfo`). En plus de la progression actuelle, une ligne indique l'effet de l'ajout du produit affiché :
- si le produit suffit à atteindre le seuil : « Ajoutez ce produit et la livraison vous est offerte » ;
- sinon : « Avec ce produit, plus que 2,50 € pour la livraison gratuite ».
Le calcul utilise le prix de la déclinaison sélectionnée multiplié par la quantité saisie, sur la même base HT ou TTC que le panier, avec les prix spécifiques du client. Il se relance quand le client change de déclinaison ou de quantité.
**Mise à jour depuis une version antérieure.** Cet emplacement démarre désactivé sur une boutique existante, pour que la mise à jour ne change pas ce que voient vos clients. Activez-le dans l'onglet Général.
## Le tiroir panier Creative Elements
Sur une boutique dont le header est construit avec Creative Elements, la barre s'intègre au panier latéral du widget **Panier** en habillage _Sidebar_, par le hook `displayCEShoppingCartFooter` que ce widget exécute. L'habillage _Classic_ n'ouvre pas de tiroir.
Le réglage **Position dans le tiroir panier** propose trois emplacements : sous le titre du tiroir, au-dessus du récapitulatif ou au-dessus des boutons de commande.
La barre se met à jour en Ajax à chaque ajout au panier et à chaque suppression depuis le tiroir, sans rechargement, avec une jauge qui glisse depuis sa valeur précédente. Creative Elements ne reconstruit que la liste des produits et le récapitulatif : la barre reste en place entre deux mises à jour.
## Onglet Territoires
Le tableau liste tous les pays actifs de la boutique et, sous chaque pays comportant des états, ses états en retrait. Un champ de recherche et un filtre « territoires configurés » facilitent la navigation. Les montants sont en devise par défaut.
### Ordre de résolution
Pour une adresse de livraison, le module cherche dans cet ordre et s'arrête au premier résultat : l'**état** de l'adresse, puis le **pays**, puis le **seuil global de repli** s'il est activé. Sans résultat, la barre ne s'affiche pas.
### Case à cocher et montant : deux effets différents
- **Case décochée** : la barre est masquée pour ce territoire, sans héritage du pays ni du seuil global.
- **Case cochée, montant vide** : la règle est supprimée, le territoire hérite du niveau supérieur.
- **Case cochée, montant saisi** : ce montant s'applique.
**Attention.** Pour exclure un territoire, décochez la case. Vider le montant produit l'effet inverse : le territoire hérite du seuil de son pays.
### Exemple : franco métropole uniquement
- **France** : case cochée, montant `65`.
- **Corse** : case cochée, montant vide ; elle hérite des 65 €.
- **Guadeloupe, Martinique, Guyane, Réunion, Mayotte** : cases décochées.
- **Seuil global de repli** : désactivé.
## Onglet Transporteurs
Trois modes : tous les transporteurs, affichage réservé aux transporteurs cochés, ou masquage pour les transporteurs cochés. Les règles sont enregistrées sur l'`id_reference` du transporteur : PrestaShop recrée un transporteur à chaque modification, mais sa référence reste stable.
Le réglage **Avant sélection du transporteur** décide si la barre s'affiche sur le catalogue et le panier tant qu'aucun transporteur n'est choisi.
## Onglet Messages
Cinq messages se personnalisent pour chaque langue active :
- **Panier vide** (défaut : « Livraison gratuite dès {threshold}. »)
- **Panier en cours** (défaut : « Plus que {amount} pour bénéficier de la livraison gratuite ! »)
- **Seuil atteint**
- **Fiche produit : ce produit débloque la livraison gratuite**
- **Fiche produit : montant restant après ajout du produit**
Deux jetons sont disponibles : `{amount}` pour le montant restant et `{threshold}` pour le seuil. Ils sont remplacés par le montant formaté dans la devise du visiteur, en gras. Le texte est affiché tel quel : le HTML saisi n'est pas interprété. Un champ laissé vide reprend le texte traduit fourni avec le module.
## Onglet Apparence
- **Couleurs** : fond, barre, texte et message de réussite, avec un sélecteur et un champ hexadécimal synchronisés.
- **Icône** : camion, colis, cadeau ou aucune. Les icônes sont en SVG et une coche remplace l'icône quand le seuil est atteint.
- **Animation** : rayures animées pendant la progression, automatiquement coupées pour les visiteurs qui ont activé la réduction des animations dans leur système.
- **Bannière refermable** : ajoute un bouton de fermeture à la bannière du haut de page. Une fois fermée, elle reste masquée jusqu'à la fermeture du navigateur. Les autres emplacements ne sont pas concernés.
Un **aperçu en direct** montre la bannière, la fiche produit et le seuil atteint, et se met à jour à chaque changement avant enregistrement.
## Mise à jour en temps réel
Chaque emplacement imprime un conteneur, même quand la barre n'a rien à afficher. Après un événement panier, adresse, étape du tunnel, déclinaison ou quantité, une seule requête récupère la barre de tous les emplacements de la page, qui sont remplis ou vidés sur place. Une barre masquée au chargement peut donc apparaître sans rechargement, et inversement.
Le script écoute les événements PrestaShop `updateCart`, `updatedCart`, `updatedAddressForm`, `changedCheckoutStep`, `updateDeliveryForm` et `updatedProduct`. Pour un rafraîchissement depuis votre propre code :
```
document.dispatchEvent(new Event('dffreeshipbar:refresh'));
```
## Multi-boutique et traductions
Les seuils portent un `id_shop` : chaque boutique a ses propres règles. Sélectionnez le contexte de la boutique en haut du back office avant d'ouvrir la configuration.
Le module est livré traduit en français, anglais, allemand, espagnol, italien et polonais. Pour les textes côté client, l'onglet Messages suffit dans la plupart des cas.
## Mise à jour depuis une version antérieure
Le remplacement du ZIP exécute automatiquement les scripts de migration. Vos seuils sont conservés. Les nouvelles options démarrent désactivées sur une boutique existante : fiche produit, masquage du panier vide, bannière refermable, restriction par groupe. Les couleurs enregistrées par les anciennes versions sont normalisées au format `#rrggbb`, et les caches Smarty et opcache sont vidés.
## Dépannage
### La barre ne s'affiche nulle part
1. Le bandeau de synthèse signale-t-il qu'aucun territoire n'a de seuil ?
2. Le module est-il activé, et les emplacements voulus sont-ils activés ?
3. Le mode d'exigence d'adresse est-il sur _Toujours_ alors que vous testez sans adresse ?
4. Des groupes clients sont-ils cochés sans que votre compte de test en fasse partie ?
5. L'option « Masquer tant que le panier est vide » est-elle active avec un panier vide ?
### La barre s'affiche là où elle ne devrait pas
Vérifiez que la case du territoire est bien décochée, et non simplement que son montant a été vidé.
### Rien dans le tiroir Creative Elements
- Le widget Panier doit être en habillage _Sidebar_.
- L'option « Afficher dans le tiroir panier Creative Elements » doit être active.
- Après une mise à jour depuis la 2.1.0 ou antérieure, videz le cache dans **Paramètres avancés → Performances**.
### Le montant ne correspond pas au tunnel de commande
- Le réglage TTC doit correspondre à la base de vos tranches transporteur.
- Un bon de réduction peut faire repasser le panier sous le seuil.
- Le module ne lit pas vos tranches : reportez toute modification de tranche dans le module.
### La barre ne se met pas à jour après un ajout
Le rafraîchissement repose sur les événements JavaScript de PrestaShop. Si un module de panier tiers ne les émet pas, déclenchez `dffreeshipbar:refresh` depuis son code. Vérifiez aussi la console : une erreur JavaScript en amont empêche l'écoute de s'installer.
## Désinstallation
La désinstallation supprime les deux tables de seuils et toutes les clés de configuration préfixées `DFFREESHIPBAR_`, messages compris. Exportez les deux tables si vous prévoyez de réinstaller.
## FAQ rapide
- **Le module lit-il PS_SHIPPING_FREE_PRICE ?** Non, jamais.
- **Le module lit-il mes tranches transporteur ?** Non, les seuils sont saisis manuellement. Une synchronisation automatique est possible en développement spécifique.
- **Mon franco dépend aussi du poids. Est-ce géré ?** Non, le module ne mesure qu'un montant.
- **Puis-je mettre du gras ou un lien dans un message ?** Non, le texte est échappé. Les montants des jetons sont mis en gras automatiquement.
- **La bannière fermée revient-elle ?** À la prochaine ouverture du navigateur.
## Support et mises à jour
Le module inclut **12 mois de mises à jour et de support**. Support par email en français ou en anglais, réponse sous 24 heures ouvrées. Contactez [le support DataFirefly](https://www.datafirefly.com/contact/) en précisant les versions de PrestaShop, de PHP et du module, le thème utilisé, et le territoire et le transporteur concernés.