# DataFirefly Live Shopping: kompletny przewodnik

> Instalacja i konfiguracja modułu DataFirefly Live Shopping dla PrestaShop 8 i 9: natywne wideo HLS / MP4 / embed, Studio czasu rzeczywistego, oferty błyskawiczne, czat i replaye.

- Strona: <https://www.datafirefly.com/pl/documentation/dflive/>
- Język: pl
- Zaktualizowano: 2026-10-26
- Inne języki: [fr](https://www.datafirefly.com/documentation/dflive/index.md), [en](https://www.datafirefly.com/en/documentation/dflive/index.md), [es](https://www.datafirefly.com/es/documentation/dflive/index.md), [de](https://www.datafirefly.com/de/documentation/dflive/index.md), [it](https://www.datafirefly.com/it/documentation/dflive/index.md), [nl](https://www.datafirefly.com/nl/documentation/dflive/index.md), [pt](https://www.datafirefly.com/pt/documentation/dflive/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## Wprowadzenie

Moduł **DataFirefly Live Shopping** (`dflive`) zamienia sklep PrestaShop w platformę **sprzedaży wideo na żywo**. Prowadzisz transmisję, przypinasz produkty w czasie rzeczywistym, uruchamiasz oferty flash, klienci dodają produkty do koszyka bez opuszczania transmisji, a sesja pozostaje dostępna jako powtórka. Wszystko działa w Twoim sklepie: bez zewnętrznej platformy live shoppingu i bez abonamentu.

Trzy filary: **natywne wideo** (HLS, MP4 lub embed), **Studio w czasie rzeczywistym** w panelu do prowadzenia transmisji oraz **warstwa zakupowa** (przypinanie produktów, oferty flash, natywny koszyk, czat, reakcje, social proof, przypomnienia e-mail).

## Zgodność

- PrestaShop **od 1.7.0 do 1.7.8**, **8.x** i **9.x** (od wersji 1.1.0 modułu)
- PHP od 5.6 do 8.3, zależnie od wersji PrestaShop
- Motywy Classic i Hummingbird oraz motywy na nich oparte
- Jeden sklep i multistore
- Wielojęzyczność (5 języków w zestawie: FR, EN, ES, DE, IT)
- Brak zależności (ani Composera, ani frameworka); `hls.js` jest wbudowany w moduł
- Zgodny z hostingiem współdzielonym (synchronizacja przez polling AJAX, bez WebSocket i SFU)

Interfejs modułu jest przetłumaczony na francuski, angielski, hiszpański, niemiecki i włoski. W sklepie po polsku teksty modułu wyświetlają się po francusku (język źródłowy), dopóki ich nie przetłumaczysz w **Międzynarodowe > Tłumaczenia**. Dlatego poniżej przyciski podano z ich oryginalną francuską nazwą. W PrestaShop 1.7.0–1.7.5 część tekstów (system XLF) pozostaje po francusku także w pozostałych językach.

## Wymagania

Moduł odpowiada za **odtwarzanie** wideo i całą warstwę zakupową, ale **źródło wideo** zapewniasz Ty. W zależności od trybu:

- **HLS**: strumień `.m3u8` z własnego serwera HLS, Mux lub Cloudflare Stream, zasilany enkoderem takim jak OBS.
- **MP4**: adres publicznie dostępnego pliku `.mp4`.
- **Embed**: transmisja YouTube, Twitch lub Vimeo (adres lub kod ``).

Aby działały przypomnienia, sklep musi mieć skonfigurowaną wysyłkę e-maili (**Zaawansowane > E-mail**).

Zalecany jest HTTPS: autoodtwarzanie i pełny ekran działają lepiej w sklepie obsługiwanym przez HTTPS, co dotyczy już prawie wszystkich sklepów produkcyjnych.

## Instalacja

1. W panelu otwórz **Moduły > Menedżer modułów**.
2. Kliknij **Załaduj moduł** i wybierz plik `dflive.zip`.
3. Po instalacji otwórz **Sprzedaż > Live Shopping > Lives & Replays**.

Podczas instalacji moduł tworzy swoje tabele (sesje, produkty sesji, wiadomości, zdarzenia, obecność, przypomnienia), rejestruje zakładki w **Sprzedaż**, dodaje trasy `/live` i `/live/{id}-{slug}` oraz włącza widget strony głównej.

## Aktualizacja z wersji 1.0.0

1. W **Moduły > Menedżer modułów** załaduj nowy plik `dflive.zip` (lub podmień folder `modules/dflive` przez FTP).
2. Kliknij **Aktualizuj** w wierszu modułu, jeśli PrestaShop to zaproponuje.

Skrypt aktualizacji 1.1.0 uruchamia się automatycznie, bez utraty danych. Skrypt:

- dodaje potrzebne kolumny (ochrona przed floodem dla gości, język i sklep przypomnień);
- przypisuje istniejące transmisje do wszystkich sklepów;
- zastępuje puste daty zapisane jako `0000-00-00` wartościami pustymi (NULL);
- usuwa niepotrzebny już hook `displayHeader`.

Jeśli korzystasz z CCC (łączenie CSS i JS), po aktualizacji wyczyść pamięć podręczną PrestaShop (**Zaawansowane > Wydajność > Wyczyść pamięć podręczną**), aby wczytały się nowe pliki odtwarzacza.

## Tworzenie transmisji

W **Sprzedaż > Live Shopping > Lives & Replays** kliknij **Dodaj nowy**. Formularz ma zakładki:

### Ogólne

- **Tytuł** i **opis** transmisji (wielojęzyczne).
- **Prowadzący**: nazwa wyświetlana jako host w czacie i pod wideo.
- **Zaplanowana data / godzina**: uruchamia odliczanie u widza.
- **Status**: zaplanowana, na żywo lub zakończona. Statusem można sterować także ze Studio; zmiana w formularzu ma te same skutki (daty, czyszczenie ofert, aktualizacja u widzów).
- **Obraz okładki**: JPG, PNG, GIF lub WebP, wyświetlany przed transmisją i na listach. Sprawdzany jest rzeczywisty typ pliku: inne pliki są odrzucane.

### Wideo

- **Typ źródła wideo**: HLS, MP4 lub embed.
- **Źródło wideo**: adres `.m3u8`, adres `.mp4` albo adres / kod `` embed, zależnie od typu. W przypadku kodu embed u widza używany jest tylko adres iframe.
- **Adres powtórki (VOD)** (opcjonalnie): np. nagranie z serwera HLS, odtwarzane automatycznie po zakończeniu transmisji.

### Produkty

Przypisz produkty prezentowane w transmisji za pomocą wyszukiwarki AJAX (nazwa, indeks lub ID). **Przeciągnij i upuść** wiersze, aby ustalić kolejność. Wyłączony produkt pozostaje na liście, ale nie jest pokazywany podczas transmisji.

### Opcje

Włącz lub wyłącz czat, reakcje i powtórkę dla tej sesji oraz jej widoczność w sklepie. W multistore wybierz **sklepy**, w których transmisja jest publikowana.

### SEO

Uzupełnij **meta tytuł**, **meta opis** i opcjonalnie **przyjazny URL** strony transmisji (puste pole zostanie wygenerowane z tytułu).

## Nadawanie strumienia

Dla transmisji HLS zasada jest następująca:

1. Skonfiguruj enkoder (np. OBS) do nadawania na serwer HLS, Mux lub Cloudflare Stream.
2. Skopiuj wyjściowy adres `.m3u8` i wklej go w polu **Źródło wideo** sesji.
3. Rozpocznij nadawanie w enkoderze, otwórz Studio i kliknij **Lancer le live** (uruchom transmisję).

Strumień ładuje się u widzów dopiero po uruchomieniu transmisji. Jeśli strumień HLS jest chwilowo niedostępny (enkoder startuje później, przerwa w sieci), odtwarzacz automatycznie ponawia próbę.

Moduł nie wiąże Cię z żadną infrastrukturą: wybierasz własny łańcuch nadawczy (własny serwer lub chmura) i po prostu wklejasz adres. Do szybkiego testu wystarczy plik MP4 lub embed YouTube / Twitch.

## Studio (reżyserka)

Studio to reżyserka w panelu. Otwórz je przyciskiem **Studio** na liście transmisji.

- **Lancer le live / Terminer** (uruchom / zakończ): zmienia status sesji. Przy starcie osoby zapisane na przypomnienie dostają e-mail. Po zakończeniu trwające oferty flash są usuwane, a produkt odpinany.
- **Épingler** (przypnij produkt): jego karta od razu pojawia się na wideo widzów, także tych, którzy dołączą później. Przypięcie produktu automatycznie odpina poprzedni. Moment pierwszej prezentacji jest zapisywany dla osi czasu powtórki.
- **Offre flash** (oferta flash): wpisz rabat (np. `20%` lub `10`) i w razie potrzeby **czas trwania** (od 5 do 60 minut lub bez limitu). Moduł tworzy w locie `SpecificPrice`, a nowa cena od razu pojawia się u widzów. Przycisk **×** kończy ofertę i przywraca cenę regularną u wszystkich.
- **Annonce épinglée** (przypięte ogłoszenie): wyświetla baner na wideo widzów i dodaje przypiętą wiadomość do czatu.
- **Wiadomość prowadzącego**: pole pod czatem pozwala pisać w imieniu hosta.
- **Moderacja**: ukrywanie, pokazywanie lub przypinanie dowolnej wiadomości. Ukryta wiadomość znika także u widzów, którzy już ją otrzymali.
- **Statystyki na żywo**: liczba widzów, reakcji i zapisów na przypomnienia w czasie rzeczywistym.

Studio wysyła zdarzenia (przypięcie, oferta, ogłoszenie, zmiana statusu, ukrycie), które widzowie odbierają w następnym cyklu pollingu. Interwał ustawisz w konfiguracji modułu.

## Przypomnienia e-mail

W **zaplanowanej** sesji widz wpisuje swój e-mail (uzupełniony automatycznie, jeśli jest zalogowany) i klika przycisk zapisu (**Me prévenir** w interfejsie francuskim). Liczba zapisanych jest widoczna na stronie transmisji i w Studio.

Po kliknięciu przycisku uruchomienia transmisji od razu wychodzi pierwsza partia e-maili; pozostałe są wysyłane partiami po 20, dopóki Studio jest otwarte. Każdy zapisany otrzymuje wiadomość w języku, w którym się zapisał (FR, EN, ES, DE lub IT; dla innych języków, w tym polskiego, po angielsku), z bezpośrednim linkiem do transmisji. Każda osoba jest powiadamiana tylko raz.

Szablony znajdują się w `modules/dflive/mails/{język}/dflive_reminder.html` i `.txt`. Aby wysyłać e-mail po polsku, skopiuj folder `mails/en` do `mails/pl` i przetłumacz pliki.

## Strona widza

Strona transmisji (`/live/{id}-{slug}`) zawiera:

- **Odtwarzacz** z oznaczeniem transmisji na żywo i liczbą widzów. Przeglądarki pozwalają na autoodtwarzanie tylko **bez dźwięku**: na wideo pojawia się przycisk włączenia dźwięku.
- **Kartę przypiętego produktu** na wideo, z przyciskiem dodania do koszyka.
- **Listę produktów** transmisji, każdy dodawany do natywnego koszyka PrestaShop jednym kliknięciem. Blok koszyka motywu odświeża się bez otwierania okna, aby nie przerywać transmisji. Uwzględniane są stany magazynowe, minimalne ilości i reguły koszyka; dla produktu z kombinacjami dodawana jest kombinacja domyślna.
- **Czat** (klienci i, jeśli włączono, goście) z ochroną przed floodem, wiadomościami prowadzącego i animowanymi serduszkami.
- **Ogłoszenia** prowadzącego jako baner na wideo.
- **Powiadomienia social proof** o dodaniu produktu do koszyka przez innego widza.

W **zaplanowanej** sesji widz widzi odliczanie (według czasu serwera) i może zapisać się na przypomnienie. Po rozpoczęciu transmisji strona automatycznie przechodzi w tryb na żywo, bez przeładowania.

## Powtórki i oś czasu produktów

Po zakończeniu transmisji strona automatycznie przechodzi w tryb powtórki:

- jeśli podano **adres powtórki**, wczytywane jest nagranie z kontrolkami odtwarzania;
- w transmisji typu **embed** embed pozostaje widoczny (lub adres powtórki, jeśli go podano);
- bez źródła powtórki wyświetla się ekran zakończenia transmisji.

Podczas odtwarzania powtórki każdy produkt pojawia się na wideo w momencie, w którym został po raz pierwszy przypięty na żywo. Czas liczony jest od uruchomienia transmisji: dla dokładnej synchronizacji nagranie powinno zaczynać się w chwili kliknięcia przycisku uruchomienia.

Jeśli opcja powtórki jest wyłączona, strona zakończonej transmisji przekierowuje na listę `/live`.

## Ustawienia modułu

Strona konfiguracji (**Moduły > Menedżer modułów > DataFirefly Live Shopping > Konfiguruj**) grupuje ustawienia globalne. Wartości spoza zakresu są automatycznie korygowane.

- **Interwał pollingu** (domyślnie 3000 ms, od 1000 do 60 000): częstotliwość odświeżania czatu i zdarzeń w trakcie transmisji. Przed transmisją i w powtórce tempo jest automatycznie zmniejszane.
- **Czat na żywo** i **czat gości**: włączają czat i ewentualnie udział niezalogowanych odwiedzających.
- **Reakcje** i **social proof**: włączają serduszka i powiadomienia o dodaniu do koszyka.
- **Limit czasu widza** (domyślnie 30 s, od 10 do 600): czas, po którym nieaktywny widz przestaje być liczony.
- **Maks. długość wiadomości** (domyślnie 300, od 20 do 500) i **ochrona przed floodem** (domyślnie 3 s, 0 aby wyłączyć): porządkują czat. Dla gości ochrona działa według adresu IP (zapisywanego jako skrót, nigdy jawnie).
- **Widget strony głównej** i **liczba transmisji** (domyślnie 4, od 1 do 24): sterują blokiem na stronie głównej.

## Strona listy i widget strony głównej

Strona `/live` pokazuje transmisje **trwające**, **nadchodzące** (najbliższe jako pierwsze) i **powtórki** (najnowsze jako pierwsze). Widget strony głównej wyróżnia te sesje w ustawionym limicie. W multistore każdy sklep pokazuje tylko przypisane do niego transmisje.

## Bezpieczeństwo

- Czat, dodawanie do koszyka i zapis na przypomnienia są chronione standardowym tokenem anty-CSRF PrestaShop.
- Wiadomości czatu są oczyszczane z HTML przed wyświetleniem.
- Jako okładka akceptowane są tylko prawdziwe obrazy, a folder uploadu blokuje wykonywanie skryptów.
- W kodzie embed używany jest tylko adres iframe: do strony nie trafiają żadne atrybuty ani skrypty.

## FAQ i rozwiązywanie problemów

### Wideo się nie uruchamia

Sprawdź typ i źródło wideo. Dla HLS upewnij się, że adres `.m3u8` jest publicznie dostępny, a enkoder nadaje; odtwarzacz automatycznie ponawia próby przez około 90 sekund. Dla embed sprawdź, czy adres YouTube, Twitch lub Vimeo jest poprawny. Przed uruchomieniem transmisji wideo nie jest ładowane: to normalne.

### Transmisja jest bez dźwięku

To zasada przeglądarek: autoodtwarzanie jest dozwolone tylko bez dźwięku. Widz klika przycisk włączenia dźwięku na wideo.

### Cena oferty flash nie zmienia się u widzów

Oferta działa przez `SpecificPrice` tworzony w locie i jest przekazywana w następnym cyklu pollingu. Sprawdź interwał pollingu, czy oferta nie została już zakończona i czy nie minął jej czas. Rabat kwotowy równy cenie produktu lub wyższy jest odrzucany.

### Czat się nie wyświetla lub odrzuca wiadomości

Sprawdź, czy czat jest włączony dla sesji i globalnie. Dla niezalogowanych odwiedzających musi być włączony czat gości. Ochrona przed floodem wymusza minimalny odstęp między wiadomościami. Jeśli pojawia się prośba o przeładowanie strony, sesja odwiedzającego się zmieniła (np. logowanie w innej karcie): wystarczy przeładować.

### Zapisani nie otrzymali e-maila z przypomnieniem

Sprawdź konfigurację e-mail sklepu (**Zaawansowane > E-mail**, z e-mailem testowym) i dziennik zdarzeń (**Zaawansowane > Logi**). E-maile wychodzą przy starcie transmisji, a potem partiami, dopóki Studio jest otwarte: zostaw Studio otwarte do zakończenia wysyłki.

### Odliczanie się nie wyświetla

Odliczanie pojawia się tylko w sesjach **zaplanowanych** z podaną datą. Bez daty wyświetla się komunikat o zbliżającym się starcie.

### Licznik koszyka się nie aktualizuje

Produkt jest dodawany do koszyka; odświeżenie bloku koszyka zależy od modułu koszyka motywu (`ps_shoppingcart`). Jeśli używasz CCC, wyczyść pamięć podręczną po aktualizacji modułu.

### Czy moduł działa na hostingu współdzielonym?

Tak. Synchronizacja w czasie rzeczywistym korzysta z pollingu AJAX, bez serwera WebSocket i SFU, co zapewnia zgodność z typowymi hostingami współdzielonymi.

## Historia wersji

### 1.1.0 — 26 października 2026

- Zgodność z PrestaShop od 1.7.0 do 1.7.8 (PHP od 5.6 do 8.3), oprócz 8 i 9.
- Przypomnienia wysyłane e-mailem przy starcie transmisji (5 języków).
- Powtórki: automatyczne przełączenie, wideo nie jest już zasłonięte, oś czasu produktów.
- Przycisk włączenia dźwięku, automatyczne wznawianie HLS, przypięty produkt widoczny dla spóźnionych widzów.
- Oferty flash z czasem trwania, przywracanie ceny regularnej po zakończeniu.
- Multistore: wybór sklepów dla każdej transmisji.
- Bezpieczeństwo: token anty-CSRF, kontrola uploadu, ochrona przed floodem po IP, filtrowany embed.
- Przyjazne adresy, meta SEO, okruszki, przeciąganie produktów, ogłoszenia jako baner.

### 1.0.0 — 6 czerwca 2026

- Pierwsza wersja dla PrestaShop 8 i 9.