# DataFirefly Native Live Shopping: dokumentacja
> Przegląd DataFirefly Native Live Shopping zamienia Twój sklep WooCommerce w samodzielną platformę live shoppingu, bez zależności od usług zewnętrznych w rodzaju Bambuser czy CommentSold. Transmisja korzysta z WebRTC peer-to-peer mesh…
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfnativeliveshopping/index.md), [en](https://www.datafirefly.com/en/documentation/dfnativeliveshopping/index.md), [es](https://www.datafirefly.com/es/documentation/dfnativeliveshopping/index.md), [de](https://www.datafirefly.com/de/documentation/dfnativeliveshopping/index.md), [it](https://www.datafirefly.com/it/documentation/dfnativeliveshopping/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfnativeliveshopping/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfnativeliveshopping/index.md)
- Indeks:
## Przegląd
DataFirefly Native Live Shopping zamienia Twój sklep WooCommerce w samodzielną platformę live shoppingu, bez zależności od usług zewnętrznych w rodzaju Bambuser czy CommentSold. Transmisja korzysta z **WebRTC peer-to-peer mesh** z przeglądarki prowadzącego do każdego widza, sygnalizacja przechodzi przez REST API WordPressa, a nagrywanie powtórki realizowane jest po stronie klienta przez API MediaRecorder, po czym trafia do załączników WordPressa.
Wtyczka dostarcza:
- Typ treści `dfnls_live_show` do tworzenia i planowania transmisji
- Konsolę prowadzącego zintegrowaną z administracją WordPressa (podgląd kamery, sterowanie, produkty, czat)
- Gotowe doświadczenie widza z klikalnymi produktami na nakładce i czatem
- Most do koszyka WooCommerce (oficjalne dodanie do koszyka bez opuszczania transmisji)
- Automatyczną powtórkę zsynchronizowaną ze zdarzeniami transmisji (wyróżnienia, kupony, komunikaty)
- Dedykowany blok Gutenberga i shortcode `[dfnls_live]`
**Architektura**: topologia WebRTC mesh sprawdza się do około 25 jednoczesnych widzów na prowadzącego. Powyżej tej liczby przewidź zewnętrzny serwer TURN albo rozważ SFU. Pasmo wysyłania prowadzącego powinno wynosić około 500 kbps na podłączonego widza.
## Wymagania
- **WordPress** 6.3 lub nowszy
- **WooCommerce** 8.0 lub nowszy (zgodne z HPOS)
- **PHP** 8.1 lub nowszy (testowane do 8.3)
- **HTTPS obowiązkowo**: `getUserMedia()` i `getDisplayMedia()` nie działają po niezabezpieczonym HTTP
- Wspierane przeglądarki widza: Chrome 80+, Firefox 75+, Edge 80+, Safari 14+, Opera 67+
- Aktualna przeglądarka po stronie prowadzącego, z dostępem do kamery i mikrofonu
**Ważne**: bez prawidłowego HTTPS (wystarczy Let's Encrypt) konsola prowadzącego nie uzyska dostępu do kamery ani mikrofonu. Testuj na `localhost` albo na domenie z certyfikatem TLS.
## Instalacja
1. Pobierz archiwum `df-native-live-shopping.zip` ze swojego konta DataFirefly.
2. W WordPressie przejdź do _Wtyczki → Dodaj nową_ → _Wyślij wtyczkę na serwer_.
3. Wybierz plik ZIP i kliknij _Zainstaluj teraz_.
4. Po instalacji kliknij _Włącz wtyczkę_.
5. W pasku bocznym administracji pojawia się nowe menu **Live Shopping**.
Przy aktywacji wtyczka:
- Tworzy 5 własnych tabel (`wp_dfnls_signaling`, `_sessions`, `_events`, `_replay_parts`, `_chat`)
- Dodaje uprawnienia `manage_dfnls_lives` i `host_dfnls_lives` do ról `administrator` i `shop_manager`
- Planuje dwa crony: dobowe czyszczenie starych powtórek i godzinne czyszczenie przeterminowanych komunikatów sygnalizacyjnych
- Zapisuje opcje domyślne (serwery STUN od Google, retencja 90 dni, maksymalnie 25 widzów i pozostałe)
## Pierwsza transmisja w 5 minut
Najkrótsza ścieżka do uruchomienia pierwszej transmisji:
1. Menu **Live Shopping → Nowa transmisja**
2. Wpisz tytuł (np. „Wiosenne wyprzedaże błyskawiczne")
3. W meta boksie _Produkty_ wyszukaj i wybierz produkty WooCommerce, które chcesz zaprezentować (przeciągnij i upuść, aby zmienić kolejność)
4. Opcjonalnie: w _Harmonogramie_ ustaw datę i godzinę startu (u widza wyświetli się odliczanie)
5. Opublikuj transmisję
6. Przejdź do **Live Shopping → Konsola prowadzącego** i wybierz swoją transmisję
7. Kliknij _Rozpocznij transmisję_ i zezwól na dostęp do kamery i mikrofonu
8. Udostępnij publiczny adres transmisji (`/live/twoj-slug/`) swojej publiczności
## Konsola prowadzącego
Konsola prowadzącego to panel, z którego prowadzisz transmisję. Dostępna jest przez _Live Shopping → Konsola prowadzącego_. Funkcje:
### Podgląd wideo i sterowanie
- **Kamera**: przełącznik włączenia i wyłączenia kamery
- **Mikrofon**: przełącznik włączenia i wyłączenia mikrofonu
- **Udostępnianie ekranu**: zastępuje obraz z kamery udostępnianiem ekranu (przydatne przy pokazach)
- **Rozpocznij / Zatrzymaj**: główne przyciski sterowania transmisją
### Wyróżnianie produktów
Lista produktów powiązanych z transmisją wyświetla się po prawej. Każdy produkt ma przycisk _Wyróżnij_. Kliknięcie:
- Natychmiast pokazuje produkt na nakładce u wszystkich widzów
- Zapisuje zdarzenie `product.spotlight` ze znacznikiem czasu na potrzeby synchronizacji powtórki
- Drugie kliknięcie tego samego przycisku zdejmuje nakładkę
### Emisja kuponów
Wpisz kod promocyjny (np. `LIVE20`) i ewentualnie opis, a następnie kliknij _Wyemituj_. Na ekranie widzów pojawia się animowany flash z przyciskiem „Kopiuj", pozwalającym pobrać kod jednym kliknięciem.
### Komunikaty prowadzącego
Dowolne pole tekstowe pozwala wysłać komunikat, który wyświetla się u widza jako tymczasowy baner (domyślnie 8 sekund).
### Czat na żywo
Czat prowadzącego i widzów jest wbudowany w konsolę. Komunikaty prowadzącego są wizualnie wyróżnione (plakietka i czerwone obramowanie) we wszystkich widokach.
### Dziennik aktywności
Dziennik na dole konsoli pokazuje w czasie rzeczywistym połączenia i rozłączenia, wyemitowane zdarzenia, wysyłki fragmentów powtórki oraz ewentualne błędy.
## Widok widza
Co widzi publiczność po wejściu na publiczny adres transmisji:
- **Przed transmisją**: jeśli transmisja jest zaplanowana, wyświetla się ekran oczekiwania z odliczaniem do wyznaczonej godziny. Automatyczne odpytywanie statusu co 5 sekund wykrywa start.
- **W trakcie transmisji**: obraz na żywo z pulsującą plakietką „NA ŻYWO" i licznikiem widzów. Panel boczny z dwiema zakładkami: _Produkty_ (klikalna lista produktów transmisji) i _Czat_.
- **Nakładka produktowa**: gdy prowadzący wyróżni produkt, na ekran wsuwa się karta (domyślnie w prawym dolnym rogu) ze zdjęciem, nazwą, ceną i przyciskiem _Dodaj do koszyka_.
- **Dodanie do koszyka**: kliknięcie przycisku dodaje produkt do oficjalnego koszyka WooCommerce. W prawym dolnym rogu pojawia się pływający przycisk z licznikiem pozycji w koszyku.
- **Kupon flash**: wyemitowany przez prowadzącego, wyświetla się u góry z animacją i przyciskiem kopiowania.
- **Po transmisji**: jeśli powtórka jest włączona, przycisk „Obejrzyj powtórkę" pozwala odtworzyć transmisję z pełną synchronizacją zdarzeń.
## Ustawienia globalne
Menu **Live Shopping → Ustawienia**. Główne sekcje:
### Serwery STUN
Domyślnie używane są publiczne serwery STUN od Google:
```
stun:stun.l.google.com:19302
stun:stun1.l.google.com:19302
```
Możesz dodać własne serwery STUN (po jednym w wierszu).
### Serwery TURN
Opcjonalne, ale zalecane dla widzów za symetrycznym NAT-em (niektórzy operatorzy 4G, firmowe VPN-y). Format:
```
turn:turn.przyklad.com:3478
turns:turn.przyklad.com:5349
```
Uzupełnij powiązane dane _TURN username_ i _TURN credential_.
### Nagrywanie i powtórka
- **Nagrywanie włączone**: tak / nie, globalnie
- **Długość fragmentów** (ms): domyślnie 5000. Krócej = większa odporność na awarię, ale więcej żądań; dłużej = mniej żądań, ale większa strata przy awarii
- **Retencja powtórek** (dni): domyślnie 90. Po tym czasie dobowy cron automatycznie usuwa pliki WebM i powiązane wpisy
### Pojemność i nakładka
- **Maksymalna liczba widzów na prowadzącego**: domyślnie 25. Dostosuj do swojego pasma wysyłania
- **Pozycja nakładki**: prawa, lewa albo dół
### Domyślne ustawienia transmisji
- Czat włączony domyślnie
- Powtórka włączona domyślnie
- Wymagane logowanie domyślnie
## Serwery STUN i TURN: kiedy konfigurować TURN
STUN to prosty serwer odkrywania publicznego adresu IP, darmowy i wystarczający w około 85 % przypadków. TURN natomiast faktycznie przekazuje ruch medialny: zużywa pasmo, ale pozwala połączyć dwóch klientów, którzy nie mogą się dosięgnąć bezpośrednio.
Skonfiguruj TURN, jeśli:
- Twoi widzowie regularnie skarżą się, że nie widzą obrazu (stan połączenia WebRTC zablokowany na „connecting")
- Twoja publiczność to w dużej mierze urządzenia mobilne w 4G/5G u operatorów z symetrycznym NAT-em
- Prowadzący albo widzowie są za restrykcyjnym firmowym VPN-em
**Zalecane rozwiązanie**: wdrożenie samodzielnie hostowanego [coturn](https://github.com/coturn/coturn) na małym VPS-ie (5 do 10 € miesięcznie) wystarcza na 30 do 40 jednoczesnych widzów. Płatna alternatywa: Xirsys, Twilio Network Traversal Service.
## Nagrywanie i powtórka
### Jak działa nagrywanie
Nagrywanie odbywa się w całości **po stronie przeglądarki prowadzącego**, przez API MediaRecorder:
1. Przy starcie transmisji instancjonowany jest MediaRecorder z automatycznym wykrywaniem najlepszego dostępnego kodeka (VP9 > VP8 > H.264, opus dla dźwięku, około 1,5 Mbps wideo plus 96 kbps audio)
2. Co 5 sekund (konfigurowalne) wyzwalany jest fragment WebM i wysyłany przez `POST /wp-json/df-nls/v1/shows/{id}/replay/chunk`
3. Fragment zapisywany jest jako załącznik WordPressa o nazwie `dfnls-show-{id}-part-{NNNNN}.webm`, z `post_parent` wskazującym na transmisję
4. Tabela `wp_dfnls_replay_parts` przechowuje kolejność i czas trwania każdego fragmentu
### Jak działa powtórka
Przy wczytaniu strony w trybie powtórki:
1. Widok wywołuje `GET /wp-json/df-nls/v1/shows/{id}/replay`, co zwraca uporządkowaną listę segmentów i oś czasu zdarzeń
2. Segmenty ładowane są sekwencyjnie przez zdarzenie `ended` elementu `` (natywny fallback)
3. Wariant z MediaSource pozwala na przezroczyste sklejanie, jeśli przeglądarka to wspiera
4. Pozycja odtwarzania (czas skumulowany) porównywana jest z `offset_ms` każdego zdarzenia: po przekroczeniu punktu widok lokalnie wyzwala to samo zachowanie co na żywo (pokazanie nakładki, flash kuponu, komunikat)
### Przechowywanie i miejsce na dysku
Rząd wielkości: godzinna transmisja przy 1,5 Mbps wideo plus 96 kbps audio daje około **720 MB** plików WebM. Przy 90 dniach retencji i 4 transmisjach miesięcznie licz na około 10 GB miejsca przeznaczonego na powtórki.
**MIME i wysyłanie**: wtyczka dodaje filtr `upload_mimes`, aby dopuścić `video/webm` i `video/mp4` z biblioteki mediów. Sprawdź, czy serwer nie ma zbyt restrykcyjnej reguły `LimitRequestBody` albo `upload_max_filesize` (celuj w minimum 20 MB na fragment).
## Integracja: shortcode, blok, bezpośredni adres
### Bezpośredni adres publiczny
Każda opublikowana transmisja ma własny, automatycznie generowany adres:
```
https://twoja-witryna.pl/live/twoj-slug/
```
To najprostsza droga: udostępnij ten link publiczności.
### Shortcode
Aby wstawić transmisję na istniejącą stronę albo do wpisu:
```
[dfnls_live id="42"]
[dfnls_live id="42" mode="live"]
[dfnls_live id="42" mode="replay"]
[dfnls_live id="42" mode="auto"]
```
Dostępne tryby:
- `auto` (domyślny): wykrywa status transmisji i wyświetla odpowiednio live, oczekiwanie albo powtórkę
- `live`: wymusza tryb transmisji (przydatne do testów)
- `replay`: wymusza tryb powtórki, nawet gdy transmisja wciąż trwa
### Blok Gutenberga
W edytorze bloków wyszukaj _„Live Shopping"_. Blok obsługuje wyrównania `wide` i `full`, udostępnia wybór transmisji oraz wybór trybu w panelu bocznym inspektora.
### Własny szablon PHP
Typ treści używa `templates/single-live-show.php`. Aby go nadpisać, skopiuj ten plik do swojego motywu pod `twoj-motyw/df-native-live-shopping/single-live-show.php`.
## Wielojęzyczność z Polylangiem
Wtyczka deklaruje typ treści `dfnls_live_show` jako tłumaczalny dla Polylanga. Przy aktywacji, jeśli Polylang jest już zainstalowany:
- Każda transmisja może mieć wersję FR, EN, ES, DE, IT i inne
- Krytyczne metadane (`_dfnls_product_ids`, `_dfnls_scheduled_at`, opcje transmisji) są automatycznie kopiowane między tłumaczeniami
- 5 wbudowanych języków (FR, EN, ES, DE, IT) ładuje się automatycznie zgodnie z locale WordPressa
**Wskazówka do Polylang Pro**: jeśli używasz Polylang Pro, a Twoje produkty WooCommerce są tłumaczone, każde tłumaczenie transmisji musi być powiązane z odpowiadającą wersją językową produktów. Wtyczka nie robi automatycznego mapowania identyfikatorów produktów między językami.
## HPOS i zgodność
Wtyczka oficjalnie deklaruje zgodność z wydajnym magazynem zamówień WooCommerce (HPOS) przez `FeaturesUtil`. Możesz włączyć HPOS w swojej instalacji bez ryzyka zakłócenia mostu do koszyka.
Zgodna także z:
- WordPress Multisite (instalacja per witryna, bez trybu sieciowego)
- Hostingiem współdzielonym: sygnalizacja korzysta z odpytywania REST, bez WebSocketów
- Wtyczkami cache (WP Rocket, WP Super Cache): endpointy REST wtyczki są automatycznie wykluczane
## Bezpieczeństwo i uprawnienia
Wtyczka dodaje dwa dedykowane uprawnienia:
- `manage_dfnls_lives`: tworzenie, edycja, usuwanie transmisji oraz dostęp do ustawień
- `host_dfnls_lives`: dostęp do konsoli prowadzącego, uruchamianie i zatrzymywanie transmisji
Oba uprawnienia przypisywane są domyślnie rolom `administrator` i `shop_manager`. Aby dać użytkownikowi wyłącznie prawo prowadzenia, bez możliwości tworzenia transmisji:
```
$user = get_user_by('login', 'host');
$user->add_cap('host_dfnls_lives');
```
### Nonce w REST
Wszystkie trasy akcji (POST) chronione są przez nonce `wp_rest`. Widok i prowadzący otrzymują swoje nonce przez `wp_localize_script` przy wczytaniu strony.
### Walidacja MIME przy wysyłaniu
Wysyłanie fragmentów powtórki jest ściśle walidowane przez `wp_check_filetype_and_ext`, aby przyjmować wyłącznie `video/webm` i `video/mp4`. Pliki są przemianowywane po stronie serwera (`dfnls-show-{id}-part-{NNNNN}.webm`).
## Cron i konserwacja
Przy aktywacji planowane są dwa crony WordPressa:
- `dfnls_cleanup_expired_replays`: **dobowy**. Usuwa powtórki transmisji zakończonych ponad N dni temu (konfigurowalna retencja). Używa `wp_delete_attachment(..., true)`, aby usunąć także plik fizyczny.
- `dfnls_cleanup_stale_signaling`: **godzinny**. Czyści komunikaty sygnalizacyjne starsze niż 24 godziny i sesje nieaktywne dłużej niż 90 sekund.
**Wyłączony WP-Cron**: jeśli wyłączyłeś WP-Cron na rzecz crona systemowego, zadbaj o wywoływanie `wp-cron.php` co najmniej raz na godzinę, aby czyszczenia się wykonywały.
## Dla deweloperów: REST API
Wszystkie trasy znajdują się w przestrzeni nazw `df-nls/v1`.
### Show
- `GET /shows/{id}`: pobiera transmisję (status, produkty, opcje)
- `POST /shows/{id}/join`: dołącza jako widz albo prowadzący (body: `peer_id`, `role`)
- `POST /shows/{id}/leave`: czyste opuszczenie
- `POST /shows/{id}/heartbeat`: utrzymuje sesję otwartą (automatycznie co 15 s po stronie widza)
- `POST /shows/{id}/start`: rozpoczyna transmisję (tylko prowadzący)
- `POST /shows/{id}/end`: kończy transmisję (tylko prowadzący)
- `GET /shows/{id}/viewers`: licznik aktywnych widzów
### Sygnalizacja WebRTC
- `POST /signal/send`: wysyła komunikat SDP/ICE do zdalnego peera
- `GET /signal/pull?peer={id}`: pobiera oczekujące komunikaty i wykonuje niejawny heartbeat
### Zdarzenia
- `POST /shows/{id}/event`: zapisuje zdarzenie (wyróżnienie, komunikat, kupon)
- `GET /shows/{id}/events?since={id}`: pobranie zdarzeń od podanego ID
### Czat
- `GET /shows/{id}/chat?since={id}`: pobranie komunikatów od podanego ID
- `POST /shows/{id}/chat`: wysyła komunikat
### Most do koszyka
- `POST /cart/add`: dodaje produkt do koszyka ze śledzeniem źródła (`show_id`, `product_id`, `quantity`)
- `GET /cart/summary`: licznik i suma bieżącego koszyka
### Nagrywanie i powtórka
- `POST /shows/{id}/replay/chunk`: wysyłka multipart fragmentu WebM
- `GET /shows/{id}/replay`: segmenty i oś czasu zdarzeń do odtworzenia
## Struktura wtyczki (PSR-4)
```
df-native-live-shopping/
├── df-native-live-shopping.php # Bootstrap
├── uninstall.php
├── readme.txt
├── assets/
│ ├── js/ (host.js, viewer.js, admin.js, block-editor.js)
│ └── css/ (host.css, viewer.css, admin.css)
├── languages/ # 5 .po/.mo + .pot
├── templates/ # single-live-show.php, viewer-container.php, ...
└── src/
├── Plugin.php
├── Activator.php Deactivator.php
├── PostType/ (LiveShow.php)
├── Database/ (Schema + 5 Repository.php)
├── Admin/ (AdminPages, MetaBoxes, SettingsPage)
├── Api/ (RestController, SignalingController, CartController)
├── Recording/ (RecordingHandler)
├── Replay/ (ReplayHandler)
├── Frontend/ (Renderer, Shortcode, Block)
└── Compat/ (PolylangCompat)
```
Główna przestrzeń nazw: `DataFireflyNativeLiveShopping`, ręczny autoloader PSR-4 zadeklarowany w `df-native-live-shopping.php`.
## Rozwiązywanie problemów
### Widzowie nie widzą obrazu
- Sprawdź, czy witryna działa po HTTPS (obowiązkowe przy WebRTC)
- Otwórz konsolę przeglądarki po stronie widza i poszukaj błędów `ICE failed` albo `connection state failed`
- Skonfiguruj serwer TURN, jeśli publiczność to głównie urządzenia mobilne w 4G
- Sprawdź, czy pasmo wysyłania prowadzącego jest wystarczające (narzędzie fast.com po stronie prowadzącego)
### Konsola prowadzącego nie wykrywa kamery
- Sprawdź, czy przeglądarka udzieliła zezwolenia (ikona kłódki w pasku adresu)
- Na macOS sprawdź uprawnienia systemowe: _Preferencje → Bezpieczeństwo → Kamera_
- Zamknij inne aplikacje korzystające z kamery (Zoom, Teams, OBS)
### Fragmenty powtórki się nie wysyłają
- Sprawdź `upload_max_filesize` i `post_max_size` w php.ini (celuj w minimum 20 MB)
- Sprawdź `LimitRequestBody` po stronie Apache, jeśli dotyczy
- Zajrzyj do dziennika aktywności konsoli prowadzącego, aby ustalić dokładny błąd
- Sprawdź uprawnienia katalogu `wp-content/uploads`
### Koszyk nie zachowuje dodanych pozycji
- Sprawdź, czy żadna wtyczka cache nie cache'uje endpointów `/wp-json/df-nls/v1/*`
- Sprawdź, czy ciasteczka WooCommerce (`woocommerce_cart_hash`, `wp_woocommerce_session_*`) są prawidłowo wystawiane
- Przy ścisłym HTTPS sprawdź, czy ciasteczka mają flagę `Secure`
### Powtórki zajmują za dużo miejsca
- Skróć retencję (na przykład z 90 do 30 dni) w ustawieniach
- Wyłącz nagrywanie dla transmisji, przy których nie jest potrzebne (pole „Zezwól na powtórkę" w meta boksie _Opcje_)
- Zmniejsz bitrate, modyfikując `host.js` (zmienna `videoBitsPerSecond`)
## Deinstalacja
Przy zwykłym wyłączeniu dane są zachowywane, a crony wyrejestrowywane. Przy **pełnym usunięciu** wtyczki ze strony _Wtyczki_ plik `uninstall.php` wykonuje:
- Usunięcie 5 własnych tabel
- Usunięcie wszystkich opcji `dfnls_*`
- Odebranie uprawnień rolom
- Wyrejestrowanie cronów
- Opcjonalnie: usunięcie typów treści i wszystkich załączników powtórek, jeśli przed deinstalacją włączono opcję `dfnls_uninstall_delete_data`
**Uwaga**: domyślnie transmisje i ich powtórki NIE są usuwane przy deinstalacji. Aby usunąć wszystko, włącz w ustawieniach opcję _Usuń wszystkie dane przy deinstalacji_ przed odinstalowaniem.
## Wsparcie i rozwój
Wsparcie techniczne w cenie przez 12 miesięcy w panelu klienta DataFirefly. Aktualizacje wtyczki dostępne są z Twojego konta, z powiadomieniem e-mail o wersjach głównych.
Pomysły rozwojowe z mapy drogowej:
- Automatyczne przełączenie na SFU po przekroczeniu progu widzów
- Ankiety na żywo (poll.open / poll.close już zarezerwowane w protokole zdarzeń)
- Natywna analityka (średni czas oglądania, współczynnik konwersji per transmisja)
- Wielu prowadzących (dwie osoby jednocześnie)