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

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

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

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

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

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.

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

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)