DataFirefly Native Live Shopping: documentação

Visão de conjunto

O DataFirefly Native Live Shopping transforma a sua loja WooCommerce numa plataforma de live shopping autónoma, sem depender de um serviço de terceiros como a Bambuser ou a CommentSold. A difusão usa WebRTC ponto a ponto em mesh a partir do navegador do anfitrião para cada espetador, a sinalização passa pela API REST do WordPress, e a gravação do replay é feita do lado do cliente através da API MediaRecorder e guardada como anexos do WordPress.

O plugin fornece:

• Um CPT dfnls_live_show para criar e agendar as suas transmissões
• Uma consola de anfitrião integrada na administração do WordPress (pré-visualização de câmara, controlos, produtos, chat)
• Uma experiência de espetador pronta a usar, com produtos clicáveis em sobreposição e chat
• Uma ponte para o carrinho do WooCommerce (adição ao carrinho oficial sem sair da transmissão)
• Um replay automático sincronizado com os eventos da transmissão (destaques, cupões, mensagens)
• Um bloco Gutenberg dedicado e o shortcode [dfnls_live]

Requisitos

• WordPress 6.3 ou superior
• WooCommerce 8.0 ou superior (compatível com HPOS)
• PHP 8.1 ou superior (testado até à 8.3)
• HTTPS obrigatório: o getUserMedia() e o getDisplayMedia() recusam funcionar em HTTP não seguro
• Navegadores suportados do lado do espetador: Chrome 80+, Firefox 75+, Edge 80+, Safari 14+, Opera 67+
• Um navegador recente do lado do anfitrião, com câmara e microfone acessíveis

Instalação

1. Descarregue o arquivo df-native-live-shopping.zip a partir da sua conta DataFirefly.
2. No WordPress, vá a Plugins → Adicionar → Carregar plugin.
3. Selecione o ficheiro ZIP e clique em Instalar agora.
4. Terminada a instalação, clique em Ativar plugin.
5. Aparece um novo menu Live Shopping na barra lateral da administração.

Na ativação, o plugin:

• Cria 5 tabelas personalizadas (wp_dfnls_signaling, _sessions, _events, _replay_parts, _chat)
• Acrescenta as permissões manage_dfnls_lives e host_dfnls_lives aos perfis administrator e shop_manager
• Agenda dois crons: limpeza diária dos replays antigos e limpeza horária das mensagens de sinalização obsoletas
• Regista as opções predefinidas (servidores STUN da Google, retenção de 90 dias, máximo de 25 espetadores, etc.)

Primeira transmissão em 5 minutos

O percurso mais curto para lançar a sua primeira transmissão:

1. Menu Live Shopping → Nova transmissão
2. Indique um título (por exemplo «Vendas relâmpago de primavera»)
3. Na metabox Produtos, pesquise e selecione os produtos WooCommerce que quer apresentar (arrastar e largar para reordenar)
4. Opcional: em Agendamento, defina uma data e hora de início (aparece uma contagem decrescente do lado do espetador)
5. Publique a transmissão
6. Vá a Live Shopping → Consola de anfitrião e selecione a sua transmissão
7. Clique em Iniciar a difusão e autorize o acesso à câmara e ao microfone
8. Partilhe o URL público da transmissão (/live/o-seu-slug/) com o seu público

Consola de anfitrião

A consola de anfitrião é o painel a partir do qual anima a sua transmissão. Está acessível em Live Shopping → Consola de anfitrião. Funcionalidades:

Pré-visualização de vídeo e controlos

• Câmara: interruptor de ativação e desativação da câmara
• Microfone: interruptor de ativação e desativação do microfone
• Partilha de ecrã: substitui o fluxo da câmara por uma partilha de ecrã (útil para demonstrações)
• Iniciar / Parar: botões de controlo principal da transmissão

Destaque de produtos

A lista dos produtos ligados à transmissão aparece à direita. Cada produto tem um botão Destacar. Clicar nele:

• Faz aparecer de imediato o produto em sobreposição em todos os espetadores
• Regista um evento product.spotlight com data e hora para a sincronização do replay
• Um segundo clique no mesmo botão retira a sobreposição

Difusão de cupões

Introduza um código promocional (por exemplo LIVE20) e, se quiser, uma descrição, e clique em Difundir. Aparece um destaque animado no ecrã dos espetadores, com um botão «Copiar» para obter o código num clique.

Mensagens do apresentador

Um campo de texto livre permite enviar uma mensagem que aparece numa faixa temporária do lado do espetador (8 segundos por predefinição).

Chat em direto

O chat entre apresentador e espetadores está integrado na consola. As mensagens do apresentador são visualmente distintas (distintivo e contorno vermelho) em todas as vistas.

Registo de atividade

Um registo no fundo da consola mostra em tempo real as ligações e desligações, os eventos difundidos, os carregamentos de blocos de replay e os eventuais erros.

Vista do espetador

O que o público vive assim que chega ao URL público da transmissão:

• Antes da transmissão: se estiver agendada, aparece um ecrã de espera com contagem decrescente até à hora prevista. Consulta automática do estado a cada 5 segundos para detetar o arranque.
• Durante a transmissão: vídeo em direto com pastilha «EM DIRETO» a pulsar e contador de espetadores. Barra lateral com dois separadores: Produtos (lista clicável dos produtos da transmissão) e Chat.
• Sobreposição de produto: quando o apresentador destaca um produto, desliza um cartão no ecrã (por predefinição em baixo à direita) com fotografia, nome, preço e botão Adicionar ao carrinho.
• Adição ao carrinho: um clique no botão acrescenta o produto ao carrinho oficial do WooCommerce. Aparece um botão flutuante em baixo à direita com o contador de artigos no carrinho.
• Cupão relâmpago: difundido pelo apresentador, aparece no topo com animação e botão de copiar.
• Depois da transmissão: se o replay estiver ativo, um botão «Ver o replay» permite rever a transmissão com sincronização integral dos eventos.

Definições globais

Menu Live Shopping → Definições. Secções principais:

Servidores STUN

Por predefinição, são usados os servidores STUN públicos da Google:

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

Pode acrescentar os seus próprios servidores STUN (um por linha).

Servidores TURN

Opcional, mas recomendado para os espetadores por trás de NAT simétrico (alguns operadores 4G, VPN de empresa). Formato:

turn:turn.exemplo.com:3478
turns:turn.exemplo.com:5349

Indique as credenciais TURN username e TURN credential associadas.

Gravação e replay

• Gravação ativa: sim / não, global
• Duração dos blocos (ms): 5000 por predefinição. Mais curto = mais resiliência a falhas mas mais pedidos; mais longo = menos pedidos mas maior perda em caso de falha
• Retenção dos replays (dias): 90 por predefinição. Acima disso, o cron diário elimina automaticamente os ficheiros WebM e as entradas associadas

Capacidade e sobreposição

• Número máximo de espetadores por anfitrião: 25 por predefinição. Ajuste conforme a sua largura de banda de envio
• Posição da sobreposição: direita, esquerda ou baixo

Predefinições por transmissão

• Chat ativo por predefinição
• Replay ativo por predefinição
• Sessão iniciada exigida por predefinição

Servidores STUN e TURN: quando configurar um TURN

O STUN é um simples servidor de descoberta de IP público, gratuito e suficiente em cerca de 85% dos casos. O TURN, pelo contrário, retransmite efetivamente o tráfego de média: consome largura de banda, mas permite ligar dois clientes que não conseguem chegar um ao outro diretamente.

Configure um TURN se:

• Os seus espetadores se queixarem regularmente de não ver o vídeo (estado da ligação WebRTC bloqueado em «connecting»)
• O seu público tiver muitos telemóveis em 4G/5G em operadores com NAT simétrico
• O seu anfitrião ou os seus espetadores estiverem por trás de uma VPN de empresa estrita

Gravação e replay

Como funciona a gravação

A gravação é feita inteiramente no navegador do anfitrião, através da API MediaRecorder:

1. No arranque da transmissão, o MediaRecorder é instanciado com deteção automática do melhor codec disponível (VP9 > VP8 > H.264, opus para o áudio, cerca de 1,5 Mbps de vídeo mais 96 kbps de áudio)
2. A cada 5 segundos (configurável), é produzido um bloco WebM e carregado através de POST /wp-json/df-nls/v1/shows/{id}/replay/chunk
3. O bloco é guardado como anexo do WordPress, com o nome dfnls-show-{id}-part-{NNNNN}.webm e post_parent a apontar para a transmissão
4. A tabela wp_dfnls_replay_parts conserva a ordem e a duração de cada bloco

Como funciona o replay

No carregamento da página em modo replay:

1. O visualizador chama GET /wp-json/df-nls/v1/shows/{id}/replay, que devolve a lista ordenada dos segmentos e a linha temporal dos eventos
2. Os segmentos são carregados sequencialmente através do evento ended do <video> (recurso nativo)
3. Uma variante MediaSource permite a concatenação transparente se o navegador a suportar
4. A posição de leitura (tempo acumulado) é comparada com o offset_ms de cada evento; quando o ponto é ultrapassado, o visualizador desencadeia localmente o mesmo comportamento que em direto (apresentar a sobreposição, destaque do cupão, mensagem)

Armazenamento e espaço em disco

Ordem de grandeza: uma transmissão de uma hora a 1,5 Mbps de vídeo mais 96 kbps de áudio produz cerca de 720 MB de ficheiros WebM. Com 90 dias de retenção e 4 transmissões por mês, conte com cerca de 10 GB de espaço em disco dedicado aos replays.

Integração: shortcode, bloco, URL direto

URL público direto

Cada transmissão publicada tem o seu próprio URL gerado automaticamente:

https://o-seu-site.com/live/o-seu-slug/

É a forma mais simples: partilhe esta ligação com o seu público.

Shortcode

Para inserir uma transmissão numa página ou num artigo existente:

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

Modos disponíveis:

• auto (predefinido): deteta o estado da transmissão e apresenta direto / espera / replay conforme o caso
• live: força a apresentação em modo difusão (útil para testes)
• replay: força o modo replay mesmo que a transmissão ainda esteja em curso

Bloco Gutenberg

No editor de blocos, procure «Live Shopping». O bloco suporta os alinhamentos wide e full, e expõe um seletor para escolher a transmissão e um seletor de modo na barra lateral do inspetor.

Template PHP personalizado

O CPT usa o templates/single-live-show.php. Para o substituir, copie este ficheiro para o seu tema em o-seu-tema/df-native-live-shopping/single-live-show.php.

Multilingue com Polylang

O plugin declara o CPT dfnls_live_show como traduzível junto do Polylang. Na ativação, se o Polylang já estiver instalado:

• Cada transmissão pode ter uma versão FR, EN, ES, DE, IT, etc.
• Os metadados críticos (_dfnls_product_ids, _dfnls_scheduled_at, opções da transmissão) são copiados automaticamente entre traduções
• Os 5 idiomas integrados (FR, EN, ES, DE, IT) são carregados automaticamente conforme a locale do WordPress

HPOS e compatibilidades

O plugin declara oficialmente a sua compatibilidade com o armazenamento de encomendas de alto desempenho do WooCommerce (HPOS) através do FeaturesUtil. Pode ativar o HPOS na sua instalação sem risco de avaria na ponte para o carrinho.

É também compatível com:

• WordPress Multisite (instalação por site, sem modo de rede)
• Alojamento partilhado: a sinalização usa polling REST, sem WebSocket
• Plugins de cache (WP Rocket, WP Super Cache): os endpoints REST do plugin são excluídos automaticamente

Segurança e permissões

O plugin acrescenta duas permissões dedicadas:

• manage_dfnls_lives: criação, edição e eliminação de transmissões; acesso às definições
• host_dfnls_lives: acesso à consola de anfitrião, início e fim de uma transmissão

As duas permissões são atribuídas por predefinição aos perfis administrator e shop_manager. Para dar a um utilizador apenas o direito de animar sem poder criar transmissões:

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

Nonces REST

Todas as rotas de ação (POST) estão protegidas por nonce wp_rest. O visualizador e o anfitrião recebem o respetivo nonce através do wp_localize_script no carregamento da página.

Validação MIME dos carregamentos

O carregamento de blocos de replay é validado de forma estrita através do wp_check_filetype_and_ext, para aceitar apenas video/webm e video/mp4. Os ficheiros são renomeados no servidor (dfnls-show-{id}-part-{NNNNN}.webm).

Cron e manutenção

São agendados dois crons do WordPress na ativação:

• dfnls_cleanup_expired_replays: diário. Elimina os replays das transmissões terminadas há mais de N dias (retenção configurável). Usa o wp_delete_attachment(..., true) para eliminar também o ficheiro físico.
• dfnls_cleanup_stale_signaling: horário. Limpa as mensagens de sinalização com mais de 24 h e as sessões inativas há mais de 90 segundos.

Para programadores: API REST

Todas as rotas estão no namespace df-nls/v1.

Show

• GET /shows/{id}: obtém uma transmissão (estado, produtos, opções)
• POST /shows/{id}/join: entra como espetador ou anfitrião (corpo: peer_id, role)
• POST /shows/{id}/leave: sai de forma limpa
• POST /shows/{id}/heartbeat: mantém a sessão aberta (automático a cada 15 s do lado do espetador)
• POST /shows/{id}/start: inicia a transmissão (apenas anfitrião)
• POST /shows/{id}/end: termina a transmissão (apenas anfitrião)
• GET /shows/{id}/viewers: contador de espetadores ativos

Sinalização WebRTC

• POST /signal/send: envia uma mensagem SDP/ICE a um peer remoto
• GET /signal/pull?peer={id}: obtém as mensagens pendentes e faz um heartbeat implícito

Eventos

• POST /shows/{id}/event: regista um evento (destaque, mensagem, cupão)
• GET /shows/{id}/events?since={id}: obtém os eventos a partir de um ID dado

Chat

• GET /shows/{id}/chat?since={id}: obtém as mensagens a partir de um ID
• POST /shows/{id}/chat: envia uma mensagem

Ponte para o carrinho

• POST /cart/add: acrescenta um produto ao carrinho com rastreio da origem (show_id, product_id, quantity)
• GET /cart/summary: contador e total do carrinho atual

Gravação e replay

• POST /shows/{id}/replay/chunk: carregamento multipart de um bloco WebM
• GET /shows/{id}/replay: segmentos e linha temporal de eventos para leitura

Estrutura do 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 raiz: DataFireflyNativeLiveShopping, autoloader manual PSR-4 declarado em df-native-live-shopping.php.

Resolução de problemas

Os espetadores não veem o vídeo

• Verificar que o site está em HTTPS (obrigatório para WebRTC)
• Abrir a consola do navegador do lado do espetador e procurar os erros ICE failed ou connection state failed
• Configurar um servidor TURN se o público tiver muitos telemóveis em 4G
• Verificar que a largura de banda de envio do anfitrião é suficiente (utilitário fast.com do lado do anfitrião)

A consola de anfitrião não deteta a câmara

• Verificar que o navegador concedeu mesmo a autorização (ícone do cadeado na barra de URL)
• Em macOS, verificar as permissões do sistema: Preferências → Segurança → Câmara
• Fechar as outras aplicações que usam a câmara (Zoom, Teams, OBS…)

Os blocos de replay não são carregados

• Verificar o upload_max_filesize e o post_max_size no php.ini (visar 20 MB no mínimo)
• Verificar o LimitRequestBody do lado do Apache, se aplicável
• Consultar o registo de atividade da consola de anfitrião para identificar o erro exato
• Verificar as permissões da pasta wp-content/uploads

O carrinho não conserva as adições

• Verificar que nenhum plugin de cache coloca em cache os endpoints /wp-json/df-nls/v1/*
• Verificar que os cookies do WooCommerce (woocommerce_cart_hash, wp_woocommerce_session_*) são mesmo emitidos
• Em HTTPS estrito, verificar que os cookies têm mesmo a flag Secure

Os replays ocupam demasiado espaço

• Reduzir a retenção (por exemplo, de 90 para 30 dias) nas definições
• Desativar a gravação nas transmissões em que não é necessária (caixa «Permitir o replay» na metabox Opções)
• Reduzir o bitrate alterando o host.js (variável videoBitsPerSecond)

Desinstalação

Na simples desativação, os dados são conservados e os crons desagendados. Na remoção completa do plugin a partir de Plugins, o uninstall.php executa:

• Eliminação das 5 tabelas personalizadas
• Eliminação de todas as opções dfnls_*
• Remoção das permissões dos perfis
• Desagendamento dos crons
• Opcional: eliminação dos CPT e de todos os anexos de replay, se a opção dfnls_uninstall_delete_data tiver sido ativada antes da desinstalação

Suporte e evoluções

Suporte técnico incluído durante 12 meses através da área de cliente DataFirefly. As atualizações do plugin estão disponíveis a partir da sua conta, com notificação por e-mail das versões principais.

Ideias de evolução no roadmap:

• Passagem automática para SFU acima de um limiar de espetadores
• Sondagens em direto (poll.open / poll.close já reservados no protocolo de eventos)
• Análises nativas (tempo médio de visualização, taxa de conversão por transmissão)
• Vários anfitriões (dois apresentadores em simultâneo)