DataFirefly Live Counters

DataFirefly Live Counters affiche sur votre site WordPress/WooCommerce des compteurs animés (clients, commandes, abonnés sociaux, KPI maison) qui restent justes même quand le site entier est servi depuis un full-page cache comme LiteSpeed Cache ou WP Rocket.

Installation et démarrage

Prérequis

• WordPress 6.2 ou supérieur (testé sur 6.7).
• PHP 8.1 ou supérieur.
• WooCommerce 7.0+ recommandé pour les compteurs boutique. Sans WooCommerce, les compteurs sociaux et KPI personnalisés restent pleinement fonctionnels.
• Polylang ou WPML facultatif pour les libellés multilingues.

Installation

1. Téléchargez le fichier dflivecounters.zip depuis votre compte DataFirefly.
2. Dans WordPress, allez dans Extensions → Ajouter une extension → Téléverser une extension.
3. Choisissez le zip puis cliquez sur Installer maintenant.
4. Activez l’extension. Un nouvel élément Live Counters apparaît dans le menu WooCommerce (ou Réglages si WooCommerce n’est pas installé).

Premier affichage en 30 secondes

Placez ce shortcode dans n’importe quelle page ou article :

[dflivecounters]

Au premier chargement, une grille de quatre compteurs apparaît avec une animation count-up. Les chiffres sont calculés depuis votre catalogue WooCommerce et mis en cache.

Réglages généraux

Allez dans WooCommerce → Live Counters. La page est organisée en quatre cartes, suivie d’un aperçu en direct et d’un bouton de vidage de cache.

Carte « Affichage & cache »

• Style : Cartes, Minimaliste, Dégradé.
• Colonnes : entre 1 et 6. Responsive : 2 colonnes sur mobile, 1 sur très petit écran.
• Couleur d’accent : utilisée pour icônes, chiffres (cartes) et fond (dégradé). Défaut #0f172a.
• Durée animation (ms) : 200 à 8 000. 0 désactive l’animation.
• Cache compteurs (min) : 60 par défaut.
• Cache réseaux sociaux (min) : 360 par défaut (APIs sociales rate-limited).
• Abréger les grands nombres : affiche 12,4 k au lieu de 12 400.
• Ajouter « + » aux compteurs cumulatifs.
• Pré-chauffer le cache automatiquement (cron) : Action Scheduler en priorité, WP-Cron en fallback.

Statuts de commande comptés

• Statuts comptés (clients, commandes, articles, pays) : par défaut Processing et Completed.
• Statuts « expédiés » : utilisé uniquement pour Produits expédiés. Par défaut Completed.

Date de création

Le compteur Années d’expérience calcule sa valeur à partir de la date renseignée dans « Date de création ».

Vider et régénérer le cache

Le bouton « ↻ Vider et régénérer le cache maintenant » supprime tous les transients du plugin et déclenche un warm-up immédiat. Toute modification des réglages vide automatiquement le cache et reprogramme le warm-up.

Compteurs WooCommerce

Liste des compteurs disponibles

• Clients satisfaits (customers) : adresses email distinctes ayant passé une commande dans un statut compté.
• Produits expédiés (shipped) : somme des quantités d’articles dans les commandes « expédié ».
• Commandes traitées (orders).
• Articles vendus (items_sold) : somme des quantités sur toutes les lignes.
• Produits au catalogue (products).
• Avis clients (reviews) : avis approuvés.
• Pays livrés (countries).
• Années d’expérience (years) : à partir de la date de création.

Activer et personnaliser un compteur

Dans le tableau « Compteurs boutique », cochez Actif et optionnellement :

• Renseignez un libellé personnalisé.
• Choisissez une période (voir section dédiée).
• Ajoutez un offset pour intégrer un historique antérieur (par exemple 1 200 clients hérités d’une précédente boutique).
• Définissez un objectif qui activera la barre de progression.

Compatibilité HPOS

Le plugin détecte automatiquement HPOS (High-Performance Order Storage) ou le stockage legacy (CPT). Les requêtes sont écrites en deux versions optimisées. La compatibilité HPOS et Cart/Checkout Blocks est déclarée via le hook before_woocommerce_init.

Compteurs sociaux et KPI personnalisés

Réseaux sociaux supportés

• Facebook et Instagram — récupération automatique via l’API Meta Graph v19 (Instagram en compte Business ou Creator uniquement).
• TikTok, X (Twitter), LinkedIn, YouTube — saisie manuelle.

TikTok, X et LinkedIn n’exposent pas de compteur d’abonnés via une API publique fiable, d’où la saisie manuelle.

Configurer Facebook ou Instagram via l’API Meta Graph

1. Créez une application sur developers.facebook.com.
2. Générez un jeton d’accès longue durée avec la permission pages_read_engagement (Facebook) ou instagram_basic + pages_show_list (Instagram).
3. Récupérez l’ID de la Page Facebook ou de l’IG Business.
4. Dans la carte « Réseaux sociaux », cochez « Récupérer via l’API », collez l’ID dans ID objet et le jeton dans Jeton d’accès.

Si l’appel API échoue (jeton expiré, rate limit), le plugin conserve la dernière valeur connue. Le champ « manuel » sert de fallback ultime.

Compteurs KPI personnalisés

Dans la carte « Compteurs personnalisés (KPI) », cliquez sur « + Ajouter un compteur », puis renseignez : icône (users, award, heart, leaf, download…), libellé, valeur, préfixe optionnel (« $ », « + »), suffixe optionnel (« %, h, M »), objectif optionnel.

Périodes, objectifs et tendance

Périodes par compteur

Compteurs qui agrègent dans le temps (customers, shipped, orders, items_sold, reviews, countries) peuvent être restreints :

• Total : comportement par défaut.
• Cette année : depuis le 1^er janvier.
• Ce mois : depuis le 1^er du mois.
• 30 derniers jours : fenêtre glissante.

L’effet « 124 commandes ce mois-ci » est souvent plus engageant que « 9 421 commandes ».

Objectifs et barre de progression

Renseigner un objectif dans la colonne « Objectif (0 = aucun) » active automatiquement une barre sous le compteur, animée en même temps que le count-up, jusqu’à min(100 %, valeur / objectif). Disponible aussi sur les compteurs sociaux et personnalisés.

Indicateur de tendance ▲/▼

Une puce colorée apparaît à côté du chiffre :

• ▲ vert si la valeur a augmenté depuis le snapshot précédent.
• ▼ rouge si elle a baissé.
• Aucune puce si la variation est nulle ou si l’historique est insuffisant.

Le pourcentage est calculé sur une fenêtre glissante de 7 jours par défaut, modifiable via le filtre dflc_trend_window. Les baselines sont stockés dans une option WordPress unique (dflc_trend).

Affichage : bloc, widget, shortcode

Bloc Gutenberg

Dans l’éditeur de bloc, cherchez « DataFirefly Live Counters » (catégorie « Widgets »). Le panneau d’inspection permet de configurer colonnes, style et liste des compteurs à afficher. L’aperçu utilise ServerSideRender, identique au rendu front.

Widget classique

Dans Apparence → Widgets, ajoutez « DataFirefly Live Counters ». Champs : titre, colonnes (0 à 6), style, clés (liste séparée par des virgules ou vide = tous les compteurs activés).

Shortcode

[dflivecounters]
[dflivecounters keys="customers,orders,reviews" columns="3"]
[dflivecounters keys="social_facebook,social_instagram" columns="2" style="gradient"]
[dflivecounters keys="custom_0,custom_1" style="minimal"]

Attributs supportés : keys (string, liste de clés), columns (int 1-6), style (cards, minimal, gradient).

Liste des clés disponibles

Compteur	Clé
Clients	customers
Produits expédiés	shipped
Commandes traitées	orders
Articles vendus	items_sold
Produits au catalogue	products
Avis clients	reviews
Pays livrés	countries
Années d’expérience	years
Réseaux sociaux	social_facebook, social_instagram, social_tiktok, social_twitter, social_linkedin, social_youtube
Compteurs personnalisés	custom_0, custom_1, etc.

Insertion dans un thème (PHP)

echo do_shortcode( '[dflivecounters keys="customers,orders" columns="2"]' );

Architecture du cache

Le problème

Quand un cache de page (LiteSpeed, WP Rocket, NGINX micro-cache, Varnish, Cloudflare APO) sert une HTML pré-générée, tout chiffre rendu en PHP est figé. La réponse classique — désactiver le cache sur ces pages — dégrade gravement les performances.

Le principe : séparer structure et valeurs

• Structure cacheable : grille, icônes, libellés et emplacements vides, rendus côté serveur, parfaitement cacheables.
• Valeurs non cacheables : récupérées par fetch() vers une route REST dédiée, avec un en-tête Cache-Control court.

Le visiteur reçoit instantanément le HTML caché, puis les chiffres se remplissent en JavaScript avec une animation count-up.

Transient cache + warm-up

La route REST ne fait jamais de requête SQL lourde pendant la visite. Elle lit des transients WordPress, pré-chauffés par Action Scheduler (job dflc_warm_cache) ou par WP-Cron en fallback.

Stale-while-revalidate

Si un transient expire pile entre deux warm-ups :

1. La dernière valeur connue est lue depuis l’option persistante dflc_lastgood (qui survit à l’expiration du transient) et renvoyée immédiatement.
2. Un job de refresh asynchrone est programmé.
3. Un verrou court (2 minutes) empêche d’empiler plusieurs refresh concurrents.

Le cold start réel n’arrive qu’au tout premier affichage après installation.

Sécurité de l’endpoint REST

• Lecture publique uniquement.
• Whitelist des clés : seules les clés correspondant à des compteurs réellement configurés sont acceptées.
• En-tête Cache-Control: public, max-age=... dimensionné sur le TTL des compteurs.

API développeur

Cinq filtres PHP permettent d’étendre le plugin sans toucher au cœur.

dflc_counter_definitions

Ajouter, réordonner ou masquer des compteurs.

add_filter( 'dflc_counter_definitions', static function ( array $items, array $settings ) {
    $items[] = array(
        'key'        => 'newsletter_subscribers',
        'label'      => 'Abonnés newsletter',
        'icon'       => 'heart',
        'suffix'     => '+',
        'prefix'     => '',
        'abbreviate' => true,
        'goal'       => 5000,
    );
    return $items;
}, 10, 2 );

dflc_compute

Court-circuite le calcul. Retourner un entier prend la main, null laisse le core gérer.

add_filter( 'dflc_compute', static function ( $pre, string $key, array $settings ) {
    if ( 'newsletter_subscribers' === $key ) {
        return (int) get_option( 'my_newsletter_count', 0 );
    }
    return $pre;
}, 10, 3 );

dflc_counter_value

Filtre la valeur finale juste avant l’envoi au front.

add_filter( 'dflc_counter_value', static function ( int $value, string $key ) {
    if ( 'customers' === $key && $value < 1000 ) {
        return 1000;
    }
    return $value;
}, 10, 2 );

dflc_payload

Filtre la totalité du payload REST.

add_filter( 'dflc_payload', static function ( array $payload, array $only, bool $force ) {
    foreach ( $payload as &$item ) {
        $item['emoji'] = '🎉';
    }
    return $payload;
}, 10, 3 );

dflc_trend_window

Modifie la fenêtre glissante de tendance. Valeur en secondes, défaut 7 * DAY_IN_SECONDS.

add_filter( 'dflc_trend_window', static fn() => 30 * DAY_IN_SECONDS );

Recette : compteur Mailchimp

add_filter( 'dflc_counter_definitions', static function ( array $items ) {
    $items[] = array(
        'key' => 'mailchimp_subs', 'label' => 'Abonnés newsletter',
        'icon' => 'heart', 'suffix' => '+', 'prefix' => '',
        'abbreviate' => true, 'goal' => 0,
    );
    return $items;
} );

add_filter( 'dflc_compute', static function ( $pre, string $key ) {
    if ( 'mailchimp_subs' !== $key ) {
        return $pre;
    }
    $response = wp_remote_get( 'https://us1.api.mailchimp.com/3.0/lists/LIST_ID', array(
        'headers' => array( 'Authorization' => 'Bearer ' . MAILCHIMP_API_KEY ),
    ) );
    if ( is_wp_error( $response ) ) {
        return 0;
    }
    $body = json_decode( wp_remote_retrieve_body( $response ), true );
    return (int) ( $body['stats']['member_count'] ?? 0 );
}, 10, 2 );

Dépannage

Les chiffres ne s'animent pas

• Vérifier que le script dflc-front.js se charge (onglet réseau).
• Vérifier que la route REST /wp-json/dflivecounters/v1/counters répond en 200 avec un JSON valide.
• Tester avec un autre thème.

Les chiffres affichent toujours « — »

• L'appel REST a échoué. Vérifier la console JS.
• La route REST peut être bloquée par une extension de sécurité.

Les chiffres ne se mettent pas à jour

• Vérifier que « Pré-chauffer le cache automatiquement » est activé.
• Sur sites à faible trafic, envisager un vrai cron système au lieu de WP-Cron.
• Forcer un rafraîchissement via le bouton « ↻ Vider et régénérer le cache maintenant ».

L'appel API Meta retourne 0

• Vérifier la validité du jeton sur Access Token Debugger.
• Vérifier que le compte Instagram est bien Business ou Creator.

Notice WP 6.7 « _load_textdomain_just_in_time »

Corrigée depuis la version 1.1.1.