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

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

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.
• Verificare che l'account Instagram sia Business o Creator.

Avviso WP 6.7 «_load_textdomain_just_in_time»

Corretto dalla versione 1.1.1.