DataFirefly Live Counters — Guide complet

DataFirefly Live Counters affiche sur votre boutique PrestaShop un widget de compteurs animés alimenté en partie automatiquement par votre base (clients actifs, commandes expédiées, produits, pays livrés) et en partie par des valeurs que vous saisissez (avis, satisfaction, abonnés réseaux sociaux…). Le widget se positionne nativement sur plusieurs hooks (accueil, footer, panier, colonnes) ou n’importe où dans votre thème via la balise Smarty widget name="dflivecounters". Cette documentation couvre l’installation, la configuration des 17 compteurs disponibles, les 5 thèmes visuels, la stratégie de cache, le branchement des APIs Facebook et Instagram, le refresh AJAX live et la résolution des principaux problèmes.

Installation

1. Téléchargez l’archive dflivecounters.zip depuis votre compte DataFirefly.
2. Back-office PrestaShop → Modules → Téléverser un module → envoyez le ZIP.
3. À l’installation, le module enregistre 7 hooks d’affichage et initialise une dizaine de variables de configuration. Aucune table SQL n’est créée : tous les réglages sont stockés dans ps_configuration.
4. Le module charge son autoloader PSR-4 standalone — aucun composer install requis sur le serveur.

Apparence du widget

Ouvrez Modules → DataFirefly Live Counters → Configurer. La première section regroupe les réglages d’apparence globale.

Thème visuel

Cinq thèmes prêts à l’emploi :

• Minimal : sobriété maximale, fond blanc, idéal pour les thèmes épurés.
• Glassmorphism : verre dépoli avec backdrop-blur, fond légèrement teinté de la couleur primaire. Très tendance.
• Gradient : fond en dégradé pleine largeur de la couleur primaire vers une teinte sombre. Fort impact visuel, texte blanc.
• Card : cartes blanches élevées avec ombre douce et hover. Classique premium.
• Flat : fond légèrement teinté de la couleur primaire, valeurs colorées en primaire.

Titre et sous-titre

Affichés au-dessus du grid de compteurs. Laissez vides pour masquer l’en-tête (utile dans le footer où le contexte est déjà donné par l’environnement).

Couleurs

Trois couleurs principales pilotent l’ensemble du widget via des variables CSS (--dflc-primary, --dflc-text, --dflc-bg) :

• Couleur principale : icônes par défaut, accent du thème Flat, dégradé du thème Gradient.
• Couleur du texte : titre, sous-titre, valeurs et labels.
• Couleur de fond : fond de la section (ignoré sur les thèmes Glassmorphism et Gradient qui appliquent leur propre fond).

Colonnes

Deux réglages indépendants :

• Colonnes desktop : 1 à 6 (par défaut 4).
• Colonnes mobile : 1 à 3 (par défaut 2). Le breakpoint est 768 px.

Durée de l’animation CountUp

Durée en millisecondes pendant laquelle les chiffres défilent de 0 vers leur valeur cible (par défaut 2 000 ms). Une courbe d’ease-out cubique est appliquée pour une décélération douce. Mettez 0 pour désactiver l’animation et afficher la valeur finale tout de suite.

Refresh AJAX live (optionnel)

Lorsqu’activé, le widget interroge périodiquement un endpoint JSON pour mettre à jour les valeurs sans rechargement de page. Deux paramètres :

• Live refresh : ON/OFF.
• Intervalle : en secondes, minimum 30 (par défaut 60). Réglage forcé à 30 si vous saisissez moins.

L’endpoint répond avec un Cache-Control: public, max-age=30 qui permet à votre CDN d’absorber le trafic. L’animation de transition d’une valeur à l’autre démarre depuis la valeur précédemment affichée, pas depuis zéro — l’effet visuel est plus naturel.

« Date from »

Date de référence utilisée par deux compteurs :

• Commandes expédiées : ne comptabilise que les commandes créées après cette date (filtre WHERE date_add >= ?).
• Années d’expertise : calcule automatiquement le nombre d’années écoulées depuis cette date jusqu’à aujourd’hui.

Catalogue des compteurs

17 compteurs sont disponibles, répartis en trois groupes selon leur mode de calcul.

Compteurs automatiques (5)

Ces compteurs lisent en temps réel les données de votre PrestaShop. Aucune saisie nécessaire.

• Clients : clients actifs (active = 1 AND deleted = 0), scopés au shop context. TTL 15 min.
• Commandes expédiées : commandes dont au moins un historique de statut figure parmi les états sélectionnés (champ « Order states counted as shipped »). Si aucun état n’est sélectionné, le module utilise automatiquement le flag shipped = 1 de la table ps_order_state. TTL 15 min.
• Commandes traitées : toutes les commandes dont l’état courant a le flag logable = 1 (le flag canonique PrestaShop pour les commandes qui comptent dans les statistiques). Exclut donc les annulations et remboursements. TTL 15 min.
• Produits : produits actifs et visibles du catalogue, scopés au shop context. TTL 30 min.
• Pays livrés : nombre de pays distincts ayant reçu au moins une commande (COUNT(DISTINCT id_country) sur la table ps_address jointe à ps_orders). TTL 1 h.

Compteurs hybrides (4)

Ces compteurs tentent d’abord un calcul automatique, puis basculent sur la valeur manuelle que vous avez saisie en backup.

• Années d’expertise : calculé depuis la date « Date from » ; valeur manuelle si vous préférez fixer un chiffre arrondi (ex : « 12 » au lieu de « 11 »). TTL 24 h.
• Articles publiés : auto-détection des tables des principaux modules de blog PrestaShop (smart_blog_post, prestablog_news, psblog_post, ph_simpleblog_post) via INFORMATION_SCHEMA. Si aucune correspondance, utilisez la valeur manuelle. TTL 24 h.
• Abonnés Facebook : appel à la Graph API Facebook avec un Page Access Token longue durée. Fallback manuel si non configuré ou si l’API échoue. TTL 1 h.
• Abonnés Instagram : appel à la Graph API Instagram (compte Business ou Creator requis). Fallback manuel. TTL 1 h.

Compteurs manuels (8)

Ces compteurs affichent simplement la valeur que vous saisissez. Idéaux pour les métriques que PrestaShop ne peut pas calculer ou que vous voulez maîtriser totalement.

• Avis clients : nombre d’avis (depuis Trustpilot, Avis Vérifiés, Google, etc.).
• Satisfaction : taux de satisfaction. Astuce : utilisez un suffixe « % » et une valeur 0–100.
• CO₂ économisé : kg d’émissions évitées. Astuce : suffixe « kg ».
• Récompenses : prix, certifications, distinctions.
• Heures de support : suffixe « h ».
• Abonnés TikTok : la Display API TikTok nécessite un OAuth par utilisateur impraticable pour un widget public. Saisie manuelle.
• Abonnés X (Twitter) : l’API X v2 est payante. Saisie manuelle.
• Abonnés LinkedIn : LinkedIn Organization Followers requiert une approbation Marketing Developer Platform. Saisie manuelle.

Configuration par compteur

Chaque ligne de compteur dans l’admin propose les mêmes réglages :

• Activé (ON/OFF) : seuls les compteurs activés apparaissent dans le widget. L’ordre d’affichage suit celui de l’admin.
• Libellé personnalisé : remplace le libellé par défaut. Laissez vide pour utiliser le libellé natif traduit dans la langue du visiteur.
• Valeur (manuel) : pour les compteurs manuels et le fallback des hybrides.
• Offset : entier ajouté à la valeur calculée. Pratique pour partir d’un chiffre flatteur sans toucher à votre base de données. Pour les compteurs « Clients » et « Commandes expédiées » par exemple, vous pouvez ajouter respectivement +500 et +2 000 si votre boutique vient d’être migrée. Le label « Current live » à côté du champ Offset vous indique la valeur brute calculée par PrestaShop, sans offset.
• Préfixe / Suffixe : 4 et 6 caractères respectivement. Le préfixe et le suffixe restent fixes même pendant l’animation.
• Décimales : 0 à 3. Le formatage utilise Intl.NumberFormat avec la locale du visiteur (séparateurs de milliers et virgule décimale localisés).
• Couleur d’icône : remplace la couleur primaire pour cette icône uniquement.

États de commande « expédiés »

Le compteur « Commandes expédiées » s’appuie par défaut sur l’historique des statuts. Le réglage Order states counted as shipped vous laisse choisir précisément les états qui comptent. Sur une installation PrestaShop standard, ce sont les états ID 4 (Expédiée) et 5 (Livrée) qui sont préconfigurés.

Si aucun état n’est sélectionné, le module bascule sur un fallback qui interroge le flag shipped = 1 de la table ps_order_state. Cette approche est plus permissive et capture la plupart des configurations courantes.

Configurer Facebook

1. Rendez-vous sur developers.facebook.com et créez une App de type « Business ».
2. Dans la section Graph API Explorer, sélectionnez votre App puis votre Page Facebook.
3. Générez un Page Access Token avec les scopes pages_read_engagement et pages_show_list.
4. Échangez ce token court (1 h) contre un token longue durée (60 jours) via l’endpoint /oauth/access_token?grant_type=fb_exchange_token.
5. Récupérez votre Page ID dans les paramètres de votre Page (section « Transparence de la Page » ou directement dans le Graph API Explorer).
6. Renseignez les deux champs dans la configuration Live Counters et sauvez. Le compteur Facebook se met à jour à la sauvegarde.

Configurer Instagram

1. Votre compte Instagram doit être en mode Business ou Creator. Les comptes personnels ne sont pas supportés par la Graph API.
2. Liez votre compte Instagram à une Page Facebook (paramètres de la Page → Instagram).
3. Dans le Graph API Explorer, interrogez /me/accounts avec votre Page Access Token pour récupérer le Instagram User ID associé (champ instagram_business_account).
4. Utilisez le même token Facebook longue durée pour l’API Instagram.
5. Renseignez l’IG User ID et le token dans la configuration Live Counters.

Stratégie de cache

Le cache fonctionne sur deux niveaux pour garantir un TTFB constant même sous trafic.

Cache par compteur

Chaque compteur a son propre TTL :

• 15 minutes : Clients, Commandes expédiées, Commandes traitées.
• 30 minutes : Produits.
• 1 heure : Pays livrés, Facebook, Instagram.
• 24 heures : Années d’expertise, Articles publiés, et tous les compteurs manuels.

Le cache utilise d’abord la couche Cache native PrestaShop (memcached, APCu ou Redis si configurés sur votre serveur), puis un fallback filesystem dans var/cache/dflivecounters/. Cela garantit que les TTL sont respectés même si la couche native est en mode « no-cache ».

Cache du widget rendu

Le HTML complet du widget est lui-même mis en cache pendant 60 secondes par langue et par hook (dflc_widget_LANG_HASH). Cette deuxième couche absorbe la majorité du trafic même lorsque les compteurs internes sont déjà à jour.

Purge automatique

• La sauvegarde de la configuration purge automatiquement tous les caches du module.
• Un bouton Purger le cache est disponible dans le panneau d’administration pour invalidation manuelle.
• La désinstallation du module purge le cache automatiquement.

Placer le widget dans votre thème

Le module enregistre 7 hooks à l’installation :

• displayHome — page d’accueil
• displayFooter — pied de page
• displayFooterBefore — juste avant le footer (PS 8+)
• displayLeftColumn / displayRightColumn — colonnes latérales
• displayShoppingCartFooter — page panier, sous le résumé
• actionFrontControllerSetMedia — enregistre les assets CSS/JS

Vous pouvez ajouter ou retirer des hooks depuis Conception → Positions dans le back-office.

Placement libre via Smarty

Pour placer le widget à un endroit précis de votre thème (ex : sur la fiche produit, sous le titre d’une catégorie), utilisez la balise widget Smarty :

{widget name="dflivecounters"}

Le widget implémente l’interface WidgetInterface native PrestaShop, ce qui le rend appelable depuis n’importe quel template .tpl de votre thème.

Personnaliser le template du widget

Le template Smarty principal est views/templates/hook/widget.tpl. Pour le surcharger sans modifier le module (afin de préserver les mises à jour), recopiez-le dans votre thème, dans le dossier themes/votre-theme/modules/dflivecounters/views/templates/hook/widget.tpl.

Variables Smarty exposées :

• {$dflc.counters} — tableau de chaque compteur avec les clés key, label, value, icon, prefix, suffix, decimals, icon_color
• {$dflc.theme} — slug du thème (minimal, glassmorphism, gradient, card, flat)
• {$dflc.title}, {$dflc.subtitle}
• {$dflc.primary_color}, {$dflc.text_color}, {$dflc.bg_color}
• {$dflc.cols_desktop}, {$dflc.cols_mobile}
• {$dflc.hook} — nom du hook d’origine (utile pour adapter le rendu selon le placement)

Endpoint AJAX

Le contrôleur front refresh expose une URL JSON utilisable par le live refresh ou par toute intégration tierce :

index.php?fc=module&module=dflivecounters&controller=refresh

La réponse JSON contient un booléen success, un timestamp Unix, et un objet counters où chaque clé est l’identifiant du compteur (customers, shipped_orders, facebook, instagram, etc.) et chaque valeur est le nombre courant. Le contenu reflète les compteurs activés au moment de l’appel, avec les offsets appliqués. La réponse est servie avec Cache-Control: public, max-age=30.

Accessibilité

Le widget est conçu pour respecter les recommandations WCAG 2.2 AA :

• Structure sémantique : section, header, ul role="list", li.
• Toutes les icônes SVG ont aria-hidden="true" (décoratives).
• Respect strict de prefers-reduced-motion: reduce : animation désactivée, valeur finale affichée tout de suite.
• Contrastes : les couleurs par défaut respectent un ratio supérieur à 4.5:1 sur les thèmes Minimal et Card. Vérifiez vos couleurs personnalisées avec un outil comme axe DevTools.
• Format des nombres : font-variant-numeric: tabular-nums pour une largeur de chiffre constante (évite le « saut » visuel pendant l’animation).

RGPD

Le widget est conçu pour ne nécessiter aucune mention de consentement :

• Aucun cookie déposé côté visiteur.
• Aucun script tiers chargé (pas de Facebook Pixel, pas de Google Tag Manager).
• Les appels API Facebook et Instagram sont effectués côté serveur en PHP, jamais depuis le navigateur. Aucune donnée du visiteur n’est transmise à Meta.
• Aucune donnée personnelle collectée ou stockée par le module.

Compatibilité et notes techniques

• PrestaShop 8.0 à 9.x, PHP 8.1+.
• Multi-boutique natif : toutes les requêtes SQL sont scopées au Shop::getContextListShopID().
• Multilingue : Polylang Pro ou système multilingue natif PrestaShop.
• Aucune table SQL créée : configuration stockée dans ps_configuration.
• Autoloader PSR-4 standalone (pas de composer install sur le serveur).
• WidgetInterface PrestaShop natif : usable via {widget name="dflivecounters"}.
• Poids des assets : 3 KB JS, 2 KB CSS. Aucune requête externe par défaut.
• Conforme aux conventions PrestaShop 9 AJAX : $this->module->l() au lieu de $this->l(), controller front dédié pour le refresh, jamais d’override de ajaxRender.

FAQ et résolution des problèmes

Le widget ne s’affiche pas sur la page d’accueil. Vérifiez que le module est bien greffé au hook displayHome dans Conception → Positions. Vérifiez aussi qu’au moins un compteur est activé : sans compteur activé, le widget ne retourne rien (silencieusement).

Le compteur Facebook reste à zéro. Plusieurs causes possibles : Page ID incorrect, token expiré (durée de vie 60 jours), scope manquant (pages_read_engagement est requis). Purgez le cache du module et rechargez la configuration : la valeur retournée par Graph API apparaîtra à côté du label « Current live ».

Le compteur Commandes expédiées est trop bas. Vérifiez la sélection « Order states counted as shipped » : seuls les états sélectionnés sont comptés. Si vous voulez inclure des statuts personnalisés (ex : « Click & Collect retiré »), ajoutez-les à la sélection.

Les chiffres semblent figés et ne reflètent pas mon trafic réel. C’est le cache qui fait son travail. Le TTL par défaut va de 15 minutes (clients, commandes) à 24 heures (compteurs statiques). Utilisez le bouton Purger le cache pour invalider manuellement. Pour un rafraîchissement automatique, activez le mode Live refresh.

L’animation CountUp ne se déclenche pas. Le widget utilise IntersectionObserver et se déclenche au moment où il entre dans le viewport. Si le widget est déjà visible au chargement de la page (ex : placé tout en haut), l’animation se lance immédiatement. Si elle reste figée à zéro : vérifiez la console JavaScript de votre navigateur, un autre module pourrait casser le bundle JS.

Le widget casse mon Lighthouse / Core Web Vitals. Avec un placement bas de page (footer) et le cache de 60 s sur le HTML rendu, l’impact CLS / LCP est négligeable. Si vous constatez un problème, vérifiez que vous n’avez pas activé le Live refresh avec un intervalle trop court (l’AJAX se déclenche pendant que Lighthouse mesure). Pour un audit propre, désactivez le live refresh.

Sur multi-boutique, est-ce que les compteurs sont scopés par boutique ? Oui. Toutes les requêtes SQL utilisent Shop::getContextListShopID(). En mode « toutes les boutiques », les compteurs cumulent ; en mode « une boutique », ils ne comptent que celle-ci. Les libellés et la valeur manuelle sont également par-boutique-par-langue.

Comment ajouter un nouveau compteur personnalisé ? Créez une classe qui étend Df/LiveCounters/Counter/AbstractCounter (ou ManualCounter pour un compteur 100 % manuel), implémentez getKey(), getDefaultLabel() et getValue(), puis ajoutez l’instance au tableau d’instances du CounterRegistry. Pour ne pas perdre votre code à la prochaine mise à jour, créez un mini-module compagnon qui injecte votre compteur dans le registry via un hook custom — n’hésitez pas à nous contacter pour un exemple.