# DataFirefly Live Counters

> DataFirefly Live Counters zeigt animierte Zähler (Kunden, Bestellungen, Social-Follower, eigene KPIs) auf Ihrer WordPress/WooCommerce-Website an, die auch dann genau bleiben, wenn die gesamte Website aus einem Full-Page-Cache wie LiteSpeed Cache…

- Seite: <https://www.datafirefly.com/de/documentation/dflivecounters-wp/>
- Sprache: de
- Aktualisiert am: 2026-06-28
- Weitere Sprachen: [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), [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/de/documentation/llms.txt>

DataFirefly Live Counters zeigt animierte Zähler (Kunden, Bestellungen, Social-Follower, eigene KPIs) auf Ihrer WordPress/WooCommerce-Website an, die auch dann genau bleiben, wenn die gesamte Website aus einem Full-Page-Cache wie LiteSpeed Cache oder WP Rocket serviert wird.

## Installation und Schnellstart

### Voraussetzungen

- WordPress 6.2 oder höher (getestet auf 6.7).
- PHP 8.1 oder höher.
- WooCommerce 7.0+ empfohlen für Shop-Zähler. Ohne WooCommerce bleiben Social- und Custom-KPI-Zähler voll funktionsfähig.
- Polylang oder WPML optional für mehrsprachige Beschriftungen.

### Installation

1. Laden Sie `dflivecounters.zip` aus Ihrem DataFirefly-Konto herunter.
2. In WordPress: **Plugins → Installieren → Plugin hochladen**.
3. Wählen Sie die ZIP-Datei und klicken Sie auf **Jetzt installieren**.
4. Aktivieren Sie das Plugin. Ein neuer Eintrag **Live Counters** erscheint im WooCommerce-Menü.

### Erste Anzeige in 30 Sekunden

```
[dflivecounters]
```

Beim ersten Laden erscheint ein Raster mit vier Zählern und einer Count-up-Animation. Die Zahlen werden aus Ihrem WooCommerce-Katalog berechnet und gecacht.

## Allgemeine Einstellungen

Gehen Sie zu **WooCommerce → Live Counters**. Die Seite ist in vier Karten gegliedert, gefolgt von einer Live-Vorschau und einem Cache-Leeren-Button.

### Karte „Anzeige & Cache"

- **Stil**: `Karten`, `Minimal`, `Verlauf`.
- **Spalten**: 1 bis 6. Responsive: 2 Spalten auf Mobilgeräten, 1 auf sehr kleinen Bildschirmen.
- **Akzentfarbe**: für Symbole, Zahlen (Karten) und Hintergrund (Verlauf). Standard `#0f172a`.
- **Animationsdauer (ms)**: 200 bis 8.000. 0 deaktiviert die Animation.
- **Zähler-Cache (Min.)**: 60 Standard.
- **Social-Cache (Min.)**: 360 Standard (Social-APIs sind rate-limited).
- **Große Zahlen abkürzen**: zeigt `12,4k`.
- **„+" zu kumulativen Zählern hinzufügen**.
- **Cache automatisch vorwärmen (Cron)**: Action Scheduler bevorzugt, WP-Cron als Fallback.

### Gezählte Bestellstatus

- **Gezählte Status**: standardmäßig `In Bearbeitung` und `Fertiggestellt`.
- **„Versendet"-Status**: nur für _Versendete Produkte_. Standardmäßig `Fertiggestellt`.

### Gründungsdatum

Der Zähler _Jahre Erfahrung_ wird aus dem Datum unter **„Gründungsdatum"** berechnet.

### Cache leeren und neu aufbauen

Der Button **„↻ Cache jetzt leeren und neu aufbauen"** entfernt alle Transients und löst eine sofortige Vorwärmung aus. Jede Einstellungsänderung leert automatisch den Cache.

## WooCommerce-Zähler

### Verfügbare Zähler

- **Zufriedene Kunden** (`customers`).
- **Versendete Produkte** (`shipped`).
- **Verarbeitete Bestellungen** (`orders`).
- **Verkaufte Artikel** (`items_sold`).
- **Produkte im Katalog** (`products`).
- **Kundenbewertungen** (`reviews`).
- **Belieferte Länder** (`countries`).
- **Jahre Erfahrung** (`years`).

### Zähler aktivieren und anpassen

- Benutzerdefinierte Bezeichnung.
- Zeitraum (siehe entsprechenden Abschnitt).
- Offset zur Integration älterer Historie.
- Ziel, das die Fortschrittsanzeige aktiviert.

### HPOS-Kompatibilität

Das Plugin erkennt automatisch HPOS (High-Performance Order Storage) oder Legacy-Speicher (CPT). Queries sind in zwei optimierten Versionen geschrieben. Die Kompatibilität wird über den `before_woocommerce_init`-Hook deklariert.

## Soziale und benutzerdefinierte KPI-Zähler

### Unterstützte soziale Netzwerke

- **Facebook** und **Instagram** — automatischer Abruf über die Meta Graph API v19 (Instagram nur Business- oder Creator-Konten).
- **TikTok**, **X**, **LinkedIn**, **YouTube** — manuelle Eingabe.

### Facebook oder Instagram über die Meta Graph API konfigurieren

1. Erstellen Sie eine App auf [developers.facebook.com](https://developers.facebook.com).
2. Generieren Sie ein Long-Lived Access Token mit `pages_read_engagement` (FB) oder `instagram_basic` + `pages_show_list` (IG).
3. Beschaffen Sie die Page ID oder Business Account ID.
4. Markieren Sie **„Über API abrufen"**, fügen Sie ID und Token ein.

Wenn der API-Aufruf fehlschlägt, behält das Plugin den letzten bekannten Wert. Das „manuelle" Feld dient als ultimativer Fallback.

### Benutzerdefinierte KPI-Zähler

In der Karte **„Benutzerdefinierte Zähler (KPI)"** klicken Sie auf **„+ Zähler hinzufügen"**, dann: Symbol, Bezeichnung, Wert, optionales Präfix, optionales Suffix, optionales Ziel.

## Zeiträume, Ziele und Trend

### Zeiträume pro Zähler

Unterstützte Zähler: `customers`, `shipped`, `orders`, `items_sold`, `reviews`, `countries`.

- **Gesamt**: Standardverhalten.
- **Dieses Jahr**: seit 1. Januar.
- **Diesen Monat**: seit dem 1. des Monats.
- **Letzte 30 Tage**: gleitendes Fenster.

### Ziele und Fortschrittsbalken

Ein Ziel in der Spalte **„Ziel (0 = keines)"** aktiviert automatisch einen animierten Balken bis `min(100 %, Wert / Ziel)`.

### Trend-Indikator ▲/▼

Ein farbiger Chip erscheint neben der Zahl: ▲ grün bei Anstieg, ▼ rot bei Rückgang, keine Markierung bei Null-Variation oder unzureichender Historie. 7-tägiges gleitendes Fenster standardmäßig, konfigurierbar über den Filter `dflc_trend_window`. Baselines in einer einzigen WordPress-Option `dflc_trend`.

**Erwartete Geduld.** Auf einer neuen Website erscheint der Trend-Chip erst nach Ablauf des Fensters (standardmäßig 7 Tage).

## Anzeige: Block, Widget, Shortcode

### Gutenberg-Block

Im Block-Editor suchen Sie nach **„DataFirefly Live Counters"** (Kategorie „Widgets"). Das Inspektor-Panel erlaubt die Konfiguration von Spalten, Stil und Zählerliste. Die Vorschau ist identisch zum Front-Rendering.

### Klassisches Widget

Unter **Design → Widgets** fügen Sie **„DataFirefly Live Counters"** hinzu. Felder: Titel, Spalten (0 bis 6), Stil, Schlüssel (kommagetrennt).

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

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

### Verfügbare Schlüssel

| Zähler | Schlüssel |
| --- | --- |
| Kunden | `customers` |
| Versendete Produkte | `shipped` |
| Verarbeitete Bestellungen | `orders` |
| Verkaufte Artikel | `items_sold` |
| Produkte im Katalog | `products` |
| Kundenbewertungen | `reviews` |
| Belieferte Länder | `countries` |
| Jahre Erfahrung | `years` |
| Soziale Netzwerke | `social_facebook`, `social_instagram`, `social_tiktok`, `social_twitter`, `social_linkedin`, `social_youtube` |
| Benutzerdefinierte Zähler | `custom_0`, `custom_1`, usw. |

### Theme-Integration (PHP)

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

## Cache-Architektur

### Das Problem

Wenn ein Seiten-Cache (LiteSpeed, WP Rocket, NGINX Micro-Cache, Varnish, Cloudflare APO) vorgeneriertes HTML serviert, wird jede in PHP gerenderte Zahl eingefroren. Caching auf diesen Seiten zu deaktivieren beeinträchtigt die Performance erheblich.

### Das Prinzip: Struktur und Werte trennen

- **Cachebare Struktur**: Raster, Symbole, Beschriftungen und leere Slots, server-seitig gerendert.
- **Nicht-cachebare Werte**: über `fetch()` an eine REST-Route mit kurzem `Cache-Control`-Header abgerufen.

### Transient-Cache + Warm-up

Die REST-Route führt während des Besuchs keine schwere SQL-Query aus. Sie liest WordPress-Transients, vorgewärmt durch Action Scheduler (`dflc_warm_cache`-Job) oder WP-Cron als Fallback.

### Stale-while-revalidate

1. Cache-Miss erkannt.
2. Lesen des letzten bekannten Werts (persistente Option `dflc_lastgood`), sofort zurückgegeben.
3. Asynchroner Refresh-Job geplant.
4. Kurze Sperre (2 Minuten) verhindert gleichzeitige Refreshes.

### REST-Endpoint-Sicherheit

- Nur öffentliches Lesen.
- Schlüssel-Whitelist.
- Header `Cache-Control: public, max-age=...`.

**Vorsicht.** Wenn Ihr CDN den `Cache-Control`-Header der REST-Route ignoriert, werden Zahlen auf CDN-Ebene eingefroren. Schließen Sie `/wp-json/dflivecounters/v1/counters` aus Ihrem CDN-Cache aus.

## Entwickler-API

Fünf PHP-Filter erweitern das Plugin ohne Kern-Eingriff.

### dflc_counter_definitions

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

### Rezept: Mailchimp-Zähler

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

## Fehlerbehebung

### Zahlen animieren nicht

- Überprüfen Sie, dass `dflc-front.js` geladen wird.
- Überprüfen Sie, dass `/wp-json/dflivecounters/v1/counters` mit 200 und gültigem JSON antwortet.
- Mit einem anderen Theme testen.

### Zahlen zeigen immer „—"

- Der REST-Aufruf ist fehlgeschlagen. JS-Konsole prüfen.
- Die Route kann von einem Sicherheits-Plugin blockiert sein.

### Zahlen aktualisieren sich nicht

- Überprüfen Sie, dass **„Cache automatisch vorwärmen"** aktiviert ist.
- Auf Websites mit geringem Traffic einen echten System-Cron erwägen.

### Meta-API-Aufruf gibt 0 zurück

- Token-Gültigkeit im [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/) prüfen.
- Überprüfen, dass das Instagram-Konto Business oder Creator ist.

### WP 6.7 „_load_textdomain_just_in_time"-Hinweis

Behoben seit Version 1.1.1.