DataFirefly Native Live Shopping — Dokumentation

Überblick

DataFirefly Native Live Shopping macht deinen WooCommerce-Shop zu einer eigenständigen Live-Shopping-Plattform, ganz ohne Abhängigkeit von Drittanbieter-Diensten wie Bambuser oder CommentSold. Die Übertragung nutzt WebRTC-Peer-to-Peer-Mesh vom Browser des Hosts zu jedem Zuschauer, die Signalisierung läuft über die WordPress-REST-API, und die Replay-Aufzeichnung erfolgt clientseitig über die MediaRecorder-API und wird als WordPress-Anhang gespeichert.

Das Plugin bietet:

• Einen dfnls_live_show-CPT, um deine Lives anzulegen und zu planen
• Eine Host-Konsole, integriert in den WordPress-Admin (Kameravorschau, Steuerungen, Produkte, Chat)
• Ein schlüsselfertiges Zuschauer-Erlebnis mit anklickbaren Produkt-Einblendungen und Chat
• Eine WooCommerce-Warenkorb-Bridge (in den offiziellen Warenkorb legen, ohne das Live zu verlassen)
• Eine automatische Wiederholung, zeitlich synchronisiert mit den Live-Ereignissen (Spotlights, Gutscheine, Nachrichten)
• Einen dedizierten Gutenberg-Block und den Shortcode [dfnls_live]

Voraussetzungen

• WordPress 6.3 oder höher
• WooCommerce 8.0 oder höher (HPOS-kompatibel)
• PHP 8.1 oder höher (getestet bis 8.3)
• HTTPS erforderlich — getUserMedia() und getDisplayMedia() funktionieren nicht über unsicheres HTTP
• Unterstützte Browser auf der Zuschauerseite: Chrome 80+, Firefox 75+, Edge 80+, Safari 14+, Opera 67+
• Ein aktueller Browser auf der Host-Seite mit zugänglicher Kamera und Mikrofon

Installation

1. Lade das Archiv df-native-live-shopping.zip aus deinem DataFirefly-Konto herunter.
2. Gehe in WordPress zu Plugins → Installieren → Plugin hochladen.
3. Wähle die ZIP-Datei aus und klicke auf Jetzt installieren.
4. Nach der Installation klicke auf Plugin aktivieren.
5. Ein neues Menü Live Shopping erscheint in der Admin-Seitenleiste.

Beim Aktivieren führt das Plugin folgendes durch:

• Erstellt 5 Custom Tables (wp_dfnls_signaling, _sessions, _events, _replay_parts, _chat)
• Fügt die Capabilities manage_dfnls_lives und host_dfnls_lives zu den Rollen administrator und shop_manager hinzu
• Plant zwei Crons: tägliche Bereinigung alter Wiederholungen, stündliche Bereinigung veralteter Signalisierungsnachrichten
• Registriert Standardoptionen (Google-STUN-Server, 90 Tage Aufbewahrung, 25 Zuschauer max, usw.)

Erstes Live in 5 Minuten

Der kürzeste Weg, um dein erstes Live zu starten:

1. Menü Live Shopping → Neues Live
2. Gib einen Titel ein (z. B. „Frühjahrs-Flash-Sale“)
3. In der Produkte-Metabox suche und wähle die WooCommerce-Produkte aus, die du präsentieren möchtest (per Drag & Drop neu anordnen)
4. Optional: unter Zeitplanung ein Startdatum und eine Startzeit festlegen (ein Countdown erscheint auf der Zuschauerseite)
5. Live veröffentlichen
6. Gehe zu Live Shopping → Host-Konsole und wähle dein Live aus
7. Klicke auf Übertragung starten und erlaube den Zugriff auf Kamera und Mikrofon
8. Teile die öffentliche URL des Lives (/live/dein-slug/) mit deinem Publikum

Host-Konsole

Die Host-Konsole ist das Dashboard, von dem aus du dein Live moderierst. Zugänglich über Live Shopping → Host-Konsole. Funktionen:

Videovorschau und Steuerungen

• Kamera: schaltet die Kamera an/aus
• Mikrofon: schaltet das Mikrofon an/aus
• Bildschirmfreigabe: ersetzt den Kamerastream durch eine Bildschirmfreigabe (nützlich für Demos)
• Starten / Stoppen: Haupt-Steuerungs-Buttons für das Live

Produkte hervorheben

Die Liste der mit dem Live verknüpften Produkte erscheint rechts. Jedes Produkt hat einen Hervorheben-Button. Ein Klick darauf:

• Lässt das Produkt sofort als Overlay bei allen Zuschauern erscheinen
• Zeichnet ein zeitmarkiertes product.spotlight-Ereignis für die Replay-Sync auf
• Ein zweiter Klick auf denselben Button entfernt das Overlay

Gutschein-Versand

Gib einen Promo-Code ein (z. B. LIVE20) und optional eine Beschreibung, dann klick auf Senden. Ein animierter Flash erscheint auf dem Bildschirm der Zuschauer mit einem „Kopieren“-Button zum Übernehmen des Codes.

Host-Nachrichten

Ein freies Textfeld erlaubt es, eine Nachricht zu senden, die auf der Zuschauerseite als temporäres Banner erscheint (standardmäßig 8 Sekunden).

Live-Chat

Der Host-/Zuschauer-Chat ist in die Konsole integriert. Nachrichten des Hosts sind in allen Ansichten visuell hervorgehoben (Badge und rote Umrandung).

Aktivitätslog

Ein Log am unteren Rand der Konsole zeigt in Echtzeit Verbindungen/Trennungen, gesendete Ereignisse, Replay-Chunk-Uploads und eventuelle Fehler an.

Zuschauer-Ansicht

Was das Publikum auf der öffentlichen URL des Lives sieht:

• Vor dem Live — Ist das Live geplant, wird ein Warte-Screen mit Countdown bis zur geplanten Zeit angezeigt. Automatisches Status-Polling alle 5 Sekunden, um den Start zu erkennen.
• Während des Lives — Live-Video mit pulsierender „LIVE“-Pille und Zuschauerzähler. Sidebar mit zwei Tabs: Produkte (anklickbare Liste der Live-Produkte) und Chat.
• Produkt-Einblendung — Wenn der Host ein Produkt hervorhebt, gleitet eine Karte ins Bild (standardmäßig unten rechts) mit Foto, Name, Preis und In den Warenkorb-Button.
• In den Warenkorb — Ein Klick auf den Button legt das Produkt in den offiziellen WooCommerce-Warenkorb. Ein FAB (Floating Button) erscheint unten rechts mit dem Warenkorb-Artikelzähler.
• Gutschein-Flash — Vom Host gesendet, erscheint oben mit Animation und Kopierbutton.
• Nach dem Live — Wenn die Wiederholung aktiviert ist, erlaubt ein „Wiederholung ansehen“-Button, das Live komplett mit synchronisierten Ereignissen erneut abzuspielen.

Globale Einstellungen

Menü Live Shopping → Einstellungen. Hauptbereiche:

STUN-Server

Standardmäßig werden Googles öffentliche STUN-Server verwendet:

stun:stun.l.google.com:19302
stun:stun1.l.google.com:19302

Du kannst eigene STUN-Server hinzufügen (einer pro Zeile).

TURN-Server

Optional, aber empfohlen für Zuschauer hinter symmetrischem NAT (manche 4G-Anbieter, Unternehmens-VPNs). Format:

turn:turn.beispiel.de:3478
turns:turn.beispiel.de:5349

Gib die zugehörigen Zugangsdaten TURN-Benutzername und TURN-Passwort ein.

Aufzeichnung und Wiederholung

• Aufzeichnung aktiviert: global ja / nein
• Chunk-Dauer (ms): standardmäßig 5000. Kürzer = mehr Crash-Resilienz aber mehr Anfragen; länger = weniger Anfragen aber mehr Verlust bei einem Crash
• Aufbewahrung der Wiederholungen (Tage): standardmäßig 90. Danach löscht der tägliche Cron automatisch die WebM-Dateien und zugehörige Einträge

Kapazität und Overlay

• Maximale Zuschauerzahl pro Host: standardmäßig 25. An deine Upload-Bandbreite anpassen
• Overlay-Position: rechts, links oder unten

Live-Standardeinstellungen

• Chat standardmäßig aktiviert
• Wiederholung standardmäßig aktiviert
• Anmeldung standardmäßig erforderlich

STUN- und TURN-Server — wann ein TURN einrichten

STUN ist ein einfacher Public-IP-Discovery-Server, kostenlos und in ~85 % der Fälle ausreichend. TURN dagegen leitet den Media-Traffic tatsächlich weiter: es verbraucht Bandbreite, ermöglicht aber die Verbindung zwischen zwei Clients, die sich nicht direkt erreichen können.

Richte einen TURN ein, wenn:

• Deine Zuschauer sich regelmäßig beschweren, dass sie das Video nicht sehen (WebRTC-Verbindungszustand hängt bei „connecting“)
• Dein Publikum viele 4G/5G-Mobilnutzer bei Anbietern mit symmetrischem NAT enthält (Free Mobile in Frankreich zum Beispiel)
• Dein Host oder deine Zuschauer hinter einem strikten Unternehmens-VPN sitzen

Aufzeichnung und Wiederholung

Wie die Aufzeichnung funktioniert

Die Aufzeichnung erfolgt komplett im Browser des Hosts über die MediaRecorder-API:

1. Beim Start des Lives wird MediaRecorder instanziiert und erkennt automatisch den besten verfügbaren Codec (VP9 > VP8 > H.264, opus für Audio, ~1,5 Mbps Video + 96 kbps Audio)
2. Alle 5 Sekunden (konfigurierbar) wird ein WebM-Chunk ausgelöst und per POST /wp-json/df-nls/v1/shows/{id}/replay/chunk hochgeladen
3. Der Chunk wird als WordPress-Anhang gespeichert, benannt als dfnls-show-{id}-part-{NNNNN}.webm, mit post_parent zeigt auf das Live
4. Die Tabelle wp_dfnls_replay_parts speichert die Reihenfolge und Dauer jedes Chunks

Wie die Wiederholung funktioniert

Beim Laden der Seite im Replay-Modus:

1. Der Viewer ruft GET /wp-json/df-nls/v1/shows/{id}/replay auf, das die geordnete Segmentliste und die Ereignis-Timeline zurückgibt
2. Die Segmente werden sequentiell über das ended-Event des <video>-Elements geladen (nativer Fallback)
3. Eine MediaSource-Variante erlaubt transparente Verkettung, falls der Browser sie unterstützt
4. Die Wiedergabeposition (kumulative Zeit) wird mit den offset_ms jedes Ereignisses verglichen — wenn der Punkt erreicht ist, löst der Viewer lokal dasselbe Verhalten wie im Live aus (Overlay anzeigen, Gutschein-Flash, Nachricht)

Speicherung und Speicherplatz

Größenordnung: ein einstündiges Live bei 1,5 Mbps Video + 96 kbps Audio produziert etwa 720 MB WebM-Dateien. Bei 90 Tagen Aufbewahrung und 4 Lives pro Monat rechne mit ~10 GB Speicherplatz für Wiederholungen.

Integration: Shortcode, Block, direkte URL

Direkte öffentliche URL

Jedes veröffentlichte Live hat eine automatisch generierte URL:

https://deine-website.de/live/dein-slug/

Das ist der einfachste Weg: teile diesen Link mit deinem Publikum.

Shortcode

Um ein Live in eine bestehende Seite oder einen Artikel einzufügen:

[dfnls_live id="42"]
[dfnls_live id="42" mode="live"]
[dfnls_live id="42" mode="replay"]
[dfnls_live id="42" mode="auto"]

Verfügbare Modi:

• auto (Standard): erkennt den Live-Status und zeigt Live / Warten / Replay entsprechend an
• live: erzwingt die Live-Übertragungs-Ansicht (nützlich für Tests)
• replay: erzwingt Replay-Modus, auch wenn das Live noch läuft

Gutenberg-Block

Suche im Block-Editor nach „Live Shopping“. Der Block unterstützt wide– und full-Ausrichtungen, bietet einen Selektor zur Live-Auswahl und einen Modus-Selektor in der Inspektor-Seitenleiste.

Benutzerdefinierte PHP-Vorlage

Der CPT verwendet templates/single-live-show.php. Zum Überschreiben kopiere diese Datei in dein Theme unter dein-theme/df-native-live-shopping/single-live-show.php.

Mehrsprachig mit Polylang

Das Plugin deklariert den CPT dfnls_live_show als bei Polylang übersetzbar. Bei der Aktivierung, wenn Polylang bereits installiert ist:

• Jedes Live kann eine FR-, EN-, ES-, DE-, IT-Version haben, usw.
• Kritische Metadaten (_dfnls_product_ids, _dfnls_scheduled_at, Live-Optionen) werden automatisch zwischen Übersetzungen kopiert
• Die 5 integrierten Sprachen (FR, EN, ES, DE, IT) werden automatisch entsprechend der WordPress-Locale geladen

HPOS und Kompatibilitäten

Das Plugin deklariert offiziell seine Kompatibilität mit dem Hochleistungs-Bestelldatenspeicher von WooCommerce (HPOS) über FeaturesUtil. Du kannst HPOS in deiner Installation aktivieren, ohne dass die Warenkorb-Bridge Probleme macht.

Ebenfalls kompatibel mit:

• WordPress Multisite (pro-Site-Installation, kein Netzwerkmodus)
• Shared Hosting (o2switch, OVH, Infomaniak, PlanetHoster) — die Signalisierung nutzt REST-Polling, keine WebSockets
• Cache-Plugins (WP Rocket, WP Super Cache) — die REST-Endpunkte des Plugins werden automatisch ausgeschlossen

Sicherheit und Capabilities

Das Plugin fügt zwei dedizierte Capabilities hinzu:

• manage_dfnls_lives — Erstellen, Bearbeiten, Löschen von Lives; Zugriff auf Einstellungen
• host_dfnls_lives — Zugriff auf die Host-Konsole, Start / Stop eines Lives

Beide Capabilities sind standardmäßig den Rollen administrator und shop_manager zugewiesen. Um einem Nutzer nur das Recht zu geben, zu moderieren, ohne Lives anlegen zu können:

$user = get_user_by('login', 'moderator');
$user->add_cap('host_dfnls_lives');

REST-Nonces

Alle Aktions-Routen (POST) sind durch einen wp_rest-Nonce geschützt. Viewer und Host erhalten ihren jeweiligen Nonce über wp_localize_script beim Seitenladen.

MIME-Validierung Uploads

Der Upload von Replay-Chunks wird streng über wp_check_filetype_and_ext validiert und akzeptiert nur video/webm und video/mp4. Dateien werden serverseitig umbenannt (dfnls-show-{id}-part-{NNNNN}.webm).

Cron und Wartung

Zwei WordPress-Crons werden bei der Aktivierung geplant:

• dfnls_cleanup_expired_replays — täglich. Löscht Wiederholungen von Lives, die seit mehr als N Tagen beendet sind (konfigurierbare Aufbewahrung). Verwendet wp_delete_attachment(..., true), um auch die physische Datei zu löschen.
• dfnls_cleanup_stale_signaling — stündlich. Bereinigt Signalisierungsnachrichten, die älter als 24 h sind, und Sessions, die länger als 90 Sekunden inaktiv waren.

Für Entwickler — REST-API

Alle Routen liegen unter dem Namespace df-nls/v1.

Show

• GET /shows/{id} — ruft ein Live ab (Status, Produkte, Optionen)
• POST /shows/{id}/join — als Viewer oder Host beitreten (Body: peer_id, role)
• POST /shows/{id}/leave — sauber verlassen
• POST /shows/{id}/heartbeat — Session offenhalten (auto alle 15 s auf Viewer-Seite)
• POST /shows/{id}/start — Live starten (nur Host)
• POST /shows/{id}/end — Live beenden (nur Host)
• GET /shows/{id}/viewers — Zähler aktiver Zuschauer

WebRTC-Signalisierung

• POST /signal/send — sendet eine SDP/ICE-Nachricht an einen Remote-Peer
• GET /signal/pull?peer={id} — ruft ausstehende Nachrichten ab und führt einen impliziten Heartbeat aus

Events

• POST /shows/{id}/event — zeichnet ein Ereignis auf (Spotlight, Nachricht, Gutschein)
• GET /shows/{id}/events?since={id} — Pull der Ereignisse seit einer gegebenen ID

Chat

• GET /shows/{id}/chat?since={id} — Pull der Nachrichten seit einer ID
• POST /shows/{id}/chat — sendet eine Nachricht

Warenkorb-Bridge

• POST /cart/add — fügt ein Produkt zum Warenkorb hinzu, mit Quellen-Tracking (show_id, product_id, quantity)
• GET /cart/summary — Zähler und Gesamtsumme des aktuellen Warenkorbs

Aufzeichnung und Wiederholung

• POST /shows/{id}/replay/chunk — Multipart-Upload eines WebM-Chunks
• GET /shows/{id}/replay — Segmente + Timeline-Events zum Abspielen

Plugin-Struktur (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)

Root-Namespace: DataFirefly / NativeLiveShopping, manueller PSR-4-Autoloader deklariert in df-native-live-shopping.php.

Fehlerbehebung

Zuschauer sehen das Video nicht

• Überprüfe, dass die Website auf HTTPS läuft (Pflicht für WebRTC)
• Öffne die Browser-Konsole auf Zuschauerseite, suche nach ICE failed– oder connection state failed-Fehlern
• Richte einen TURN-Server ein, wenn das Publikum viele 4G-Mobilnutzer enthält
• Prüfe, dass die Upload-Bandbreite des Hosts ausreicht (fast.com-Tool auf Host-Seite)

Die Host-Konsole erkennt die Kamera nicht

• Prüfe, dass der Browser die Berechtigung erteilt hat (Schloss-Symbol in der URL-Leiste)
• Unter macOS: Systemberechtigungen prüfen unter Einstellungen → Sicherheit → Kamera
• Andere Anwendungen schließen, die die Kamera nutzen (Zoom, Teams, OBS…)

Replay-Chunks werden nicht hochgeladen

• Prüfe upload_max_filesize und post_max_size in der php.ini (mindestens 20 MB)
• Prüfe LimitRequestBody auf Apache-Seite, falls zutreffend
• Sieh dir das Aktivitätslog der Host-Konsole an, um den genauen Fehler zu identifizieren
• Prüfe die Berechtigungen des Ordners wp-content/uploads

Warenkorb behält Ergänzungen nicht

• Prüfe, dass kein Cache-Plugin die /wp-json/df-nls/v1/*-Endpunkte cached
• Prüfe, dass die WooCommerce-Cookies (woocommerce_cart_hash, wp_woocommerce_session_*) korrekt ausgeliefert werden
• Bei striktem HTTPS: prüfe, dass Cookies das Secure-Flag haben

Wiederholungen belegen zu viel Speicherplatz

• Aufbewahrung reduzieren (z. B. von 90 auf 30 Tage) in den Einstellungen
• Aufzeichnung deaktivieren für Lives, in denen sie nicht nötig ist („Wiederholung erlauben“-Checkbox in der Optionen-Metabox)
• Bitrate reduzieren, indem host.js angepasst wird (Variable videoBitsPerSecond)

Deinstallation

Bei einfacher Deaktivierung bleiben die Daten erhalten und die Crons werden abgemeldet. Bei vollständiger Löschung des Plugins über Plugins führt uninstall.php folgendes durch:

• Löschung der 5 Custom Tables
• Löschung aller dfnls_*-Optionen
• Entfernung der Capabilities aus den Rollen
• Abmeldung der Crons
• Optional: Löschung der CPTs und aller Replay-Anhänge, falls die Option dfnls_uninstall_delete_data vor der Deinstallation aktiviert war

Support und Roadmap

Technischer Support enthalten für 12 Monate über den DataFirefly-Kundenbereich. Plugin-Updates sind über dein Konto verfügbar, mit E-Mail-Benachrichtigung bei größeren Versionen.

Roadmap-Ideen:

• Automatischer SFU-Wechsel ab einem Zuschauer-Schwellwert
• Live-Umfragen (poll.open / poll.close bereits im Ereignisprotokoll reserviert)
• Native Analytics (durchschnittliche Sehdauer, Konversionsrate pro Live)
• Multi-Host-Unterstützung (zwei gleichzeitige Moderatoren)