DataFirefly Native Live Shopping — Documentazione

Panoramica

DataFirefly Native Live Shopping trasforma il tuo negozio WooCommerce in una piattaforma di live shopping autonoma, senza dipendenza da servizi di terze parti tipo Bambuser o CommentSold. La diretta usa WebRTC peer-to-peer mesh dal browser dell’host verso ogni spettatore, la segnalazione passa dall’API REST di WordPress e la registrazione del replay avviene lato client tramite l’API MediaRecorder e viene poi memorizzata come allegati WordPress.

Il plugin fornisce:

• Un CPT dfnls_live_show per creare e programmare i tuoi live
• Una console host integrata nell’admin di WordPress (anteprima fotocamera, controlli, prodotti, chat)
• Un’esperienza spettatore chiavi in mano con prodotti cliccabili in sovrimpressione e chat
• Un bridge del carrello WooCommerce (aggiungere al carrello ufficiale senza abbandonare il live)
• Un replay automatico sincronizzato con gli eventi del live (spotlight, codici promo, messaggi)
• Un blocco Gutenberg dedicato e lo shortcode [dfnls_live]

Prerequisiti

• WordPress 6.3 o superiore
• WooCommerce 8.0 o superiore (compatibile HPOS)
• PHP 8.1 o superiore (testato fino a 8.3)
• HTTPS obbligatorio — getUserMedia() e getDisplayMedia() si rifiutano di funzionare su HTTP non sicuro
• Browser supportati lato spettatore: Chrome 80+, Firefox 75+, Edge 80+, Safari 14+, Opera 67+
• Un browser recente lato host con fotocamera e microfono accessibili

Installazione

1. Scarica l’archivio df-native-live-shopping.zip dal tuo account DataFirefly.
2. In WordPress, vai su Plugin → Aggiungi nuovo → Carica plugin.
3. Seleziona il file ZIP e clicca su Installa ora.
4. Una volta installato, clicca su Attiva plugin.
5. Un nuovo menu Live Shopping appare nella barra laterale dell’admin.

All’attivazione, il plugin:

• Crea 5 tabelle personalizzate (wp_dfnls_signaling, _sessions, _events, _replay_parts, _chat)
• Aggiunge le capabilities manage_dfnls_lives e host_dfnls_lives ai ruoli administrator e shop_manager
• Programma due cron: pulizia giornaliera dei replay vecchi, pulizia oraria dei messaggi di segnalazione obsoleti
• Registra le opzioni di default (server STUN di Google, ritenzione 90 giorni, 25 spettatori max, ecc.)

Primo live in 5 minuti

Il percorso più breve per lanciare il tuo primo live:

1. Menu Live Shopping → Nuovo live
2. Inserisci un titolo (es. « Vendite flash primavera »)
3. Nella metabox Prodotti, cerca e seleziona i prodotti WooCommerce che vuoi presentare (trascina e rilascia per riordinare)
4. Opzionale: in Pianificazione, definisci una data e un’ora di inizio (apparirà un conto alla rovescia lato spettatore)
5. Pubblica il live
6. Vai su Live Shopping → Console host e seleziona il tuo live
7. Clicca su Avvia diretta, autorizza l’accesso alla fotocamera e al microfono
8. Condividi l’URL pubblico del live (/live/tuo-slug/) con la tua audience

Console host

La console host è il pannello da cui animi il tuo live. È accessibile via Live Shopping → Console host. Funzionalità:

Anteprima video e controlli

• Fotocamera: alterna attivazione/disattivazione della fotocamera
• Microfono: alterna attivazione/disattivazione del microfono
• Condivisione schermo: sostituisce il flusso della fotocamera con la condivisione schermo (utile per demo)
• Avvia / Ferma: pulsanti di controllo principali del live

Mettere in evidenza i prodotti

La lista dei prodotti collegati al live appare a destra. Ogni prodotto ha un pulsante Metti in evidenza. Cliccandoci:

• Fa apparire immediatamente il prodotto in sovrimpressione da tutti gli spettatori
• Registra un evento product.spotlight con timestamp per sincronizzare il replay
• Un secondo clic sullo stesso pulsante rimuove la sovrimpressione

Diffusione codici promo

Inserisci un codice promo (es. LIVE20) e opzionalmente una descrizione, poi clicca su Diffondi. Un flash animato appare sullo schermo degli spettatori con un pulsante « Copia » per ottenere il codice con un clic.

Messaggi dell’animatore

Un campo di testo libero ti permette di inviare un messaggio che si visualizza come banner temporaneo lato spettatore (8 secondi di default).

Chat live

La chat animatore/spettatori è integrata nella console. I messaggi dell’animatore sono visivamente distinti (badge e bordo rosso) in tutte le viste.

Log delle attività

Un log in fondo alla console mostra in tempo reale le connessioni/disconnessioni, gli eventi diffusi, gli upload dei chunk replay e gli eventuali errori.

Vista spettatore

Cosa vive l’audience una volta sull’URL pubblico del live:

• Prima del live — Se il live è programmato, viene mostrata una schermata di attesa con conto alla rovescia fino all’ora prevista. Poll automatico dello stato ogni 5 secondi per rilevare l’inizio.
• Durante il live — Video in diretta con pillola « IN DIRETTA » pulsante e contatore di spettatori. Sidebar con due tab: Prodotti (lista cliccabile dei prodotti del live) e Chat.
• Sovrimpressione prodotto — Quando l’animatore mette in evidenza un prodotto, una card scivola sullo schermo (di default in basso a destra) con foto, nome, prezzo e pulsante Aggiungi al carrello.
• Aggiungi al carrello — Un clic sul pulsante aggiunge il prodotto al carrello WooCommerce ufficiale. Appare un FAB (pulsante flottante) in basso a destra con il contatore degli articoli del carrello.
• Codice promo flash — Diffuso dall’animatore, appare in alto con animazione e pulsante di copia.
• Dopo il live — Se il replay è attivato, un pulsante « Guarda il replay » permette di riprodurre il live con sincronizzazione integrale degli eventi.

Impostazioni globali

Menu Live Shopping → Impostazioni. Sezioni principali:

Server STUN

Di default, vengono usati i server STUN pubblici di Google:

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

Puoi aggiungere i tuoi server STUN (uno per riga).

Server TURN

Opzionale ma consigliato per spettatori dietro NAT simmetrico (alcuni operatori 4G, VPN aziendali). Formato:

turn:turn.esempio.com:3478
turns:turn.esempio.com:5349

Inserisci le credenziali Username TURN e Password TURN associate.

Registrazione e replay

• Registrazione attiva: sì / no globale
• Durata dei chunk (ms): 5000 di default. Più corta = più resilienza in caso di crash ma più richieste; più lunga = meno richieste ma perdita maggiore in caso di crash
• Ritenzione dei replay (giorni): 90 di default. Oltre, il cron giornaliero elimina automaticamente i file WebM e le voci associate

Capacità e sovrimpressione

• Numero massimo di spettatori per host: 25 di default. Aggiusta in base alla tua banda di upload
• Posizione della sovrimpressione: destra, sinistra o basso

Predefiniti per live

• Chat attiva per default
• Replay attivo per default
• Accesso richiesto per default

Server STUN e TURN — quando configurare un TURN

STUN è un semplice server di scoperta dell’IP pubblico, gratuito e sufficiente nel ~85 % dei casi. TURN, invece, rilancia effettivamente il traffico media: consuma banda, ma permette di connettere due client che non possono raggiungersi direttamente.

Configura un TURN se:

• I tuoi spettatori si lamentano regolarmente di non vedere il video (stato di connessione WebRTC bloccato su « connecting »)
• La tua audience contiene molti mobile 4G/5G presso operatori con NAT simmetrico (Free Mobile in Francia in particolare)
• Il tuo host o i tuoi spettatori sono dietro un VPN aziendale rigido

Registrazione e replay

Come funziona la registrazione

La registrazione avviene interamente lato browser dell’host tramite l’API MediaRecorder:

1. All’avvio del live, MediaRecorder viene istanziato con rilevamento automatico del miglior codec disponibile (VP9 > VP8 > H.264, opus per l’audio, ~1,5 Mbps video + 96 kbps audio)
2. Ogni 5 secondi (configurabile), un chunk WebM viene attivato e caricato via POST /wp-json/df-nls/v1/shows/{id}/replay/chunk
3. Il chunk viene memorizzato come allegato WordPress, nominato dfnls-show-{id}-part-{NNNNN}.webm, con post_parent che punta al live
4. La tabella wp_dfnls_replay_parts conserva l’ordine e la durata di ogni chunk

Come funziona il replay

Al caricamento della pagina in modalità replay:

1. Il viewer chiama GET /wp-json/df-nls/v1/shows/{id}/replay che restituisce la lista ordinata dei segmenti e la timeline degli eventi
2. I segmenti vengono caricati sequenzialmente tramite l’evento ended del <video> (fallback nativo)
3. Una variante MediaSource permette la concatenazione trasparente se il browser la supporta
4. La posizione di riproduzione (tempo cumulato) viene confrontata con gli offset_ms di ogni evento — quando il punto viene attraversato, il viewer scatena localmente lo stesso comportamento del live (mostrare sovrimpressione, flash codice promo, messaggio)

Archiviazione e spazio su disco

Ordine di grandezza: un live di un’ora a 1,5 Mbps di video + 96 kbps di audio produce circa 720 MB di file WebM. Con 90 giorni di ritenzione e 4 live al mese, conta ~10 GB di spazio su disco dedicato ai replay.

Integrazione: shortcode, blocco, URL diretto

URL pubblico diretto

Ogni live pubblicato possiede il proprio URL generato automaticamente:

https://tuo-sito.com/live/tuo-slug/

È il modo più semplice: condividi questo link con la tua audience.

Shortcode

Per inserire un live in una pagina o un articolo esistente:

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

Modalità disponibili:

• auto (default): rileva lo stato del live e mostra live / attesa / replay a seconda
• live: forza la visualizzazione in modalità diretta (utile per test)
• replay: forza la modalità replay anche se il live è ancora in corso

Blocco Gutenberg

Nell’editor a blocchi, cerca « Live Shopping ». Il blocco supporta gli allineamenti wide e full, espone un selettore per scegliere il live e un selettore di modalità nella barra laterale dell’ispettore.

Template PHP personalizzato

Il CPT usa templates/single-live-show.php. Per sovrascrivere, copia questo file nel tuo tema sotto tuo-tema/df-native-live-shopping/single-live-show.php.

Multilingue con Polylang

Il plugin dichiara il CPT dfnls_live_show come traducibile presso Polylang. All’attivazione, se Polylang è già installato:

• Ogni live può avere una versione FR, EN, ES, DE, IT, ecc.
• I metadati critici (_dfnls_product_ids, _dfnls_scheduled_at, opzioni del live) vengono copiati automaticamente tra le traduzioni
• Le 5 lingue integrate (FR, EN, ES, DE, IT) vengono caricate automaticamente secondo la locale di WordPress

HPOS e compatibilità

Il plugin dichiara ufficialmente la compatibilità con lo stoccaggio ad alte prestazioni degli ordini di WooCommerce (HPOS) tramite FeaturesUtil. Puoi attivare HPOS sulla tua installazione senza rischio di malfunzionamento del bridge del carrello.

Compatibile anche con:

• WordPress Multisite (installazione per sito, nessuna modalità network)
• Hosting condiviso (o2switch, OVH, Infomaniak, PlanetHoster) — la segnalazione usa polling REST, nessun WebSocket
• Plugin di cache (WP Rocket, WP Super Cache) — gli endpoint REST del plugin sono esclusi automaticamente

Sicurezza e capabilities

Il plugin aggiunge due capabilities dedicate:

• manage_dfnls_lives — creazione, modifica, eliminazione dei live; accesso alle impostazioni
• host_dfnls_lives — accesso alla console host, avvio / arresto di un live

Entrambe le capabilities sono attribuite di default ai ruoli administrator e shop_manager. Per dare a un utente unicamente il diritto di animare senza poter creare live:

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

Nonce REST

Tutte le rotte di azione (POST) sono protette da un nonce wp_rest. Il viewer e l’host ricevono il loro nonce rispettivo tramite wp_localize_script al caricamento della pagina.

Validazione MIME upload

L’upload dei chunk replay è validato rigorosamente tramite wp_check_filetype_and_ext per accettare unicamente video/webm e video/mp4. I file vengono rinominati lato server (dfnls-show-{id}-part-{NNNNN}.webm).

Cron e manutenzione

Due cron WordPress vengono programmati all’attivazione:

• dfnls_cleanup_expired_replays — giornaliero. Elimina i replay dei live terminati da più di N giorni (ritenzione configurabile). Usa wp_delete_attachment(..., true) per eliminare anche il file fisico.
• dfnls_cleanup_stale_signaling — orario. Pulisce i messaggi di segnalazione di più di 24 h e le sessioni inattive da più di 90 secondi.

Per gli sviluppatori — API REST

Tutte le rotte sono sotto il namespace df-nls/v1.

Show

• GET /shows/{id} — recupera un live (stato, prodotti, opzioni)
• POST /shows/{id}/join — si unisce come viewer o host (body: peer_id, role)
• POST /shows/{id}/leave — esce in modo pulito
• POST /shows/{id}/heartbeat — mantiene la sessione aperta (auto ogni 15 s lato viewer)
• POST /shows/{id}/start — avvia il live (host solamente)
• POST /shows/{id}/end — termina il live (host solamente)
• GET /shows/{id}/viewers — contatore degli spettatori attivi

Signaling WebRTC

• POST /signal/send — invia un messaggio SDP/ICE a un peer remoto
• GET /signal/pull?peer={id} — recupera i messaggi in attesa ed effettua un heartbeat implicito

Events

• POST /shows/{id}/event — registra un evento (spotlight, messaggio, codice promo)
• GET /shows/{id}/events?since={id} — pull degli eventi a partire da un ID dato

Chat

• GET /shows/{id}/chat?since={id} — pull dei messaggi a partire da un ID
• POST /shows/{id}/chat — invia un messaggio

Cart bridge

• POST /cart/add — aggiunge un prodotto al carrello con tracciamento della sorgente (show_id, product_id, quantity)
• GET /cart/summary — contatore e totale del carrello attuale

Recording e replay

• POST /shows/{id}/replay/chunk — upload multipart di un chunk WebM
• GET /shows/{id}/replay — segmenti + timeline events per la lettura

Struttura del 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 + .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)

Namespace radice: DataFirefly / NativeLiveShopping, autoloader manuale PSR-4 dichiarato in df-native-live-shopping.php.

Risoluzione dei problemi

Gli spettatori non vedono il video

• Verifica che il sito sia in HTTPS (obbligatorio per WebRTC)
• Apri la console del browser lato spettatore, cerca gli errori ICE failed o connection state failed
• Configura un server TURN se l’audience contiene molti mobile 4G
• Verifica che la banda di upload dell’host sia sufficiente (utilità fast.com lato host)

La console host non rileva la fotocamera

• Verifica che il browser abbia concesso l’autorizzazione (icona lucchetto nella barra degli indirizzi)
• Su macOS, verifica le autorizzazioni di sistema: Preferenze → Sicurezza → Fotocamera
• Chiudi le altre applicazioni che usano la fotocamera (Zoom, Teams, OBS…)

I chunk replay non si caricano

• Verifica upload_max_filesize e post_max_size nel php.ini (mira a 20 MB minimo)
• Verifica LimitRequestBody lato Apache se applicabile
• Guarda il log delle attività della console host per identificare l’errore esatto
• Verifica i permessi della cartella wp-content/uploads

Il carrello non conserva le aggiunte

• Verifica che nessun plugin di cache metta in cache gli endpoint /wp-json/df-nls/v1/*
• Verifica che i cookie WooCommerce (woocommerce_cart_hash, wp_woocommerce_session_*) vengano emessi correttamente
• Su HTTPS rigido, verifica che i cookie abbiano il flag Secure

I replay occupano troppo spazio

• Riduci la ritenzione (per es. da 90 a 30 giorni) nelle impostazioni
• Disattiva la registrazione per i live in cui non è necessaria (casella « Consenti replay » nella metabox Opzioni)
• Riduci il bitrate modificando host.js (variabile videoBitsPerSecond)

Disinstallazione

Alla disattivazione semplice, i dati vengono conservati e i cron vengono deprogrammati. All’eliminazione completa del plugin da Plugin, uninstall.php effettua:

• Eliminazione delle 5 tabelle personalizzate
• Eliminazione di tutte le opzioni dfnls_*
• Ritiro delle capabilities dai ruoli
• Deprogrammazione dei cron
• Opzionale: eliminazione dei CPT e di tutti gli allegati replay se l’opzione dfnls_uninstall_delete_data è stata attivata prima della disinstallazione

Supporto ed evoluzioni

Supporto tecnico incluso per 12 mesi tramite l’area cliente DataFirefly. Gli aggiornamenti del plugin sono disponibili dal tuo account, con notifica via email delle versioni maggiori.

Idee di evoluzione nella roadmap:

• Passaggio automatico a SFU oltre una soglia di spettatori
• Sondaggi live (poll.open / poll.close già riservati nel protocollo eventi)
• Analytics native (tempo medio di visione, tasso di conversione per live)
• Multi-host (due animatori simultanei)