# DataFirefly Native Live Shopping — Documentation
> Vue d'ensemble DataFirefly Native Live Shopping transforme votre boutique WooCommerce en plateforme de live shopping autonome, sans dépendance à un service tiers type Bambuser ou CommentSold. La diffusion utilise du…
- Page:
- Langue: fr
- Mis à jour le: 2026-07-01
- Autres langues: [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), [it](https://www.datafirefly.com/it/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)
- Index:
## Vue d'ensemble
DataFirefly Native Live Shopping transforme votre boutique WooCommerce en plateforme de live shopping autonome, sans dépendance à un service tiers type Bambuser ou CommentSold. La diffusion utilise du **WebRTC peer-to-peer mesh** depuis le navigateur de l'hôte vers chaque spectateur, la signalisation passe par l'API REST WordPress, et l'enregistrement du replay est réalisé côté client via l'API MediaRecorder puis stocké en tant que pièces jointes WordPress.
Le plugin fournit :
- Un CPT `dfnls_live_show` pour créer et planifier vos lives
- Une console hôte intégrée à l'admin WordPress (preview caméra, contrôles, produits, chat)
- Une expérience spectateur clé en main avec produits cliquables en surimpression et chat
- Un bridge panier WooCommerce (ajout au panier officiel sans quitter le live)
- Un replay automatique synchronisé avec les événements du live (spotlights, coupons, messages)
- Un bloc Gutenberg dédié et le shortcode `[dfnls_live]`
**Architecture** — La topologie WebRTC mesh est idéale jusqu'à ~25 spectateurs simultanés par hôte. Au-delà, prévoir un serveur TURN externe ou envisager un SFU. La bande passante montante de l'hôte doit être d'environ 500 kbps par spectateur connecté.
## Prérequis
- **WordPress** 6.3 ou supérieur
- **WooCommerce** 8.0 ou supérieur (compatible HPOS)
- **PHP** 8.1 ou supérieur (testé jusqu'à 8.3)
- **HTTPS obligatoire** — `getUserMedia()` et `getDisplayMedia()` refusent de fonctionner sur du HTTP non sécurisé
- Navigateurs supportés côté spectateur : Chrome 80+, Firefox 75+, Edge 80+, Safari 14+, Opera 67+
- Un navigateur récent côté hôte avec caméra et micro accessibles
**Important** — Sans HTTPS valide (Let's Encrypt suffit), la console hôte ne pourra pas accéder à la caméra ni au micro. Testez sur `localhost` ou sur un domaine avec certificat TLS.
## Installation
1. Téléchargez l'archive `df-native-live-shopping.zip` depuis votre compte DataFirefly.
2. Dans WordPress, allez sur _Extensions → Ajouter_ → _Téléverser une extension_.
3. Sélectionnez le fichier ZIP puis cliquez sur _Installer maintenant_.
4. Une fois installé, cliquez sur _Activer l'extension_.
5. Un nouveau menu **Live Shopping** apparaît dans la barre latérale de l'admin.
À l'activation, le plugin :
- Crée 5 tables custom (`wp_dfnls_signaling`, `_sessions`, `_events`, `_replay_parts`, `_chat`)
- Ajoute les capabilities `manage_dfnls_lives` et `host_dfnls_lives` aux rôles `administrator` et `shop_manager`
- Planifie deux crons : purge quotidienne des replays anciens, purge horaire des messages de signalisation obsolètes
- Enregistre les options par défaut (serveurs STUN de Google, rétention 90 jours, 25 viewers max, etc.)
## Premier live en 5 minutes
Le parcours le plus court pour lancer votre premier live :
1. Menu **Live Shopping → Nouveau live**
2. Renseignez un titre (ex. « Ventes flash printemps »)
3. Dans la metabox _Produits_, recherchez et sélectionnez les produits WooCommerce que vous voulez présenter (glisser-déposer pour réordonner)
4. Optionnel : dans _Planification_, définissez une date et une heure de démarrage (un compte à rebours s'affichera côté spectateur)
5. Publiez le live
6. Allez dans **Live Shopping → Console hôte** et sélectionnez votre live
7. Cliquez sur _Démarrer la diffusion_, autorisez l'accès à la caméra et au micro
8. Partagez l'URL publique du live (`/live/votre-slug/`) avec votre audience
## Console hôte
La console hôte est le tableau de bord depuis lequel vous animez votre live. Elle est accessible via _Live Shopping → Console hôte_. Fonctionnalités :
### Preview vidéo et contrôles
- **Caméra** : bascule d'activation/désactivation de la caméra
- **Micro** : bascule d'activation/désactivation du micro
- **Partage d'écran** : remplace le flux caméra par un partage d'écran (utile pour démos)
- **Démarrer / Arrêter** : boutons de contrôle principal du live
### Mise en avant produits
La liste des produits liés au live s'affiche à droite. Chaque produit a un bouton _Mettre en avant_. Cliquer dessus :
- Fait apparaître immédiatement le produit en surimpression chez tous les spectateurs
- Enregistre un événement `product.spotlight` horodaté pour synchronisation replay
- Un second clic sur le même bouton retire la surimpression
### Diffusion de coupons
Saisissez un code promo (ex. `LIVE20`) et éventuellement une description, puis cliquez sur _Diffuser_. Un flash animé apparaît à l'écran des spectateurs avec un bouton « Copier » pour récupérer le code d'un clic.
### Messages animateur
Un champ de saisie libre permet d'envoyer un message qui s'affiche en bannière temporaire côté spectateur (8 secondes par défaut).
### Chat live
Le chat animateur/spectateurs est intégré à la console. Les messages de l'animateur sont visuellement distingués (badge et bordure rouge) sur toutes les vues.
### Journal d'activité
Un log en bas de la console affiche en temps réel les connexions/déconnexions, les événements diffusés, les uploads de chunks replay, et les éventuelles erreurs.
## Vue spectateur
Ce que vit l'audience une fois sur l'URL publique du live :
- **Avant le live** — Si le live est planifié, affichage d'un écran d'attente avec compte à rebours jusqu'à l'heure prévue. Poll automatique du statut toutes les 5 secondes pour détecter le démarrage.
- **Pendant le live** — Vidéo en direct avec pastille « EN DIRECT » pulsante et compteur de spectateurs. Sidebar avec deux onglets : _Produits_ (liste cliquable des produits du live) et _Chat_.
- **Surimpression produit** — Lorsque l'animateur met un produit en avant, une carte glisse à l'écran (par défaut en bas à droite) avec photo, nom, prix et bouton _Ajouter au panier_.
- **Ajout au panier** — Un clic sur le bouton ajoute le produit au panier WooCommerce officiel. Un FAB (bouton flottant) apparaît en bas à droite avec le compteur d'articles au panier.
- **Coupon flash** — Diffusé par l'animateur, s'affiche en haut avec animation et bouton copie.
- **Après le live** — Si le replay est activé, un bouton « Regarder le replay » permet de rejouer le live avec synchronisation intégrale des événements.
## Réglages globaux
Menu **Live Shopping → Réglages**. Sections principales :
### Serveurs STUN
Par défaut, les serveurs STUN publics de Google sont utilisés :
```
stun:stun.l.google.com:19302
stun:stun1.l.google.com:19302
```
Vous pouvez ajouter vos propres serveurs STUN (un par ligne).
### Serveurs TURN
Optionnel mais recommandé pour les spectateurs derrière NAT symétrique (certains opérateurs 4G, VPN d'entreprise). Format :
```
turn:turn.exemple.com:3478
turns:turn.exemple.com:5349
```
Renseignez les identifiants _TURN username_ et _TURN credential_ associés.
### Enregistrement et replay
- **Enregistrement activé** : oui / non global
- **Durée des chunks** (ms) : 5000 par défaut. Plus court = plus de résilience au crash mais plus de requêtes ; plus long = moins de requêtes mais perte plus importante en cas de crash
- **Rétention des replays** (jours) : 90 par défaut. Au-delà, le cron quotidien supprime automatiquement les fichiers WebM et les entrées associées
### Capacité et surimpression
- **Nombre max de spectateurs par hôte** : 25 par défaut. Ajustez selon votre bande passante montante
- **Position de la surimpression** : droite, gauche ou bas
### Défauts par live
- Chat activé par défaut
- Replay activé par défaut
- Connexion requise par défaut
## Serveurs STUN et TURN — quand configurer un TURN
STUN est un simple serveur de découverte d'IP publique, gratuit et suffisant dans ~85 % des cas. TURN, en revanche, relaie effectivement le trafic média : il consomme de la bande passante, mais permet de connecter deux clients qui ne peuvent pas se joindre en direct.
Configurez un TURN si :
- Vos spectateurs se plaignent régulièrement de ne pas voir la vidéo (état de connexion WebRTC bloqué en « connecting »)
- Votre audience contient beaucoup de mobiles sous 4G/5G chez des opérateurs à NAT symétrique (Free Mobile en France notamment)
- Votre hôte ou vos spectateurs sont derrière un VPN d'entreprise strict
**Solution recommandée** — Déployer un [coturn](https://github.com/coturn/coturn) auto-hébergé sur un petit VPS (5 à 10 € / mois) suffit pour 30-40 spectateurs simultanés. Alternative payante : Xirsys, Twilio Network Traversal Service.
## Enregistrement et replay
### Comment fonctionne l'enregistrement
L'enregistrement se fait entièrement **côté navigateur de l'hôte** via l'API MediaRecorder :
1. Au démarrage du live, MediaRecorder est instancié avec détection automatique du meilleur codec disponible (VP9 > VP8 > H.264, opus pour l'audio, ~1,5 Mbps vidéo + 96 kbps audio)
2. Toutes les 5 secondes (configurable), un chunk WebM est déclenché et uploadé via `POST /wp-json/df-nls/v1/shows/{id}/replay/chunk`
3. Le chunk est stocké comme pièce jointe WordPress, nommée `dfnls-show-{id}-part-{NNNNN}.webm`, avec `post_parent` pointant vers le live
4. La table `wp_dfnls_replay_parts` conserve l'ordre et la durée de chaque chunk
### Comment fonctionne le replay
Au chargement de la page en mode replay :
1. Le viewer appelle `GET /wp-json/df-nls/v1/shows/{id}/replay` qui retourne la liste ordonnée des segments et la timeline des événements
2. Les segments sont chargés séquentiellement via l'événement `ended` du `` (fallback natif)
3. Une variante MediaSource permet la concaténation transparente si le navigateur le supporte
4. La position de lecture (temps cumulé) est comparée aux `offset_ms` de chaque événement — quand le point est franchi, le viewer déclenche localement le même comportement qu'en live (afficher la surimpression, flash coupon, message)
### Stockage et espace disque
Ordre de grandeur : un live d'une heure à 1,5 Mbps vidéo + 96 kbps audio produit environ **720 Mo** de fichiers WebM. Avec 90 jours de rétention et 4 lives par mois, comptez ~10 Go d'espace disque dédié aux replays.
**MIME et upload** — Le plugin ajoute un filtre `upload_mimes` pour autoriser `video/webm` et `video/mp4` depuis la médiathèque. Vérifiez que votre serveur n'a pas de règle `LimitRequestBody` ou `upload_max_filesize` trop stricte (viser 20 Mo minimum par chunk).
## Intégration : shortcode, bloc, URL directe
### URL publique directe
Chaque live publié possède sa propre URL générée automatiquement :
```
https://votre-site.com/live/votre-slug/
```
C'est la manière la plus simple : partagez ce lien avec votre audience.
### Shortcode
Pour insérer un live dans une page ou un article existant :
```
[dfnls_live id="42"]
[dfnls_live id="42" mode="live"]
[dfnls_live id="42" mode="replay"]
[dfnls_live id="42" mode="auto"]
```
Modes disponibles :
- `auto` (défaut) : détecte le statut du live et affiche live / attente / replay selon
- `live` : force l'affichage en mode diffusion (utile pour des tests)
- `replay` : force le mode replay même si le live est encore en cours
### Bloc Gutenberg
Dans l'éditeur de blocs, cherchez _« Live Shopping »_. Le bloc supporte les alignements `wide` et `full`, expose un sélecteur pour choisir le live et un sélecteur de mode dans la barre latérale de l'inspecteur.
### Template PHP personnalisé
Le CPT utilise `templates/single-live-show.php`. Pour surcharger, copiez ce fichier dans votre thème sous `votre-theme/df-native-live-shopping/single-live-show.php`.
## Multilingue avec Polylang
Le plugin déclare le CPT `dfnls_live_show` comme traduisible auprès de Polylang. À l'activation, si Polylang est déjà installé :
- Chaque live peut avoir une version FR, EN, ES, DE, IT, etc.
- Les métadonnées critiques (`_dfnls_product_ids`, `_dfnls_scheduled_at`, options de live) sont copiées automatiquement entre traductions
- Les 5 langues intégrées (FR, EN, ES, DE, IT) sont chargées automatiquement selon la locale WordPress
**Astuce Polylang Pro** — Si vous utilisez Polylang Pro et que vos produits WooCommerce sont eux-mêmes traduits, chaque traduction du live doit être associée à la version linguistique correspondante des produits. Le plugin ne fait pas de mapping automatique inter-langues sur les IDs produits.
## HPOS et compatibilités
Le plugin déclare officiellement sa compatibilité avec le stockage haute performance des commandes de WooCommerce (HPOS) via `FeaturesUtil`. Vous pouvez activer HPOS sur votre installation sans risque de dysfonctionnement du bridge panier.
Compatible également avec :
- WordPress Multisite (installation par site, pas de mode réseau)
- Hébergement mutualisé (o2switch, OVH, Infomaniak, PlanetHoster) — la signalisation utilise le polling REST, pas de WebSocket
- Plugins de cache (WP Rocket, WP Super Cache) — les endpoints REST du plugin sont exclus automatiquement
## Sécurité et capabilities
Le plugin ajoute deux capabilities dédiées :
- `manage_dfnls_lives` — création, édition, suppression des lives ; accès aux réglages
- `host_dfnls_lives` — accès à la console hôte, démarrage / arrêt d'un live
Les deux capabilities sont attribuées par défaut aux rôles `administrator` et `shop_manager`. Pour donner à un utilisateur uniquement le droit d'animer sans pouvoir créer de lives :
```
$user = get_user_by('login', 'animateur');
$user->add_cap('host_dfnls_lives');
```
### Nonces REST
Toutes les routes d'action (POST) sont protégées par nonce `wp_rest`. Le viewer et l'host reçoivent leur nonce respectif via `wp_localize_script` au chargement de la page.
### Validation MIME uploads
L'upload de chunks replay est strictement validé via `wp_check_filetype_and_ext` pour n'accepter que `video/webm` et `video/mp4`. Les fichiers sont renommés côté serveur (`dfnls-show-{id}-part-{NNNNN}.webm`).
## Cron et maintenance
Deux crons WordPress sont planifiés à l'activation :
- `dfnls_cleanup_expired_replays` — **quotidien**. Supprime les replays des lives terminés depuis plus de N jours (rétention configurable). Utilise `wp_delete_attachment(..., true)` pour supprimer aussi le fichier physique.
- `dfnls_cleanup_stale_signaling` — **horaire**. Purge les messages de signalisation de plus de 24h et les sessions inactives de plus de 90 secondes.
**WP-Cron désactivé** — Si vous avez désactivé WP-Cron au profit d'un cron système, assurez-vous d'appeler `wp-cron.php` au moins une fois par heure pour que les purges s'exécutent.
## Pour les développeurs — API REST
Toutes les routes sont sous le namespace `df-nls/v1`.
### Show
- `GET /shows/{id}` — récupère un live (statut, produits, options)
- `POST /shows/{id}/join` — rejoint comme viewer ou host (body : `peer_id`, `role`)
- `POST /shows/{id}/leave` — quitte proprement
- `POST /shows/{id}/heartbeat` — maintient la session ouverte (auto toutes les 15s côté viewer)
- `POST /shows/{id}/start` — démarre le live (host uniquement)
- `POST /shows/{id}/end` — termine le live (host uniquement)
- `GET /shows/{id}/viewers` — compteur de spectateurs actifs
### Signaling WebRTC
- `POST /signal/send` — envoie un message SDP/ICE à un peer distant
- `GET /signal/pull?peer={id}` — récupère les messages en attente et effectue un heartbeat implicite
### Events
- `POST /shows/{id}/event` — enregistre un événement (spotlight, message, coupon)
- `GET /shows/{id}/events?since={id}` — pull des événements depuis un ID donné
### Chat
- `GET /shows/{id}/chat?since={id}` — pull des messages depuis un ID
- `POST /shows/{id}/chat` — envoie un message
### Cart bridge
- `POST /cart/add` — ajoute un produit au panier avec traçage source (`show_id`, `product_id`, `quantity`)
- `GET /cart/summary` — compteur et total du panier courant
### Recording et replay
- `POST /shows/{id}/replay/chunk` — upload multipart d'un chunk WebM
- `GET /shows/{id}/replay` — segments + timeline events pour lecture
## Structure du 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 racine : `DataFireflyNativeLiveShopping`, autoloader manuel PSR-4 déclaré dans `df-native-live-shopping.php`.
## Dépannage
### Les spectateurs ne voient pas la vidéo
- Vérifier que le site est en HTTPS (obligatoire pour WebRTC)
- Ouvrir la console du navigateur côté spectateur, chercher les erreurs `ICE failed` ou `connection state failed`
- Configurer un serveur TURN si l'audience contient beaucoup de mobiles 4G
- Vérifier que la bande passante montante de l'hôte est suffisante (utilitaire fast.com côté hôte)
### La console hôte ne détecte pas la caméra
- Vérifier que le navigateur a bien accordé l'autorisation (icône cadenas dans la barre d'URL)
- Sur macOS, vérifier les permissions système : _Préférences → Sécurité → Caméra_
- Fermer les autres applications utilisant la caméra (Zoom, Teams, OBS...)
### Les chunks replay ne s'uploadent pas
- Vérifier `upload_max_filesize` et `post_max_size` dans php.ini (viser 20 Mo minimum)
- Vérifier `LimitRequestBody` côté Apache si applicable
- Regarder le journal d'activité de la console hôte pour identifier l'erreur exacte
- Vérifier les permissions du dossier `wp-content/uploads`
### Le panier ne conserve pas les ajouts
- Vérifier qu'aucun plugin de cache ne met en cache les endpoints `/wp-json/df-nls/v1/*`
- Vérifier que les cookies WooCommerce (`woocommerce_cart_hash`, `wp_woocommerce_session_*`) sont bien émis
- Sur HTTPS strict, vérifier que les cookies ont bien le flag `Secure`
### Les replays occupent trop d'espace
- Réduire la rétention (par ex. de 90 à 30 jours) dans les réglages
- Désactiver l'enregistrement pour les lives où ce n'est pas nécessaire (case « Autoriser le replay » dans la metabox _Options_)
- Réduire le bitrate en modifiant `host.js` (variable `videoBitsPerSecond`)
## Désinstallation
À la désactivation simple, les données sont conservées et les crons désinscrits. À la **suppression complète** du plugin depuis _Extensions_, `uninstall.php` effectue :
- Suppression des 5 tables custom
- Suppression de toutes les options `dfnls_*`
- Retrait des capabilities des rôles
- Désinscription des crons
- Optionnel : suppression des CPT et de toutes les pièces jointes replay si l'option `dfnls_uninstall_delete_data` a été activée avant désinstallation
**Attention** — Par défaut, les lives et leurs replays ne sont PAS supprimés à la désinstallation. Pour tout supprimer, activez l'option _Supprimer toutes les données à la désinstallation_ dans les réglages avant de désinstaller.
## Support et évolutions
Support technique inclus pendant 12 mois via l'espace client DataFirefly. Les mises à jour du plugin sont disponibles depuis votre compte, avec notification par email des versions majeures.
Idées d'évolution sur la roadmap :
- Basculement SFU automatique au-delà d'un seuil de spectateurs
- Sondages live (poll.open / poll.close déjà réservés dans le protocole d'événements)
- Analytics natives (temps moyen de visionnage, taux de conversion par live)
- Multi-hôtes (deux animateurs simultanés)