Compteur de Ventes Shopware 6 : guide d’installation et de configuration

Ce guide couvre l’installation, la configuration et la personnalisation du plugin DfSalesCounter, qui affiche sur chaque fiche produit le nombre de fois qu’un produit a déjà été vendu, à partir des commandes réelles de votre boutique Shopware 6.

Prérequis

• Shopware 6.5.x, 6.6.x ou 6.7.x en installation auto-hébergée. Shopware Cloud (SaaS) n’accepte pas les plugins serveur.
• PHP 8.1 ou supérieur.
• Un thème storefront dérivé du thème Storefront de Shopware, ou un thème personnalisé qui conserve les blocs Twig standards du bloc d’achat.
• Un accès en ligne de commande est recommandé pour la compilation du thème, mais l’installation par l’administration fonctionne également.

Installation

Par upload ZIP depuis l’administration

1. Dans l’administration Shopware, ouvrez Extensions, puis Mes extensions.
2. Cliquez sur Téléverser l’extension et sélectionnez le fichier DfSalesCounter-1.0.0.zip.
3. Une fois le plugin listé, cliquez sur Installer, puis activez-le avec l’interrupteur.
4. Recompilez le thème depuis Contenus, Thèmes, en sélectionnant votre thème puis Recompiler le thème. Cette étape est nécessaire une seule fois, car le plugin fournit une feuille de style storefront.

Par ligne de commande

Déposez le dossier DfSalesCounter dans custom/plugins/ de votre installation, puis lancez :

bin/console plugin:refresh
bin/console plugin:install --activate DfSalesCounter
bin/console theme:compile
bin/console cache:clear

Sur un environnement disposant d’un pipeline de déploiement, la compilation du thème fait généralement déjà partie des étapes standard.

Configuration

La page de configuration se trouve dans Extensions, Mes extensions, bouton … à droite de DataFirefly Sales Counter, puis Configurer. Le sélecteur en haut de page permet de choisir le canal de vente auquel s’applique la configuration : chaque canal peut avoir son propre seuil, son propre texte et son propre emplacement.

Onglet Général

• Activer le compteur de ventes : interrupteur principal. Désactivé, aucune requête n’est exécutée et aucun badge n’est rendu.
• Mode de comptage : Quantité vendue additionne toutes les quantités commandées du produit. Nombre de commandes compte les commandes distinctes ayant inclus le produit. Le premier mode met en avant le volume, le second le nombre de clients différents convaincus.
• Commandes prises en compte : Toutes les commandes donne le chiffre brut. Exclure les commandes annulées écarte celles dont l’état machine est cancelled. Commandes payées uniquement ne conserve que les commandes disposant d’une transaction en état paid ou paid_partially.
• Seuil minimum avant affichage : en dessous de cette valeur, aucun badge n’apparaît. La valeur par défaut est 5. Un seuil de 0 est traité comme 1, le badge n’est jamais rendu pour un produit sans vente.
• Période en jours : limite le comptage aux X derniers jours, sur la base de la date de commande. La valeur 0 signifie un cumul depuis toujours.
• Cumuler les ventes de toutes les déclinaisons : additionne les ventes du produit parent et de l’ensemble de ses variantes. Recommandé sur un catalogue mode ou taille, à désactiver si chaque variante correspond à un usage distinct.
• Compter uniquement les commandes du canal de vente courant : évite qu’une boutique B2B ou un canal export gonfle les chiffres affichés sur la boutique grand public.

Onglet Affichage

• Emplacement sur la fiche produit : Sous le nom du produit, Sous le prix, ou Sous le bloc d’achat, c’est-à-dire en bas du bloc, sous le bouton d’ajout au panier.
• Style visuel : Badge rend une pilule bordée, Texte simple rend une ligne sans encadrement, Bandeau rend un bloc pleine largeur avec une barre latérale colorée.
• Icône : flamme, panier, coche, ou aucune. Les icônes sont des SVG rendus en ligne, aucune police d’icônes n’est chargée.
• Couleur d’accent : laissée vide, la couleur primaire du thème est utilisée. Renseignée, elle alimente la variable CSS --df-sales-counter-accent sur l’élément du badge.
• Séparateur de milliers : espace fine, virgule, point ou aucun. Utile dès que les compteurs dépassent le millier.
• Texte personnalisé : voir la section suivante.
• Durée de cache en secondes : 900 par défaut. La valeur 0 désactive le cache et interroge la base à chaque affichage de fiche.

Personnaliser le texte

Texte global depuis la configuration

Le champ Texte personnalisé accepte une phrase avec le marqueur %count% à l’endroit où le nombre doit apparaître. Exemple : Ce modèle est parti %count% fois ce mois-ci. Ce texte est commun à toutes les langues du canal de vente. Il est nettoyé avant rendu, ce qui autorise un balisage simple comme <strong> mais bloque tout script.

Textes par langue via les snippets

Laissez le champ Texte personnalisé vide pour piloter le texte langue par langue. Ouvrez Paramètres, Boutique, Fragments de texte, puis recherchez dfSalesCounter. Quatre clés sont disponibles :

• dfSalesCounter.badge.quantitySingular et dfSalesCounter.badge.quantityPlural, utilisées en mode quantité vendue.
• dfSalesCounter.badge.ordersSingular et dfSalesCounter.badge.ordersPlural, utilisées en mode nombre de commandes.

Chaque valeur accepte le marqueur %count%. Les traductions française, anglaise, espagnole, allemande et italienne sont livrées avec le plugin. Une valeur modifiée dans le gestionnaire de fragments prend le pas sur celle du plugin, y compris après une mise à jour.

Comment le chiffre est calculé

Le plugin lit les lignes de commande de type produit, jointes à la commande et à son état. Le calcul se fait en une seule requête agrégée, sans traitement en arrière-plan et sans table dédiée.

• En mode quantité, la requête somme la colonne des quantités des lignes de commande.
• En mode commandes, elle compte les identifiants de commande distincts.
• Seule la version courante des commandes est prise en compte, les versions de travail créées lors d’un avoir ou d’une modification de commande sont ignorées.
• Avec le cumul des déclinaisons activé, le plugin résout d’abord la famille du produit affiché, produit parent et variantes, puis filtre sur l’ensemble des identifiants.

Si le résultat est inférieur au seuil configuré, aucune extension n’est ajoutée au produit et le template ne rend rien. Le badge n’existe donc pas dans le HTML, ce qui évite tout affichage résiduel via une règle CSS de thème.

Cache et fraîcheur du chiffre

Le résultat est stocké dans le pool de cache applicatif de Symfony, sous une clé qui combine l’identifiant du produit, le canal de vente et une signature des options influençant le calcul. Une modification du mode de comptage, de la portée des commandes, de la période ou des options de cumul change cette signature et invalide donc mécaniquement les valeurs précédentes.

À chaque commande passée, le plugin purge le cache des produits contenus dans cette commande, ainsi que celui de leur produit parent. Le compteur reflète donc la vente sans attendre l’expiration de la durée configurée.

Sur un catalogue de taille modeste, la durée de cache peut être ramenée à 0 sans conséquence notable : la requête porte sur des colonnes indexées. Sur un gros catalogue à fort trafic, conservez une durée de plusieurs minutes.

Personnalisation avancée du rendu

Le plugin surcharge le buy-widget de la page produit et ajoute son badge dans trois blocs Twig standards, selon l’emplacement choisi : le bloc du nom du produit, le bloc du conteneur de prix et le bloc du conteneur d’achat. Le badge lui-même est rendu par un template de composant dédié, storefront/component/df-sales-counter/badge.html.twig, qui expose deux blocs surchargeables pour l’icône et pour le texte.

Depuis un thème ou un plugin, l’extension est accessible dans Twig sur le produit de la page sous le nom dfSalesCounter. Elle expose le nombre brut, le nombre formaté, l’emplacement, le style, l’icône, la couleur d’accent, le texte personnalisé et le mode de comptage. Vous pouvez ainsi rendre le compteur ailleurs que dans le bloc d’achat, par exemple dans un onglet d’informations produit, en récupérant l’extension et en incluant le composant.

Les styles sont définis dans Resources/app/storefront/src/scss/base.scss autour des classes df-sales-counter, df-sales-counter__icon et df-sales-counter__text, avec un modificateur par style visuel. Toute règle de votre thème compilée après celle du plugin prend le dessus, sans qu’il soit nécessaire de modifier le plugin.

Dépannage

Aucun badge n’apparaît

Vérifiez dans l’ordre : le plugin est activé, l’interrupteur d’activation est sur oui pour le bon canal de vente, le produit a atteint le seuil configuré, et la portée des commandes retenue n’exclut pas toutes vos commandes. Un seuil à 5 avec une portée Commandes payées uniquement sur une boutique de test dont les commandes ne sont jamais marquées payées ne produira jamais d’affichage.

Le badge apparaît sans style

Le thème n’a pas été recompilé après l’activation. Lancez bin/console theme:compile ou utilisez le bouton de recompilation dans l’administration.

Le chiffre semble figé

La durée de cache est encore en cours. Videz le cache applicatif avec bin/console cache:pool:clear cache.app, ou ramenez temporairement la durée à 0 pour valider le calcul.

Le badge ne se place pas au bon endroit

Un thème très personnalisé peut avoir supprimé ou renommé les blocs Twig du bloc d’achat. Essayez un autre emplacement dans la configuration, ou incluez le composant manuellement dans votre template en récupérant l’extension du produit.

Mise à jour et désinstallation

Une mise à jour s’effectue par téléversement du nouveau ZIP puis clic sur Mettre à jour, suivi d’une recompilation du thème si la version contient des changements de style. La configuration est conservée.

À la désinstallation, une case propose de conserver les données utilisateur. Décochée, l’ensemble des clés de configuration du plugin est supprimé. Le plugin ne crée aucune table et n’exécute aucune migration, la désinstallation ne laisse donc rien en base au-delà de sa configuration.

Référence des clés de configuration

Toutes les clés sont préfixées par DfSalesCounter.config. et manipulables par l’API Admin ou par la commande system:config:set :

• active, booléen
• countMode, valeurs quantity ou orders
• orderScope, valeurs all, notCancelled ou paid
• minThreshold, entier
• periodDays, entier
• aggregateVariants, booléen
• scopeToSalesChannel, booléen
• position, valeurs afterName, afterPrice ou afterBuy
• style, valeurs badge, inline ou banner
• icon, valeurs none, flame, cart ou check
• accentColor, chaîne hexadécimale
• thousandSeparator, valeurs space, comma, dot ou none
• customText, chaîne
• cacheTtl, entier en secondes