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

- Pagina: <https://www.datafirefly.com/nl/documentation/dflivecounters-wp/>
- Taal: nl
- Bijgewerkt op: 2026-08-19
- Andere talen: [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), [it](https://www.datafirefly.com/it/documentation/dflivecounters-wp/index.md), [pl](https://www.datafirefly.com/pl/documentation/dflivecounters-wp/index.md), [pt](https://www.datafirefly.com/pt/documentation/dflivecounters-wp/index.md)
- Index: <https://www.datafirefly.com/nl/documentation/llms.txt>

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](https://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`).

**Even geduld.** Op een nieuwe site verschijnt het trendbolletje pas nadat het venster is verstreken (standaard 7 dagen).

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

**Let op.** Negeert uw CDN de `Cache-Control` van de REST-route en cachet het die agressief, dan blijven de cijfers op CDN-niveau bevroren. Sluit in dat geval `/wp-json/dflivecounters/v1/counters` uit van uw CDN-cache.

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