Barre de livraison gratuite (dffreeshipbar) — Guide complet

Guide complet du module dffreeshipbar pour PrestaShop 8 et 9 : installation, seuils par pays et par état, filtrage par transporteur, emplacements d’affichage, multi-boutique et dépannage. Toutes les règles de résolution sont détaillées avec les cas limites.

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 à aucun moment la variable native PS_SHIPPING_FREE_PRICE : vous pouvez la laisser à 0 et piloter votre franco de port par des tranches transporteur sans aucun conflit.

La particularité du module est sa résolution territoriale à deux niveaux. Un seuil peut être défini au niveau du pays, mais aussi au niveau de l’état PrestaShop — ce qui permet de traiter différemment des territoires rattachés administrativement à un même pays, comme les départements d’outre-mer rattachés à la France.

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
• Accès administrateur au back office

Installation

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

À l’installation, le module crée deux tables et enregistre ses hooks :

• PREFIX_dffreeshipbar_country — seuils au niveau pays, avec une colonne id_shop.
• PREFIX_dffreeshipbar_state — seuils au niveau état, avec une colonne id_shop.

Hooks enregistrés : displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, actionCarrierUpdate.

Configuration générale

L’écran de configuration se trouve dans Modules → DataFirefly – Barre de livraison gratuite → Configurer. Il se compose de trois panneaux : paramètres généraux, règles transporteur, seuils par territoire.

Seuil global de repli

Deux réglages liés :

• Utiliser un seuil global par défaut : quand ce switch est sur Non, la barre n’apparaît que dans les territoires configurés explicitement. Quand il est sur Oui, tout territoire non configuré reçoit le montant saisi ci-dessous.
• Seuil global par défaut : le montant appliqué en dernier recours.

Laissez le repli désactivé si votre franco ne couvre que quelques destinations. Activez-le si votre franco est universel et que les exceptions sont rares.

Base de calcul

• Comparer les totaux TTC : détermine si le total du panier est évalué taxes comprises ou hors taxes. Ce réglage doit correspondre à la base utilisée par vos tranches transporteur, faute de quoi la barre et le tunnel de commande afficheront des résultats divergents.
• Inclure les bons de réduction dans le total : quand ce switch est actif, les remises panier sont déduites avant comparaison au seuil. Un panier de 70 € avec un bon de 10 € est alors évalué à 60 €.

Le total évalué correspond à un appel natif :

Cart::getOrderTotal(
    $with_taxes = (bool) DFFREESHIPBAR_TAX_INCL,
    $type = DFFREESHIPBAR_INCLUDE_DISCOUNTS
        ? Cart::BOTH_WITHOUT_SHIPPING
        : Cart::ONLY_PRODUCTS
);

Les frais de port et l’emballage cadeau ne sont jamais comptés dans la progression.

Exiger une adresse de livraison

Tant que le client n’a pas renseigné d’adresse, la destination n’est qu’une estimation et l’état reste inconnu. Trois modes :

• Jamais : la barre s’affiche dès la navigation catalogue, 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. Un visiteur estimé en Belgique voit la barre ; un visiteur estimé en France ne la voit qu’après saisie d’adresse, puisque son état déterminera le seuil réel.
• Toujours : rien tant qu’aucune adresse n’existe sur le panier.

Emplacements et apparence

• Afficher en haut de page : bannière visible sur tout le site.
• Afficher sur le panier et la commande : bloc affiché au moment de la décision.
• Activer l’animation : rayures animées sur la barre en cours de progression. L’animation est automatiquement neutralisée pour les visiteurs ayant activé prefers-reduced-motion.
• Quatre couleurs : fond, barre, texte, message de réussite.

Pour un placement libre dans votre thème, le module implémente WidgetInterface :

{widget name='dffreeshipbar'}
{widget name='dffreeshipbar' position='cart'}

Seuils par territoire

C’est le cœur du module. Le tableau liste tous les pays actifs de la boutique, et sous chaque pays comportant des états, ses états en retrait.

Ordre de résolution

Pour une adresse de livraison donnée, le module cherche dans cet ordre et s’arrête au premier résultat :

1. L’état de l’adresse, si une règle existe pour lui.
2. Le pays de l’adresse, si une règle existe pour lui.
3. Le seuil global de repli, s’il est activé.

Si aucune de ces trois étapes ne produit de montant, la barre ne s’affiche pas.

Case à cocher et champ montant : deux effets différents

C’est le point le plus important de la configuration, et le plus souvent mal compris :

• Case décochée → la barre est masquée pour ce territoire. Il n’hérite ni du pays parent, ni du seuil global. La résolution s’arrête là.
• 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.

Exemple : franco métropole uniquement

Cas courant d’une boutique française offrant le port à 65 € en métropole et en Corse, mais pas en outre-mer :

• France : case cochée, montant 65.
• Corse : case cochée, montant vide — elle hérite des 65 € de la France.
• Guadeloupe, Martinique, Guyane, Réunion, Mayotte : cases décochées. Aucune barre sur ces destinations.
• Seuil global de repli : désactivé, pour qu’aucun autre pays ne reçoive de barre par accident.

Un client guadeloupéen ne verra donc jamais la promesse de franco, alors même que son adresse est rattachée au pays « France » dans PrestaShop.

Filtre et recherche

Le champ de recherche filtre pays et états par nom. La case Afficher uniquement les territoires configurés réduit le tableau aux lignes ayant déjà une règle — utile sur une boutique ouverte à cent pays.

Les deux boutons d’enregistrement sont indépendants : Enregistrer les pays et Enregistrer les états.

Règles transporteur

Si votre franco n’est accordé que par certains transporteurs, restreignez l’affichage en conséquence. Trois modes :

• Tous les transporteurs : aucun filtrage.
• Afficher uniquement pour les transporteurs cochés : liste blanche.
• Masquer pour les transporteurs cochés : liste noire.

Avant sélection du transporteur

Le transporteur n’est connu qu’à l’étape de livraison. Le réglage Avant sélection du transporteur décide de ce qui se passe avant ce moment :

• Afficher : la barre apparaît sur le catalogue et le panier, puis disparaît si le client choisit un transporteur exclu.
• Masquer : la barre n’apparaît qu’une fois un transporteur éligible sélectionné.

Mise à jour en temps réel

La barre est recalculée côté serveur et rafraîchie sans rechargement de page à chaque événement panier : ajout, suppression, changement de quantité, modification d’adresse, changement d’étape du tunnel.

Le script écoute les événements PrestaShop updatedCart, updateCart, updatedAddressForm, changedCheckoutStep et updateDeliveryForm. Vous pouvez déclencher un rafraîchissement manuel depuis votre propre code :

document.dispatchEvent(new Event('dffreeshipbar:refresh'));

C’est le serveur qui décide de la visibilité : si le territoire ou le transporteur ne qualifie plus, la barre est retirée du DOM plutôt que laissée avec une valeur périmée.

Multi-boutique

Les seuils sont stockés avec une colonne id_shop. Chaque boutique possède donc ses propres règles pays et états, indépendantes les unes des autres.

Pour configurer une boutique donnée, sélectionnez son contexte en haut du back office avant d’ouvrir l’écran de configuration. Le panneau des seuils affiche le nom de la boutique courante en rappel.

Traductions

Le module est livré traduit en français, anglais, allemand, espagnol, italien et polonais.

Pour adapter les textes affichés côté client, aller dans International → Traductions, sélectionner « Traductions du module », choisir dffreeshipbar et la langue, puis chercher le domaine Modules.Dffreeshipbar.Shop. Les chaînes disponibles :

• « Plus que %amount% pour bénéficier de la livraison gratuite ! » — panier en cours.
• « Livraison gratuite dès %amount%. » — panier vide.
• « Félicitations ! Votre commande bénéficie de la livraison gratuite. » — seuil atteint.

Le jeton %amount% est remplacé par le montant formaté selon la devise et la locale actives. Conservez-le dans vos traductions.

Mise à jour depuis la version 1.0

La mise à jour est automatique au remplacement du ZIP. Les scripts d’upgrade effectuent les opérations suivantes :

• Création de la table des états.
• Renommage de la colonne active en enabled sur la table des pays. Vos seuils existants sont conservés.
• Le seuil global de repli est activé si vous en aviez un en 1.0, pour ne pas modifier ce que voient vos clients.
• Le mode d’exigence d’adresse est positionné sur Jamais, qui correspond au comportement de la version 1.0. Passez-le sur le mode recommandé quand vous le décidez.

Dépannage

La barre ne s’affiche nulle part

1. Le module est-il activé ? (switch Activer le module).
2. Avez-vous configuré au moins un territoire, ou activé le seuil global de repli ? Sans l’un ou l’autre, la barre ne s’affiche jamais.
3. Le mode d’exigence d’adresse est-il sur Toujours alors que vous testez sans adresse de livraison ?
4. Les emplacements sont-ils activés ? (bannière et/ou panier).
5. Votre thème appelle-t-il les hooks utilisés ? Vérifier dans Modules → Positions. En thème personnalisé, utiliser plutôt le widget.

La barre s’affiche là où elle ne devrait pas

Le cas typique est un territoire qui hérite alors qu’il devrait être exclu. Vérifier que la case du territoire est bien décochée, et non simplement que son montant a été vidé — les deux actions ont des effets opposés.

Le seuil affiché ne correspond pas au checkout

• Vérifier que le réglage Comparer les totaux TTC correspond à la base de vos tranches transporteur.
• Vérifier le réglage des bons de réduction : un panier remisé peut passer sous le seuil.
• Le module ne lit pas vos tranches transporteur. Si vous avez modifié une tranche, reportez la nouvelle valeur dans le module.

La barre ne se met pas à jour après un ajout au panier

Le rafraîchissement s’appuie sur les événements JavaScript de PrestaShop. Certains thèmes ou modules de panier tiers ne les émettent pas. Deux vérifications :

• La console navigateur signale-t-elle une erreur JavaScript sur une autre ressource ? Une erreur bloquante en amont empêche l’écoute de s’installer.
• Votre module de panier ajax émet-il bien prestashop.emit('updatedCart') ? Sinon, déclenchez dffreeshipbar:refresh depuis votre code.

Les règles transporteur semblent ignorées

Vérifier que le transporteur sélectionné est bien celui que vous croyez : après une modification de tarif, PrestaShop crée un nouveau transporteur. Le module suit la référence, donc la règle devrait suivre — mais si le transporteur a été recréé de zéro plutôt que modifié, sa référence est nouvelle et il faut le recocher.

Désinstallation

Aller dans Modules → Gestionnaire de modules → DataFirefly – Barre de livraison gratuite → Désinstaller. La désinstallation supprime les deux tables de seuils et toutes les clés de configuration préfixées DFFREESHIPBAR_.

FAQ rapide

• Le module lit-il PS_SHIPPING_FREE_PRICE ? Non, jamais. Vous pouvez la laisser à 0 et gérer votre franco par tranches transporteur.
• Le module lit-il mes tranches transporteur pour en déduire le seuil ? Non. Les seuils sont saisis manuellement. Une synchronisation automatique depuis les tranches 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. Une condition de poids relève d’un développement spécifique.
• Puis-je afficher la barre ailleurs que dans les emplacements proposés ? Oui, via {widget name='dffreeshipbar'} dans n’importe quel template.
• Le module fonctionne-t-il avec le thème Hummingbird ? Oui. Les hooks displayNavFullWidth et displayCheckoutSummaryTop sont enregistrés pour lui, et le widget couvre les placements personnalisés.
• Les seuils sont-ils indépendants par boutique ? Oui, chaque ligne porte un id_shop.

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 et de PHP
• Version du module installée
• Thème utilisé
• Territoire et transporteur concernés par le comportement observé
• Description du comportement observé vs attendu