DataFirefly Live Counters

DataFirefly Live Counters toont op uw WordPress- of WooCommerce-site geanimeerde tellers (klanten, bestellingen, sociale volgers, eigen KPI’s) die kloppen, ook wanneer de hele site vanuit een full page cache als LiteSpeed Cache of WP Rocket wordt geserveerd.

Installatie en start

Vereisten

• WordPress 6.2 of hoger (getest op 6.7).
• PHP 8.1 of hoger.
• WooCommerce 7.0+ aanbevolen voor de winkeltellers. Zonder WooCommerce blijven de sociale tellers en de eigen KPI’s volledig werken.
• Polylang of WPML optioneel, voor meertalige labels.

Installatie

1. Download het bestand dflivecounters.zip vanuit uw DataFirefly-account.
2. Ga in WordPress naar Plugins → Nieuwe plugin → Plugin uploaden.
3. Kies de zip en klik op Nu installeren.
4. Activeer de plugin. Er verschijnt een nieuw item Live Counters in het WooCommerce-menu (of bij Instellingen als WooCommerce niet is geïnstalleerd).

Eerste weergave in 30 seconden

Plaats deze shortcode in een willekeurige pagina of bericht:

[dflivecounters]

Bij het eerste laden verschijnt een raster met vier tellers, met een count-up-animatie. De cijfers worden uit uw WooCommerce-catalogus berekend en gecachet.

Algemene instellingen

Ga naar WooCommerce → Live Counters. De pagina bestaat uit vier kaarten, gevolgd door een live voorbeeld en een knop om de cache te legen.

Kaart “Weergave en cache”

• Stijl: Kaarten, Minimaal, Verloop.
• Kolommen: van 1 tot 6. Responsief: 2 kolommen op mobiel, 1 op een heel klein scherm.
• Accentkleur: gebruikt voor pictogrammen, cijfers (kaarten) en achtergrond (verloop). Standaard #0f172a.
• Duur van de animatie (ms): 200 tot 8.000. Met 0 schakelt u de animatie uit.
• Cache van de tellers (min): standaard 60.
• Cache van de sociale netwerken (min): standaard 360 (de sociale API’s hebben ratelimieten).
• Grote getallen afkorten: toont 12,4 k in plaats van 12 400.
• Een plusteken bij cumulatieve tellers zetten.
• De cache automatisch voorverwarmen (cron): bij voorkeur via Action Scheduler, met WP-Cron als terugval.

Meegetelde bestelstatussen

• Meegetelde statussen (klanten, bestellingen, artikelen, landen): standaard Processing en Completed.
• Statussen “verzonden”: alleen gebruikt voor Verzonden producten. Standaard Completed.

Oprichtingsdatum

De teller Jaren ervaring berekent zijn waarde op basis van de datum die u invult bij “Oprichtingsdatum”.

De cache legen en opnieuw opbouwen

De knop “↻ Cache nu legen en opnieuw opbouwen” verwijdert alle transients van de plugin en start meteen een voorverwarming. Elke wijziging aan de instellingen leegt de cache automatisch en plant de voorverwarming opnieuw in.

WooCommerce-tellers

Lijst van beschikbare tellers

• Tevreden klanten (customers): unieke e-mailadressen die een bestelling met een meegetelde status hebben geplaatst.
• Verzonden producten (shipped): de som van de artikelaantallen in de bestellingen met de status “verzonden”.
• Verwerkte bestellingen (orders).
• Verkochte artikelen (items_sold): de som van de aantallen op alle regels.
• Producten in de catalogus (products).
• Klantreviews (reviews): goedgekeurde reviews.
• Beleverde landen (countries).
• Jaren ervaring (years): vanaf de oprichtingsdatum.

Een teller inschakelen en aanpassen

Vink in de tabel “Winkeltellers” de kolom Actief aan, en eventueel:

• vul een eigen label in;
• kies een periode (zie het bijbehorende onderdeel);
• voeg een offset toe om een eerdere historiek mee te nemen (bijvoorbeeld 1.200 klanten uit een vorige winkel);
• stel een doel in, waardoor de voortgangsbalk verschijnt.

HPOS-compatibiliteit

De plugin herkent automatisch HPOS (High-Performance Order Storage) of de klassieke opslag (CPT). De queries zijn in twee geoptimaliseerde versies geschreven. De compatibiliteit met HPOS en met de Cart- en Checkout-blokken wordt verklaard via de hook before_woocommerce_init.

Sociale tellers en eigen KPI’s

Ondersteunde sociale netwerken

• Facebook en Instagram: automatisch opgehaald via de Meta Graph API v19 (Instagram alleen bij een Business- of Creator-account).
• TikTok, X (Twitter), LinkedIn en YouTube: handmatige invoer.

TikTok, X en LinkedIn bieden geen betrouwbare publieke API voor het aantal volgers, vandaar de handmatige invoer.

Facebook of Instagram instellen via de Meta Graph API

1. Maak een applicatie aan op developers.facebook.com.
2. Genereer een langlopend toegangstoken met de rechten pages_read_engagement (Facebook) of instagram_basic plus pages_show_list (Instagram).
3. Haal het ID van de Facebook-pagina of van het IG Business-account op.
4. Vink op de kaart “Sociale netwerken” de optie “Ophalen via de API” aan, plak het ID bij Object-ID en het token bij Toegangstoken.

Mislukt de API-aanroep (verlopen token, ratelimiet), dan behoudt de plugin de laatst bekende waarde. Het handmatige veld dient als uiterste terugval.

Eigen KPI-tellers

Klik op de kaart “Eigen tellers (KPI)” op “+ Teller toevoegen” en vul in: pictogram (users, award, heart, leaf, download en meer), label, waarde, optioneel voorvoegsel (“$”, “+”), optioneel achtervoegsel (“%”, “u”, “M”) en een optioneel doel.

Periodes, doelen en trend

Periodes per teller

Tellers die in de tijd optellen (customers, shipped, orders, items_sold, reviews, countries) kunt u beperken:

• Totaal: het standaardgedrag.
• Dit jaar: vanaf 1 januari.
• Deze maand: vanaf de eerste van de maand.
• Laatste 30 dagen: een voortschrijdend venster.

Het effect van “124 bestellingen deze maand” is vaak pakkender dan “9.421 bestellingen”.

Doelen en voortgangsbalk

Vult u een doel in bij de kolom “Doel (0 is geen)”, dan verschijnt er automatisch een balk onder de teller, die tegelijk met de count-up wordt geanimeerd tot min(100 procent, waarde / doel). Ook beschikbaar bij de sociale en de eigen tellers.

Trendindicator ▲ en ▼

Naast het cijfer verschijnt een gekleurd bolletje:

• ▲ groen als de waarde is gestegen sinds de vorige momentopname;
• ▼ rood als ze is gedaald;
• geen bolletje als er geen verandering is of als de historiek te kort is.

Het percentage wordt standaard berekend over een voortschrijdend venster van 7 dagen, aan te passen via het filter dflc_trend_window. De basislijnen staan in één WordPress-optie (dflc_trend).

Weergave: blok, widget, shortcode

Gutenberg-blok

Zoek in de blokeditor naar “DataFirefly Live Counters” (categorie “Widgets”). In het inspectiepaneel stelt u de kolommen, de stijl en de lijst met te tonen tellers in. Het voorbeeld gebruikt ServerSideRender en is identiek aan de weergave aan de voorkant.

Klassieke widget

Voeg in Weergave → Widgets de widget “DataFirefly Live Counters” toe. Velden: titel, kolommen (0 tot 6), stijl en sleutels (een lijst gescheiden door komma’s, of leeg voor alle ingeschakelde tellers).

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

Ondersteunde attributen: keys (string, lijst met sleutels), columns (geheel getal 1 tot 6) en style (cards, minimal, gradient).

Lijst met beschikbare sleutels

Teller	Sleutel
Klanten	customers
Verzonden producten	shipped
Verwerkte bestellingen	orders
Verkochte artikelen	items_sold
Producten in de catalogus	products
Klantreviews	reviews
Beleverde landen	countries
Jaren ervaring	years
Sociale netwerken	social_facebook, social_instagram, social_tiktok, social_twitter, social_linkedin, social_youtube
Eigen tellers	custom_0, custom_1 en zo verder

Invoegen in een thema (PHP)

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

Architectuur van de cache

Het probleem

Wanneer een paginacache (LiteSpeed, WP Rocket, NGINX micro-cache, Varnish, Cloudflare APO) vooraf gegenereerde HTML serveert, ligt elk in PHP gerenderd cijfer vast. De klassieke oplossing, de cache op die pagina’s uitschakelen, tast de prestaties zwaar aan.

Het uitgangspunt: structuur en waarden scheiden

• Cachebare structuur: raster, pictogrammen, labels en lege plaatsen, aan de serverzijde gerenderd en perfect cachebaar.
• Niet-cachebare waarden: opgehaald met fetch() via een eigen REST-route, met een korte Cache-Control-header.

De bezoeker krijgt de gecachete HTML meteen te zien, waarna de cijfers zich in JavaScript vullen met een count-up-animatie.

Transientcache en voorverwarming

De REST-route voert tijdens het bezoek nooit een zware SQL-query uit. Ze leest WordPress-transients, die vooraf worden opgewarmd door Action Scheduler (job dflc_warm_cache) of, als terugval, door WP-Cron.

Stale while revalidate

Verloopt een transient precies tussen twee voorverwarmingen in:

1. dan wordt de laatst bekende waarde gelezen uit de blijvende optie dflc_lastgood (die het verlopen van de transient overleeft) en meteen teruggegeven;
2. wordt er een asynchrone verversingsjob ingepland;
3. en voorkomt een korte vergrendeling (2 minuten) dat er meerdere verversingen tegelijk gaan lopen.

Een echte koude start doet zich alleen voor bij de allereerste weergave na de installatie.

Beveiliging van het REST-endpoint

• Alleen publieke leestoegang.
• Een whitelist van sleutels: alleen sleutels die bij daadwerkelijk ingestelde tellers horen, worden aanvaard.
• Een header Cache-Control: public, max-age=... die op de TTL van de tellers is afgestemd.

API voor ontwikkelaars

Vijf PHP-filters laten u de plugin uitbreiden zonder de kern aan te raken.

dflc_counter_definitions

Tellers toevoegen, herschikken of verbergen.

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

dflc_compute

Onderbreekt de berekening. Een geheel getal teruggeven neemt het over, null laat de kern het afhandelen.

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

Filtert de uiteindelijke waarde net vóór ze naar de voorkant gaat.

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

dflc_payload

Filtert de volledige REST-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

Past het voortschrijdende trendvenster aan. De waarde is in seconden, standaard 7 * DAY_IN_SECONDS.

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

Voorbeeld: een Mailchimp-teller

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

Probleemoplossing

De cijfers animeren niet

• Controleer of het script dflc-front.js wordt geladen (tabblad Netwerk).
• Controleer of de REST-route /wp-json/dflivecounters/v1/counters een 200 met geldige JSON teruggeeft.
• Test met een ander thema.

De cijfers tonen altijd "—"

• De REST-aanroep is mislukt. Controleer de JavaScript-console.
• De REST-route kan door een beveiligingsplugin worden geblokkeerd.

De cijfers worden niet bijgewerkt

• Controleer of "De cache automatisch voorverwarmen" is ingeschakeld.
• Overweeg op sites met weinig verkeer een echte systeemcron in plaats van WP-Cron.
• Forceer een verversing met de knop "↻ Cache nu legen en opnieuw opbouwen".

De Meta API-aanroep geeft 0 terug

• Controleer de geldigheid van het token via de Access Token Debugger.
• Controleer of het Instagram-account wel een Business- of Creator-account is.

Melding in WP 6.7 over "_load_textdomain_just_in_time"

Opgelost sinds versie 1.1.1.