DataFirefly Live Counters

DataFirefly Live Counters wyświetla w Twojej witrynie WordPress/WooCommerce animowane liczniki (klienci, zamówienia, obserwujący w mediach społecznościowych, własne KPI), które pozostają aktualne nawet wtedy, gdy cała witryna serwowana jest z full-page cache w rodzaju LiteSpeed Cache czy WP Rocket.

Instalacja i start

Wymagania

• WordPress 6.2 lub nowszy (testowane na 6.7).
• PHP 8.1 lub nowszy.
• WooCommerce 7.0+ zalecany dla liczników sklepowych. Bez WooCommerce liczniki społecznościowe i własne KPI pozostają w pełni funkcjonalne.
• Polylang albo WPML opcjonalnie dla wielojęzycznych etykiet.

Instalacja

1. Pobierz plik dflivecounters.zip ze swojego konta DataFirefly.
2. W WordPressie przejdź do Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer.
3. Wybierz ZIP i kliknij Zainstaluj teraz.
4. Włącz wtyczkę. W menu WooCommerce (albo Ustawienia, jeśli WooCommerce nie jest zainstalowane) pojawia się nowa pozycja Live Counters.

Pierwsze wyświetlenie w 30 sekund

Wstaw ten shortcode na dowolną stronę albo do wpisu:

[dflivecounters]

Przy pierwszym załadowaniu pojawia się siatka czterech liczników z animacją count-up. Liczby są obliczane z Twojego katalogu WooCommerce i cache’owane.

Ustawienia ogólne

Przejdź do WooCommerce → Live Counters. Strona składa się z czterech kart, podglądu na żywo i przycisku czyszczenia cache.

Karta „Wyświetlanie i cache”

• Styl: Karty, Minimalistyczny, Gradient.
• Kolumny: od 1 do 6. Responsywnie: 2 kolumny na telefonie, 1 na bardzo małym ekranie.
• Kolor akcentu: używany dla ikon, liczb (karty) i tła (gradient). Domyślnie #0f172a.
• Czas animacji (ms): 200 do 8 000. 0 wyłącza animację.
• Cache liczników (min): domyślnie 60.
• Cache mediów społecznościowych (min): domyślnie 360 (API społecznościowe mają limity zapytań).
• Skracaj duże liczby: wyświetla 12,4 k zamiast 12 400.
• Dodaj „+” do liczników skumulowanych.
• Podgrzewaj cache automatycznie (cron): Action Scheduler w pierwszej kolejności, WP-Cron awaryjnie.

Zliczane statusy zamówień

• Statusy zliczane (klienci, zamówienia, artykuły, kraje): domyślnie Processing i Completed.
• Statusy „wysłane”: używane tylko dla Produkty wysłane. Domyślnie Completed.

Data założenia

Licznik Lata doświadczenia oblicza wartość na podstawie daty wpisanej w polu „Data założenia”.

Czyszczenie i regeneracja cache

Przycisk „↻ Wyczyść i zregeneruj cache teraz” usuwa wszystkie transienty wtyczki i uruchamia natychmiastowy warm-up. Każda zmiana ustawień automatycznie czyści cache i przeplanowuje warm-up.

Liczniki WooCommerce

Lista dostępnych liczników

• Zadowoleni klienci (customers): odrębne adresy e-mail, które złożyły zamówienie w zliczanym statusie.
• Produkty wysłane (shipped): suma ilości artykułów w zamówieniach „wysłanych”.
• Obsłużone zamówienia (orders).
• Sprzedane artykuły (items_sold): suma ilości ze wszystkich pozycji.
• Produkty w katalogu (products).
• Opinie klientów (reviews): opinie zatwierdzone.
• Obsłużone kraje (countries).
• Lata doświadczenia (years): od daty założenia.

Włączanie i personalizacja licznika

W tabeli „Liczniki sklepowe” zaznacz Aktywny i opcjonalnie:

• Wpisz własną etykietę.
• Wybierz okres (patrz dedykowana sekcja).
• Dodaj offset, aby uwzględnić wcześniejszą historię (na przykład 1 200 klientów odziedziczonych po poprzednim sklepie).
• Ustal cel, który włączy pasek postępu.

Zgodność z HPOS

Wtyczka automatycznie wykrywa HPOS (High-Performance Order Storage) albo magazyn legacy (CPT). Zapytania są napisane w dwóch zoptymalizowanych wariantach. Zgodność z HPOS i Cart/Checkout Blocks jest deklarowana przez hook before_woocommerce_init.

Liczniki społecznościowe i własne KPI

Obsługiwane sieci społecznościowe

• Facebook i Instagram: pobieranie automatyczne przez API Meta Graph v19 (Instagram wyłącznie dla kont Business lub Creator).
• TikTok, X (Twitter), LinkedIn, YouTube: wpisywanie ręczne.

TikTok, X i LinkedIn nie udostępniają wiarygodnego licznika obserwujących przez publiczne API, stąd wpisywanie ręczne.

Konfiguracja Facebooka lub Instagrama przez API Meta Graph

1. Utwórz aplikację na developers.facebook.com.
2. Wygeneruj długoterminowy token dostępu z uprawnieniem pages_read_engagement (Facebook) albo instagram_basic + pages_show_list (Instagram).
3. Pobierz identyfikator strony Facebooka albo konta IG Business.
4. W karcie „Media społecznościowe” zaznacz „Pobieraj przez API”, wklej identyfikator w pole ID obiektu, a token w pole Token dostępu.

Jeśli wywołanie API zawiedzie (wygasły token, limit zapytań), wtyczka zachowuje ostatnią znaną wartość. Pole „ręczne” służy jako ostateczne zabezpieczenie.

Własne liczniki KPI

W karcie „Liczniki własne (KPI)” kliknij „+ Dodaj licznik” i uzupełnij: ikonę (users, award, heart, leaf, download…), etykietę, wartość, opcjonalny prefiks („$”, „+”), opcjonalny sufiks („%, h, M”), opcjonalny cel.

Okresy, cele i trend

Okresy per licznik

Liczniki agregujące w czasie (customers, shipped, orders, items_sold, reviews, countries) można zawęzić:

• Łącznie: zachowanie domyślne.
• Ten rok: od 1 stycznia.
• Ten miesiąc: od 1. dnia miesiąca.
• Ostatnie 30 dni: okno ruchome.

Komunikat „124 zamówienia w tym miesiącu” często angażuje bardziej niż „9 421 zamówień”.

Cele i pasek postępu

Wpisanie celu w kolumnie „Cel (0 = brak)” automatycznie włącza pasek pod licznikiem, animowany razem z count-up, do min(100 %, wartość / cel). Dostępne też dla liczników społecznościowych i własnych.

Wskaźnik trendu ▲/▼

Obok liczby pojawia się kolorowa plakietka:

• ▲ zielona, jeśli wartość wzrosła od poprzedniego snapshotu.
• ▼ czerwona, jeśli spadła.
• Brak plakietki przy zerowej zmianie albo niewystarczającej historii.

Procent liczony jest w oknie ruchomym, domyślnie 7-dniowym, modyfikowalnym filtrem dflc_trend_window. Wartości bazowe przechowywane są w pojedynczej opcji WordPressa (dflc_trend).

Wyświetlanie: blok, widżet, shortcode

Blok Gutenberga

W edytorze blokowym wyszukaj „DataFirefly Live Counters” (kategoria „Widżety”). Panel inspektora pozwala skonfigurować kolumny, styl i listę wyświetlanych liczników. Podgląd korzysta z ServerSideRender i jest identyczny z renderowaniem na froncie.

Klasyczny widżet

W Wygląd → Widżety dodaj „DataFirefly Live Counters”. Pola: tytuł, kolumny (0 do 6), styl, klucze (lista rozdzielona przecinkami albo pusta = wszystkie włączone liczniki).

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

Obsługiwane atrybuty: keys (string, lista kluczy), columns (int 1-6), style (cards, minimal, gradient).

Lista dostępnych kluczy

Licznik	Klucz
Klienci	customers
Produkty wysłane	shipped
Obsłużone zamówienia	orders
Sprzedane artykuły	items_sold
Produkty w katalogu	products
Opinie klientów	reviews
Obsłużone kraje	countries
Lata doświadczenia	years
Media społecznościowe	social_facebook, social_instagram, social_tiktok, social_twitter, social_linkedin, social_youtube
Liczniki własne	custom_0, custom_1 i kolejne

Wstawienie w motywie (PHP)

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

Architektura cache

Problem

Kiedy cache stron (LiteSpeed, WP Rocket, NGINX micro-cache, Varnish, Cloudflare APO) serwuje wygenerowany wcześniej HTML, każda liczba wyrenderowana w PHP jest zamrożona. Klasyczna odpowiedź, czyli wyłączenie cache na tych stronach, poważnie degraduje wydajność.

Zasada: rozdzielenie struktury i wartości

• Struktura cache’owalna: siatka, ikony, etykiety i puste miejsca, renderowane po stronie serwera, idealnie cache’owalne.
• Wartości niecache’owalne: pobierane przez fetch() z dedykowanej trasy REST, z krótkim nagłówkiem Cache-Control.

Odwiedzający otrzymuje natychmiast HTML z cache, a następnie liczby wypełniają się w JavaScripcie z animacją count-up.

Cache transientów + warm-up

Trasa REST nigdy nie wykonuje ciężkiego zapytania SQL podczas wizyty. Czyta transienty WordPressa, podgrzewane przez Action Scheduler (zadanie dflc_warm_cache) albo awaryjnie przez WP-Cron.

Stale-while-revalidate

Jeśli transient wygaśnie dokładnie między dwoma warm-upami:

1. Ostatnia znana wartość jest odczytywana z trwałej opcji dflc_lastgood (która przeżywa wygaśnięcie transientu) i zwracana natychmiast.
2. Planowane jest asynchroniczne zadanie odświeżenia.
3. Krótka blokada (2 minuty) zapobiega piętrzeniu się równoczesnych odświeżeń.

Prawdziwy cold start zdarza się tylko przy pierwszym wyświetleniu po instalacji.

Bezpieczeństwo endpointu REST

• Wyłącznie publiczny odczyt.
• Biała lista kluczy: akceptowane są tylko klucze odpowiadające rzeczywiście skonfigurowanym licznikom.
• Nagłówek Cache-Control: public, max-age=... dopasowany do TTL liczników.

API dla deweloperów

Pięć filtrów PHP pozwala rozszerzać wtyczkę bez dotykania rdzenia.

dflc_counter_definitions

Dodawanie, zmiana kolejności albo ukrywanie liczników.

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

dflc_compute

Zwiera obliczenie. Zwrócenie liczby całkowitej przejmuje kontrolę, null pozostawia obsługę rdzeniowi.

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

Filtruje wartość końcową tuż przed wysłaniem na front.

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

dflc_payload

Filtruje cały ładunek REST.

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

Zmienia ruchome okno trendu. Wartość w sekundach, domyślnie 7 * DAY_IN_SECONDS.

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

Przepis: licznik Mailchimp

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

Rozwiązywanie problemów

Liczby się nie animują

• Sprawdź, czy skrypt dflc-front.js się ładuje (zakładka sieć).
• Sprawdź, czy trasa REST /wp-json/dflivecounters/v1/counters odpowiada kodem 200 z poprawnym JSON-em.
• Przetestuj z innym motywem.

Liczby ciągle pokazują „—"

• Wywołanie REST nie powiodło się. Sprawdź konsolę JS.
• Trasa REST może być blokowana przez wtyczkę bezpieczeństwa.

Liczby się nie aktualizują

• Sprawdź, czy włączono „Podgrzewaj cache automatycznie".
• W witrynach o niskim ruchu rozważ prawdziwy cron systemowy zamiast WP-Cron.
• Wymuś odświeżenie przyciskiem „↻ Wyczyść i zregeneruj cache teraz".

Wywołanie API Meta zwraca 0

• Zweryfikuj ważność tokena w Access Token Debugger.
• Sprawdź, czy konto Instagram jest rzeczywiście typu Business albo Creator.

Notice WP 6.7 „_load_textdomain_just_in_time"

Naprawione od wersji 1.1.1.