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

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

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