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 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]

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

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

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 <video> (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.

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

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.

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

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)