# 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…
- Pagina:
- Lingua: it
- Aggiornato il: 2026-07-01
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfnativeliveshopping/index.md), [en](https://www.datafirefly.com/en/documentation/dfnativeliveshopping/index.md), [es](https://www.datafirefly.com/es/documentation/dfnativeliveshopping/index.md), [de](https://www.datafirefly.com/de/documentation/dfnativeliveshopping/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfnativeliveshopping/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfnativeliveshopping/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfnativeliveshopping/index.md)
- Indice:
## 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]`
**Architettura** — La topologia WebRTC mesh è ideale fino a ~25 spettatori simultanei per host. Oltre, prevedi un server TURN esterno o considera un SFU. La banda di upload dell'host dovrebbe essere di circa 500 kbps per spettatore connesso.
## 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
**Importante** — Senza un certificato HTTPS valido (Let's Encrypt basta), la console host non potrà accedere alla fotocamera né al microfono. Testa su `localhost` o su un dominio con certificato TLS.
## 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
**Soluzione consigliata** — Distribuire un [coturn](https://github.com/coturn/coturn) auto-ospitato su un piccolo VPS (5-10 € / mese) basta per 30-40 spettatori simultanei. Alternativa a pagamento: Xirsys, Twilio Network Traversal Service.
## 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 `` (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.
**MIME e upload** — Il plugin aggiunge un filtro `upload_mimes` per autorizzare `video/webm` e `video/mp4` dalla libreria multimediale. Verifica che il tuo server non abbia regole `LimitRequestBody` o `upload_max_filesize` troppo rigide (mira a 20 MB minimo per chunk).
## 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
**Suggerimento Polylang Pro** — Se usi Polylang Pro e i tuoi prodotti WooCommerce sono a loro volta tradotti, ogni traduzione del live deve essere associata alla versione linguistica corrispondente dei prodotti. Il plugin non effettua un mapping automatico tra lingue sugli ID prodotti.
## 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.
**WP-Cron disattivato** — Se hai disattivato WP-Cron in favore di un cron di sistema, assicurati di chiamare `wp-cron.php` almeno una volta all'ora affinché le pulizie si eseguano.
## 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
**Attenzione** — Di default, i live e i loro replay NON vengono eliminati alla disinstallazione. Per eliminare tutto, attiva l'opzione _Elimina tutti i dati alla disinstallazione_ nelle impostazioni prima di disinstallare.
## 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)