# DataFirefly Live Counters

> DataFirefly Live Counters mostra sul tuo sito WordPress/WooCommerce contatori animati (clienti, ordini, follower social, KPI personali) che rimangono accurati anche quando l'intero sito è servito da una full-page cache come…

- Pagina: <https://www.datafirefly.com/it/documentation/dflivecounters-wp/>
- Lingua: it
- Aggiornato il: 2026-06-28
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dflivecounters-wp/index.md), [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), [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)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

DataFirefly Live Counters mostra sul tuo sito WordPress/WooCommerce contatori animati (clienti, ordini, follower social, KPI personali) che rimangono accurati anche quando l'intero sito è servito da una full-page cache come LiteSpeed Cache o WP Rocket.

## Installazione e avvio rapido

### Prerequisiti

- WordPress 6.2 o superiore (testato su 6.7).
- PHP 8.1 o superiore.
- WooCommerce 7.0+ consigliato per i contatori negozio. Senza WooCommerce, i contatori social e KPI personalizzati restano pienamente funzionali.
- Polylang o WPML opzionali per le etichette multilingue.

### Installazione

1. Scarica il file `dflivecounters.zip` dal tuo account DataFirefly.
2. In WordPress, vai su **Plugin → Aggiungi nuovo → Carica plugin**.
3. Scegli il zip e clicca su **Installa ora**.
4. Attiva il plugin. Una nuova voce **Live Counters** appare nel menu WooCommerce.

### Prima visualizzazione in 30 secondi

```
[dflivecounters]
```

Al primo caricamento, una griglia di quattro contatori appare con un'animazione count-up. I numeri sono calcolati dal tuo catalogo WooCommerce e messi in cache.

## Impostazioni generali

Vai su **WooCommerce → Live Counters**. La pagina ha quattro schede, seguite da un'anteprima in tempo reale e un pulsante per svuotare la cache.

### Scheda «Visualizzazione e cache»

- **Stile**: `Card`, `Minimal`, `Gradiente`.
- **Colonne**: tra 1 e 6. Responsive: 2 colonne su mobile, 1 su schermo molto piccolo.
- **Colore d'accento**: per icone, numeri (card) e sfondo (gradiente). Predefinito `#0f172a`.
- **Durata animazione (ms)**: 200 a 8.000. 0 disabilita l'animazione.
- **Cache contatori (min)**: 60 predefinito.
- **Cache social (min)**: 360 predefinito (API social rate-limited).
- **Abbreviare i grandi numeri**: mostra `12,4k`.
- **Aggiungere «+» ai contatori cumulativi**.
- **Pre-riscaldare la cache automaticamente (cron)**: Action Scheduler prioritario, WP-Cron fallback.

### Stati ordine conteggiati

- **Stati conteggiati**: predefinito `In lavorazione` e `Completato`.
- **Stati «spediti»**: solo per _Prodotti spediti_. Predefinito `Completato`.

### Data di inizio attività

Il contatore _Anni di esperienza_ si calcola dalla data nel campo **«Data di fondazione»**.

### Svuotare e rigenerare la cache

Il pulsante **«↻ Svuota e rigenera la cache ora»** rimuove tutti i transient e attiva un warm-up immediato. Ogni modifica delle impostazioni svuota automaticamente la cache.

## Contatori WooCommerce

### Lista dei contatori disponibili

- **Clienti soddisfatti** (`customers`).
- **Prodotti spediti** (`shipped`).
- **Ordini elaborati** (`orders`).
- **Articoli venduti** (`items_sold`).
- **Prodotti nel catalogo** (`products`).
- **Recensioni clienti** (`reviews`).
- **Paesi serviti** (`countries`).
- **Anni di esperienza** (`years`).

### Attivare e personalizzare un contatore

- Etichetta personalizzata.
- Periodo (vedi sezione dedicata).
- Offset per integrare storico precedente.
- Obiettivo che attiva la barra di avanzamento.

### Compatibilità HPOS

Il plugin rileva automaticamente HPOS o lo storage legacy. Le query sono scritte in due versioni ottimizzate. La compatibilità è dichiarata tramite l'hook `before_woocommerce_init`.

## Contatori social e KPI personalizzati

### Reti social supportate

- **Facebook** e **Instagram** — recupero automatico tramite API Meta Graph v19 (Instagram solo account Business o Creator).
- **TikTok**, **X**, **LinkedIn**, **YouTube** — inserimento manuale.

### Configurare Facebook o Instagram tramite API Meta Graph

1. Crea un'app su [developers.facebook.com](https://developers.facebook.com).
2. Genera un token di lunga durata con `pages_read_engagement` (FB) o `instagram_basic` + `pages_show_list` (IG).
3. Ottieni l'ID della pagina o dell'account Business.
4. Seleziona **«Recupera tramite API»**, incolla ID e token.

Se la chiamata API fallisce, il plugin conserva l'ultimo valore noto. Il campo «manuale» funge da fallback finale.

### Contatori KPI personalizzati

Nella scheda **«Contatori personalizzati (KPI)»**, clic su **«+ Aggiungi contatore»**, poi: icona, etichetta, valore, prefisso opzionale, suffisso opzionale, obiettivo opzionale.

## Periodi, obiettivi e tendenza

### Periodi per contatore

Contatori che supportano periodi: `customers`, `shipped`, `orders`, `items_sold`, `reviews`, `countries`.

- **Totale**: comportamento predefinito.
- **Quest'anno**: dal 1° gennaio.
- **Questo mese**: dal 1° del mese.
- **Ultimi 30 giorni**: finestra mobile.

### Obiettivi e barra di avanzamento

Indicare un obiettivo nella colonna **«Obiettivo (0 = nessuno)»** attiva automaticamente una barra animata fino a `min(100%, valore / obiettivo)`.

### Indicatore di tendenza ▲/▼

Un badge colorato appare accanto al numero: ▲ verde se aumentato, ▼ rosso se diminuito, nessuno se variazione nulla o storico insufficiente. Finestra mobile di 7 giorni predefinita, configurabile tramite il filtro `dflc_trend_window`. Baseline in una singola opzione `dflc_trend`.

**Pazienza richiesta.** Su un sito nuovo, il badge appare solo dopo lo scadere della finestra (7 giorni di default).

## Visualizzazione: blocco, widget, shortcode

### Blocco Gutenberg

Nell'editor a blocchi, cerca **«DataFirefly Live Counters»** (categoria «Widget»). Il pannello di ispezione permette di configurare colonne, stile e lista dei contatori. Anteprima identica al rendering sul front.

### Widget classico

In **Aspetto → Widget**, aggiungi **«DataFirefly Live Counters»**. Campi: titolo, colonne (0 a 6), stile, chiavi (lista separata da virgole).

### 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"]
```

Attributi: `keys` (string), `columns` (int 1-6), `style` (`cards`, `minimal`, `gradient`).

### Chiavi disponibili

| Contatore | Chiave |
| --- | --- |
| Clienti | `customers` |
| Prodotti spediti | `shipped` |
| Ordini elaborati | `orders` |
| Articoli venduti | `items_sold` |
| Prodotti nel catalogo | `products` |
| Recensioni clienti | `reviews` |
| Paesi serviti | `countries` |
| Anni di esperienza | `years` |
| Social | `social_facebook`, `social_instagram`, `social_tiktok`, `social_twitter`, `social_linkedin`, `social_youtube` |
| Contatori personalizzati | `custom_0`, `custom_1`, ecc. |

### Inserimento in un tema (PHP)

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

## Architettura della cache

### Il problema

Quando una cache di pagina (LiteSpeed, WP Rocket, NGINX micro-cache, Varnish, Cloudflare APO) serve HTML pre-generato, qualsiasi numero renderizzato in PHP viene congelato. Disabilitare la cache su queste pagine degrada gravemente le performance.

### Il principio: separare struttura e valori

- **Struttura cacheable**: griglia, icone, etichette e slot vuoti, renderizzati lato server.
- **Valori non cacheable**: recuperati tramite `fetch()` a una rotta REST dedicata con header `Cache-Control` breve.

### Cache transient + warm-up

La rotta REST non esegue mai una query SQL pesante durante la visita. Legge transient WordPress, pre-riscaldati da Action Scheduler (job `dflc_warm_cache`) o WP-Cron come fallback.

### Stale-while-revalidate

1. Cache miss rilevato.
2. Lettura dell'ultimo valore noto (opzione persistente `dflc_lastgood`), restituito immediatamente.
3. Job di refresh asincrono pianificato.
4. Lock breve (2 minuti) evita refresh concorrenti.

### Sicurezza dell'endpoint REST

- Lettura pubblica solamente.
- Whitelist delle chiavi.
- Header `Cache-Control: public, max-age=...`.

**Attenzione.** Se il tuo CDN ignora l'header `Cache-Control` della rotta REST, i numeri saranno congelati a livello CDN. Escludi `/wp-json/dflivecounters/v1/counters` dalla cache CDN.

## API sviluppatore

Cinque filtri PHP estendono il plugin senza toccare il core.

### dflc_counter_definitions

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

### dflc_compute

```
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

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

### dflc_payload

```
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

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

### Ricetta: contatore Mailchimp

```
add_filter( 'dflc_counter_definitions', static function ( array $items ) {
    $items[] = array(
        'key' => 'mailchimp_subs', 'label' => 'Iscritti 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 );
```

## Risoluzione problemi

### I numeri non si animano

- Verificare che `dflc-front.js` si carichi.
- Verificare che `/wp-json/dflivecounters/v1/counters` risponda 200 con JSON valido.
- Testare con un altro tema.

### I numeri mostrano sempre «—»

- La chiamata REST è fallita. Controllare la console JS.
- La rotta può essere bloccata da un plugin di sicurezza.

### I numeri non si aggiornano

- Verificare che **«Pre-riscalda la cache automaticamente»** sia attivato.
- Per siti a basso traffico, considerare un cron di sistema reale.

### La chiamata API Meta restituisce 0

- Verificare il token nel [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/).
- Verificare che l'account Instagram sia Business o Creator.

### Avviso WP 6.7 «_load_textdomain_just_in_time»

Corretto dalla versione 1.1.1.