# 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…

- Page: <https://www.datafirefly.com/documentation/dflivecounters-wp/>
- Langue: fr
- Mis à jour le: 2026-06-28
- Autres langues: [en](https://www.datafirefly.com/en/documentation/dflivecounters-wp/index.md), [es](https://www.datafirefly.com/es/documentation/dflivecounters-wp/index.md), [de](https://www.datafirefly.com/de/documentation/dflivecounters-wp/index.md), [it](https://www.datafirefly.com/it/documentation/dflivecounters-wp/index.md), [pl](https://www.datafirefly.com/pl/documentation/dflivecounters-wp/index.md), [nl](https://www.datafirefly.com/nl/documentation/dflivecounters-wp/index.md), [pt](https://www.datafirefly.com/pt/documentation/dflivecounters-wp/index.md)
- Index: <https://www.datafirefly.com/documentation/llms.txt>

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](https://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 1er janvier.
- **Ce mois** : depuis le 1er 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`).

**Patience attendue.** Sur un site neuf, la puce de tendance n'apparaîtra qu'après l'écoulement de la fenêtre (par défaut 7 jours).

## 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.

**Attention.** Si votre CDN ignore le `Cache-Control` de la route REST et la cache agressivement, les chiffres seront figés au niveau du CDN. Excluez `/wp-json/dflivecounters/v1/counters` de votre cache CDN si vous observez ce comportement.

## 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](https://developers.facebook.com/tools/debug/accesstoken/).
- 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.