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

- Strona: <https://www.datafirefly.com/pl/documentation/dflivecounters-wp/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [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), [nl](https://www.datafirefly.com/nl/documentation/dflivecounters-wp/index.md), [pt](https://www.datafirefly.com/pt/documentation/dflivecounters-wp/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

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

**Wymagana cierpliwość.** W nowej witrynie plakietka trendu pojawi się dopiero po upływie okna (domyślnie 7 dni).

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

**Uwaga.** Jeśli Twój CDN ignoruje `Cache-Control` trasy REST i cache'uje ją agresywnie, liczby zamarzną na poziomie CDN. Wyklucz `/wp-json/dflivecounters/v1/counters` z cache CDN, jeśli zaobserwujesz takie zachowanie.

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