DataFirefly Native Live Shopping: documentatie

Overzicht

DataFirefly Native Live Shopping maakt van uw WooCommerce-winkel een zelfstandig live shopping-platform, zonder afhankelijkheid van een externe dienst als Bambuser of CommentSold. De uitzending gebruikt WebRTC peer-to-peer mesh vanuit de browser van de presentator naar elke kijker, de signalering verloopt via de WordPress REST API, en de replay wordt aan de clientzijde opgenomen met de MediaRecorder-API en daarna als WordPress-bijlagen opgeslagen.

De plugin biedt:

• een CPT dfnls_live_show om uw uitzendingen aan te maken en in te plannen;
• een presentatorconsole die in het WordPress-beheer is ingebouwd (camerapreview, bediening, producten, chat);
• een kant-en-klare kijkerservaring met aanklikbare producten in overlay en een chat;
• een brug naar de WooCommerce-winkelwagen (officieel toevoegen aan de winkelwagen zonder de uitzending te verlaten);
• een automatische replay die synchroon loopt met de gebeurtenissen van de uitzending (spotlights, coupons, berichten);
• een eigen Gutenberg-blok en de shortcode [dfnls_live].

Vereisten

• WordPress 6.3 of hoger
• WooCommerce 8.0 of hoger (compatibel met HPOS)
• PHP 8.1 of hoger (getest tot 8.3)
• HTTPS verplicht: getUserMedia() en getDisplayMedia() weigeren te werken over onbeveiligde HTTP
• Ondersteunde browsers aan kijkerszijde: Chrome 80+, Firefox 75+, Edge 80+, Safari 14+, Opera 67+
• Een recente browser aan presentatorzijde, met toegang tot camera en microfoon

Installatie

1. Download het archief df-native-live-shopping.zip vanuit uw DataFirefly-account.
2. Ga in WordPress naar Plugins → Nieuwe plugin en daarna Plugin uploaden.
3. Selecteer het ZIP-bestand en klik op Nu installeren.
4. Klik na de installatie op Plugin activeren.
5. Er verschijnt een nieuw menu Live Shopping in de beheerzijbalk.

Bij de activering doet de plugin het volgende:

• ze maakt 5 eigen tabellen aan (wp_dfnls_signaling, _sessions, _events, _replay_parts, _chat);
• ze voegt de capabilities manage_dfnls_lives en host_dfnls_lives toe aan de rollen administrator en shop_manager;
• ze plant twee crons in: een dagelijkse opruiming van oude replays en een uurlijkse opruiming van verouderde signaleringsberichten;
• ze legt de standaardopties vast (STUN-servers van Google, 90 dagen bewaartermijn, maximaal 25 kijkers en zo verder).

Uw eerste uitzending in 5 minuten

De kortste weg naar uw eerste uitzending:

1. Menu Live Shopping → Nieuwe uitzending.
2. Vul een titel in (bijvoorbeeld “Voorjaarsdeals”).
3. Zoek en selecteer in de metabox Producten de WooCommerce-producten die u wilt tonen (met slepen en neerzetten wijzigt u de volgorde).
4. Optioneel: leg bij Planning een startdatum en -tijd vast (kijkers zien dan een aftelklok).
5. Publiceer de uitzending.
6. Ga naar Live Shopping → Presentatorconsole en kies uw uitzending.
7. Klik op Uitzending starten en geef toestemming voor camera en microfoon.
8. Deel de publieke URL van de uitzending (/live/uw-slug/) met uw publiek.

Presentatorconsole

De presentatorconsole is het dashboard van waaruit u uw uitzending leidt. U bereikt die via Live Shopping → Presentatorconsole. De functies:

Videopreview en bediening

• Camera: schakelaar om de camera aan of uit te zetten
• Microfoon: schakelaar om de microfoon aan of uit te zetten
• Scherm delen: vervangt de camerastream door een gedeeld scherm (handig voor demonstraties)
• Starten en stoppen: de hoofdknoppen voor de uitzending

Producten uitlichten

De lijst met producten die aan de uitzending zijn gekoppeld, staat rechts. Elk product heeft een knop Uitlichten. Daarop klikken:

• toont het product meteen in overlay bij alle kijkers;
• legt een gebeurtenis product.spotlight met tijdstempel vast, voor de synchronisatie van de replay;
• een tweede klik op dezelfde knop haalt de overlay weg.

Coupons uitsturen

Vul een kortingscode in (bijvoorbeeld LIVE20) en eventueel een omschrijving, en klik daarna op Uitsturen. Bij de kijkers verschijnt een geanimeerde flits met een knop “Kopiëren” om de code met één klik over te nemen.

Presentatorberichten

Met een vrij invoerveld verstuurt u een bericht dat bij de kijkers als tijdelijke banner verschijnt (standaard 8 seconden).

Livechat

De chat tussen presentator en kijkers zit in de console ingebouwd. De berichten van de presentator zijn in alle weergaven visueel te onderscheiden (badge en rode rand).

Activiteitenlogboek

Onder in de console toont een logboek in realtime de verbindingen en verbrekingen, de uitgestuurde gebeurtenissen, de geüploade replaychunks en eventuele fouten.

Kijkersweergave

Wat uw publiek ziet zodra het op de publieke URL van de uitzending komt:

• Vóór de uitzending: is de uitzending ingepland, dan verschijnt een wachtscherm met een aftelklok tot het geplande tijdstip. De status wordt elke 5 seconden opgevraagd om de start te herkennen.
• Tijdens de uitzending: live video met een pulserend “LIVE”-bolletje en een kijkersteller. In de zijbalk staan twee tabbladen: Producten (de aanklikbare lijst met producten uit de uitzending) en Chat.
• Productoverlay: licht de presentator een product uit, dan schuift er een kaart in beeld (standaard rechtsonder) met foto, naam, prijs en de knop Toevoegen aan winkelwagen.
• Toevoegen aan de winkelwagen: met een klik op de knop komt het product in de officiële WooCommerce-winkelwagen. Rechtsonder verschijnt een zwevende knop met de teller van het aantal artikelen.
• Flitscoupon: door de presentator uitgestuurd, verschijnt bovenaan met animatie en een kopieerknop.
• Na de uitzending: is de replay ingeschakeld, dan kunnen kijkers via een knop “Replay bekijken” de uitzending opnieuw afspelen, met volledige synchronisatie van de gebeurtenissen.

Algemene instellingen

Menu Live Shopping → Instellingen. De belangrijkste onderdelen:

STUN-servers

Standaard worden de publieke STUN-servers van Google gebruikt:

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

U kunt uw eigen STUN-servers toevoegen (één per regel).

TURN-servers

Optioneel, maar aan te raden voor kijkers achter symmetrische NAT (sommige 4G-providers, bedrijfs-VPN’s). Formaat:

turn:turn.voorbeeld.com:3478
turns:turn.voorbeeld.com:5349

Vul de bijbehorende TURN username en TURN credential in.

Opname en replay

• Opname ingeschakeld: algemeen aan of uit
• Duur van de chunks (ms): standaard 5000. Korter betekent beter bestand tegen een crash maar meer verzoeken; langer betekent minder verzoeken maar meer verlies bij een crash
• Bewaartermijn van de replays (dagen): standaard 90. Daarna verwijdert de dagelijkse cron automatisch de WebM-bestanden en de bijbehorende regels

Capaciteit en overlay

• Maximaal aantal kijkers per presentator: standaard 25. Pas dit aan uw uploadbandbreedte aan
• Positie van de overlay: rechts, links of onderaan

Standaardwaarden per uitzending

• Chat standaard ingeschakeld
• Replay standaard ingeschakeld
• Inloggen standaard vereist

STUN en TURN: wanneer een TURN instellen

STUN is een eenvoudige server om het publieke IP-adres te ontdekken, gratis en in ongeveer 85 procent van de gevallen voldoende. TURN daarentegen relayt het mediaverkeer echt: dat kost bandbreedte, maar maakt het mogelijk twee clients te verbinden die elkaar niet rechtstreeks kunnen bereiken.

Stel een TURN in als:

• uw kijkers regelmatig melden dat ze de video niet zien (de WebRTC-verbinding blijft hangen op “connecting”);
• uw publiek veel mobiele gebruikers op 4G of 5G telt bij providers met symmetrische NAT;
• uw presentator of uw kijkers achter een strikt bedrijfs-VPN zitten.

Opname en replay

Hoe de opname werkt

De opname gebeurt volledig in de browser van de presentator, via de MediaRecorder-API:

1. Bij de start van de uitzending wordt MediaRecorder aangemaakt, met automatische herkenning van de beste beschikbare codec (VP9 boven VP8 boven H.264, opus voor audio, ongeveer 1,5 Mbps video plus 96 kbps audio).
2. Elke 5 seconden (instelbaar) wordt een WebM-chunk aangemaakt en geüpload via POST /wp-json/df-nls/v1/shows/{id}/replay/chunk.
3. De chunk wordt als WordPress-bijlage opgeslagen, met de naam dfnls-show-{id}-part-{NNNNN}.webm en met post_parent naar de uitzending.
4. De tabel wp_dfnls_replay_parts bewaart de volgorde en de duur van elke chunk.

Hoe de replay werkt

Bij het laden van de pagina in replaymodus:

1. roept de kijker GET /wp-json/df-nls/v1/shows/{id}/replay aan, die de geordende lijst met segmenten en de tijdlijn van de gebeurtenissen teruggeeft;
2. worden de segmenten na elkaar geladen via de ended-gebeurtenis van het <video>-element (de ingebouwde terugval);
3. maakt een MediaSource-variant een naadloze aaneenschakeling mogelijk als de browser dat ondersteunt;
4. wordt de afspeelpositie (de opgetelde tijd) vergeleken met de offset_ms van elke gebeurtenis; zodra dat punt wordt bereikt, voert de kijker lokaal hetzelfde gedrag uit als tijdens de uitzending (overlay tonen, flitscoupon, bericht).

Opslag en schijfruimte

Een orde van grootte: een uitzending van een uur op 1,5 Mbps video plus 96 kbps audio levert ongeveer 720 MB aan WebM-bestanden op. Met 90 dagen bewaartermijn en 4 uitzendingen per maand rekent u op ongeveer 10 GB schijfruimte voor de replays.

Integratie: shortcode, blok, directe URL

Directe publieke URL

Elke gepubliceerde uitzending krijgt automatisch een eigen URL:

https://uw-site.com/live/uw-slug/

Dat is de eenvoudigste manier: deel die link met uw publiek.

Shortcode

Om een uitzending in een bestaande pagina of een bestaand bericht op te nemen:

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

Beschikbare modi:

• auto (standaard): herkent de status van de uitzending en toont live, wachtscherm of replay;
• live: forceert de uitzendweergave (handig om te testen);
• replay: forceert de replaymodus, ook als de uitzending nog loopt.

Gutenberg-blok

Zoek in de blokeditor naar “Live Shopping”. Het blok ondersteunt de uitlijningen wide en full, en biedt in het inspectiepaneel een keuzelijst voor de uitzending en een keuzelijst voor de modus.

Eigen PHP-template

Het CPT gebruikt templates/single-live-show.php. Om dat te overschrijven, kopieert u het bestand naar uw thema onder uw-thema/df-native-live-shopping/single-live-show.php.

Meertaligheid met Polylang

De plugin meldt het CPT dfnls_live_show bij Polylang aan als vertaalbaar. Is Polylang al geïnstalleerd bij de activering:

• dan kan elke uitzending een versie in FR, EN, ES, DE, IT en andere talen hebben;
• worden de belangrijkste metagegevens (_dfnls_product_ids, _dfnls_scheduled_at, de opties van de uitzending) automatisch tussen de vertalingen gekopieerd;
• worden de 5 ingebouwde talen (FR, EN, ES, DE, IT) automatisch geladen volgens de WordPress-locale.

HPOS en compatibiliteit

De plugin verklaart officieel haar compatibiliteit met de high performance order storage van WooCommerce (HPOS), via FeaturesUtil. U kunt HPOS dus zonder risico voor de winkelwagenbrug inschakelen.

Ook compatibel met:

• WordPress Multisite (installatie per site, geen netwerkmodus);
• gedeelde hosting (o2switch, OVH, Infomaniak, PlanetHoster), want de signalering werkt met REST-polling en niet met WebSockets;
• cacheplugins (WP Rocket, WP Super Cache), want de REST-endpoints van de plugin worden automatisch uitgesloten.

Beveiliging en capabilities

De plugin voegt twee eigen capabilities toe:

• manage_dfnls_lives: uitzendingen aanmaken, bewerken en verwijderen, plus toegang tot de instellingen;
• host_dfnls_lives: toegang tot de presentatorconsole en het starten en stoppen van een uitzending.

Beide capabilities gaan standaard naar de rollen administrator en shop_manager. Om een gebruiker alleen het recht te geven om te presenteren zonder uitzendingen te kunnen aanmaken:

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

REST-nonces

Alle actieroutes (POST) zijn beveiligd met de nonce wp_rest. De kijker en de presentator krijgen hun eigen nonce bij het laden van de pagina, via wp_localize_script.

MIME-validatie bij uploads

Het uploaden van replaychunks wordt strikt gevalideerd met wp_check_filetype_and_ext, zodat alleen video/webm en video/mp4 worden aanvaard. De bestanden worden aan de serverzijde hernoemd (dfnls-show-{id}-part-{NNNNN}.webm).

Cron en onderhoud

Bij de activering worden twee WordPress-crons ingepland:

• dfnls_cleanup_expired_replays: dagelijks. Verwijdert de replays van uitzendingen die meer dan N dagen geleden zijn afgelopen (instelbare bewaartermijn). Gebruikt wp_delete_attachment(..., true) om ook het fysieke bestand te wissen.
• dfnls_cleanup_stale_signaling: elk uur. Ruimt signaleringsberichten ouder dan 24 uur op, plus sessies die meer dan 90 seconden inactief zijn.

Voor ontwikkelaars: REST API

Alle routes staan onder de namespace df-nls/v1.

Show

• GET /shows/{id}: haalt een uitzending op (status, producten, opties)
• POST /shows/{id}/join: sluit aan als kijker of presentator (body: peer_id, role)
• POST /shows/{id}/leave: verlaat netjes
• POST /shows/{id}/heartbeat: houdt de sessie open (automatisch elke 15 seconden aan kijkerszijde)
• POST /shows/{id}/start: start de uitzending (alleen de presentator)
• POST /shows/{id}/end: beëindigt de uitzending (alleen de presentator)
• GET /shows/{id}/viewers: teller van de actieve kijkers

WebRTC-signalering

• POST /signal/send: stuurt een SDP- of ICE-bericht naar een externe peer
• GET /signal/pull?peer={id}: haalt de wachtende berichten op en voert impliciet een heartbeat uit

Events

• POST /shows/{id}/event: legt een gebeurtenis vast (spotlight, bericht, coupon)
• GET /shows/{id}/events?since={id}: haalt de gebeurtenissen op vanaf een bepaald ID

Chat

• GET /shows/{id}/chat?since={id}: haalt de berichten op vanaf een bepaald ID
• POST /shows/{id}/chat: verstuurt een bericht

Winkelwagenbrug

• POST /cart/add: voegt een product toe aan de winkelwagen met bronregistratie (show_id, product_id, quantity)
• GET /cart/summary: teller en totaal van de huidige winkelwagen

Opname en replay

• POST /shows/{id}/replay/chunk: multipart-upload van een WebM-chunk
• GET /shows/{id}/replay: segmenten plus de tijdlijn met gebeurtenissen voor het afspelen

Structuur van de plugin (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 plus .pot
├── templates/                          # single-live-show.php, viewer-container.php, ...
└── src/
    ├── Plugin.php
    ├── Activator.php   Deactivator.php
    ├── PostType/       (LiveShow.php)
    ├── Database/       (Schema plus 5 Repository.php)
    ├── Admin/          (AdminPages, MetaBoxes, SettingsPage)
    ├── Api/            (RestController, SignalingController, CartController)
    ├── Recording/      (RecordingHandler)
    ├── Replay/         (ReplayHandler)
    ├── Frontend/       (Renderer, Shortcode, Block)
    └── Compat/         (PolylangCompat)

Hoofdnamespace: DataFireflyNativeLiveShopping, met een handmatige PSR-4-autoloader die in df-native-live-shopping.php wordt aangegeven.

Probleemoplossing

De kijkers zien de video niet

• Controleer of de site op HTTPS draait (verplicht voor WebRTC).
• Open de browserconsole aan kijkerszijde en zoek naar fouten als ICE failed of connection state failed.
• Stel een TURN-server in als uw publiek veel mobiele 4G-gebruikers telt.
• Controleer of de uploadbandbreedte van de presentator volstaat (test met fast.com aan presentatorzijde).

De presentatorconsole vindt de camera niet

• Controleer of de browser wel toestemming heeft gekregen (het slotje in de adresbalk).
• Controleer op macOS de systeemrechten: Systeeminstellingen → Beveiliging → Camera.
• Sluit andere programma’s die de camera gebruiken (Zoom, Teams, OBS en dergelijke).

De replaychunks worden niet geüpload

• Controleer upload_max_filesize en post_max_size in php.ini (mik op minstens 20 MB).
• Controleer zo nodig LimitRequestBody aan Apache-zijde.
• Bekijk het activiteitenlogboek van de presentatorconsole om de exacte fout te vinden.
• Controleer de rechten van de map wp-content/uploads.

De winkelwagen onthoudt de toevoegingen niet

• Controleer of geen enkele cacheplugin de endpoints /wp-json/df-nls/v1/* cachet.
• Controleer of de WooCommerce-cookies (woocommerce_cart_hash, wp_woocommerce_session_*) wel worden geplaatst.
• Controleer bij strikte HTTPS of de cookies de vlag Secure dragen.

De replays nemen te veel ruimte in

• Verkort de bewaartermijn in de instellingen (bijvoorbeeld van 90 naar 30 dagen).
• Schakel de opname uit voor uitzendingen waar die niet nodig is (het vakje “Replay toestaan” in de metabox Opties).
• Verlaag de bitrate door host.js aan te passen (variabele videoBitsPerSecond).

Verwijderen

Bij een gewone deactivering blijven de gegevens behouden en worden de crons uit de planning gehaald. Bij het volledig verwijderen van de plugin via Plugins voert uninstall.php het volgende uit:

• de 5 eigen tabellen worden verwijderd;
• alle opties dfnls_* worden verwijderd;
• de capabilities worden bij de rollen weggehaald;
• de crons worden uit de planning gehaald;
• optioneel worden de CPT’s en alle replaybijlagen verwijderd, als de optie dfnls_uninstall_delete_data vóór het verwijderen was ingeschakeld.

Support en toekomst

Technische ondersteuning is 12 maanden inbegrepen via de DataFirefly-klantomgeving. De updates van de plugin haalt u op via uw account, met een e-mailmelding bij grote versies.

Ideeën op de roadmap:

• automatisch overschakelen naar een SFU boven een bepaald aantal kijkers;
• livepeilingen (poll.open en poll.close zijn al gereserveerd in het gebeurtenissenprotocol);
• ingebouwde analyses (gemiddelde kijktijd, conversiepercentage per uitzending);
• meerdere presentatoren (twee tegelijk).