Pular para o conteúdo principal

Introdução

Abra uma conexão WebSocket em tempo real para receber atualizações de conteúdo, pedidos e usuários sem polling.

Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/events/introduction

🎯 O que este módulo faz?​

O módulo WS (WebSocket) permite que você receba notificações em tempo real - atualizações de conteúdo, alterações de pedidos, ações de usuários - estabelecendo conexões persistentes para obter atualizações instantâneas sem polling, permitindo recursos ao vivo como notificações, chat ao vivo e painéis em tempo real.

Pense nisso como seu sistema de notificações em tempo real - em vez de perguntar repetidamente "há algo novo?" (polling), o WebSocket mantém uma conexão aberta e o servidor envia atualizações para você instantaneamente quando os eventos ocorrem.

📖 Explicação Simples​

Toda aplicação moderna precisa de atualizações em tempo real:

  • 🔔 Notificações Ao Vivo - Alertas instantâneos quando algo acontece
  • 💬 Chat Ao Vivo - Mensagens em tempo real entre usuários
  • 📊 Painéis Ao Vivo - Estatísticas e métricas que se atualizam automaticamente
  • 🛒 Atualizações de Pedidos - Mudanças instantâneas no status do pedido
  • 📝 Atualizações de Conteúdo - Mudanças e publicações de conteúdo ao vivo
  • 👥 Atividade do Usuário - Presença e ações do usuário em tempo real
  • 🔄 Sincronização de Dados - Sincronização automática entre dispositivos

O problema com o polling (requisições repetidas):

// ❌ Bad - Polling every 5 seconds
setInterval(async () => {
  const orders = await Orders.getOrders();
  // Check if anything changed
  // Wastes bandwidth, delays updates, server load
}, 5000);

Problemas:

  • 🔋 Desgaste da bateria - Requisições constantes desperdiçam energia
  • 📡 Desperdício de rede - A maioria das requisições retorna "sem mudanças"
  • ⏱️ Atualizações atrasadas - Atraso de até 5 segundos
  • 🖥️ Carga do servidor - Requisições desnecessárias a cada poucos segundos

A solução WebSocket:

// ✅ Good - Real-time WebSocket connection
const { WS } = defineOneEntry('https://your-site.oneentry.cloud', {
  token: 'your-app-token'
});

// connect() returns a socket.io Socket (requires an authorized user)
const socket = await WS.connect();

// Listen for events with socket.on(...)
socket.on('my_event', (payload) => {
  console.log('Update received!', payload);
  // Instant notification, no polling!
});

Benefícios:

  • 🔋 Eficiente - Conexão persistente única
  • 📡 Em tempo real - Atualizações instantâneas, sem atraso
  • ⏱️ Baixa latência - Entrega de notificações em menos de um segundo
  • 🖥️ Carga reduzida - O servidor envia apenas quando necessário

✨ Conceitos Chave​

O que é WebSocket?​

WebSocket é uma conexão bidirecional persistente entre cliente e servidor:

  • Conexão Persistente - Permanece aberta, sem handshakes repetidos
  • Bidirecional - Tanto o cliente quanto o servidor podem enviar mensagens
  • Em Tempo Real - Entrega instantânea de mensagens
  • Baseado em Eventos - Escute eventos com socket.on(...)
  • Eficiente - Baixo overhead em comparação com polling HTTP

WebSocket vs Polling HTTP​

RecursoWebSocketPolling HTTP
ConexãoPersistente (permanece aberta)Conexões repetidas
LatênciaMenos de um segundoDepende do intervalo (2-30s)
EficiênciaMuito eficienteDesperdiçador (muitas respostas vazias)
Carga do ServidorBaixa (apenas eventos)Alta (requisições constantes)
Uso da BateriaBaixoAlto (dispositivos móveis)
Caso de UsoAtualizações em tempo realAceitável para atualizações não críticas

Ciclo de Vida da Conexão WebSocket​

1. Client opens a connection
   (const socket = await WS.connect())
   ↓
2. Connection established
   (socket.on('connect', ...) fires)
   ↓
3. Client listens for events
   (socket.on('my_event', callback))
   ↓
4. Server sends events when they occur
   (Instant delivery)
   ↓
5. Client receives event messages
   (Callback function executes)
   ↓
6. Connection stays open
   (No reconnection needed)
   ↓
7. Client disconnects when done
   (socket.disconnect())

Quais eventos chegam pela conexão​

Não há um catálogo fixo de nomes de eventos do SDK. Os eventos são acionados de acordo com a configuração do seu módulo de Eventos no painel de administração (o evento deve ter a opção WebSocket habilitada). Você escuta um evento pelo seu marcador com socket.on('<event_marker>', callback).

A carga útil depende da fonte do evento. Campos típicos da carga útil (veja connect() para exemplos completos):

Campo da Carga ÚtilChega paraContém
attributesTodo eventoOs próprios atributos do evento
productEventos de catálogo (produto)Atributos do produto mais title
userEventos de formulário de usuárioCampos do formulário de usuário
orderEventos de pedidosid do pedido e atributos
email / codeFormulários de registro / códigoCampos adicionais do formulário

Por que usar o módulo WebSocket?​

BenefícioDescrição
Atualizações em Tempo RealNotificações instantâneas, sem atraso de polling
EficienteConexão única, baixo overhead
Amigável à BateriaSem polling constante em dispositivos móveis
EscalávelO servidor envia apenas quando necessário
Baseado em EventosInscreva-se em eventos específicos
Recursos Ao VivoHabilite chat, notificações, painéis

📋 O que você precisa saber​

Gerenciamento de Conexão WebSocket​

As conexões WebSocket precisam ser gerenciadas com cuidado:

Melhores práticas:

  • Verifique o estado da conexão antes de se inscrever
  • Implemente lógica de reconexão
  • Trate erros de conexão de forma adequada
  • Desconecte quando o usuário sair

Gerenciamento de Inscrição de Eventos​

Inscreva-se em eventos apenas após a conexão ser estabelecida

Melhores práticas:

  • Use funções de callback nomeadas para facilitar a desinscrição
  • Inscreva-se após a conexão estar aberta
  • Desinscreva-se quando o componente for desmontado
  • Não se inscreva no mesmo evento várias vezes

Desinscrição de Eventos​

Sempre desinscreva-se quando terminar para evitar vazamentos de memória:

Melhores práticas:

  • Desinscreva-se em funções de limpeza
  • Desconecte o WebSocket quando não for mais necessário
  • Previna vazamentos de memória em SPAs

Estratégia de Reconexão​

Implemente reconexão automática com backoff exponencial:

Melhores práticas:

  • Use backoff exponencial para reconexão
  • Limite o número máximo de tentativas de reconexão
  • Redefina contadores em uma conexão bem-sucedida
  • Permita desconexão manual sem reconexão

Estrutura da Carga Útil do Evento​

As cargas úteis dos eventos seguem uma estrutura consistente:

Melhores práticas:

  • Valide a estrutura da carga útil do evento
  • Trate campos ausentes de forma adequada
  • Verifique o tipo da carga útil em TypeScript

Tratamento de Erros​

Implemente um tratamento de erros abrangente:

Melhores práticas:

  • Capture erros em manipuladores de eventos
  • Registre erros para depuração
  • Mostre mensagens de erro amigáveis ao usuário
  • Não deixe que erros travem a aplicação

Otimização de Desempenho​

Otimize o desempenho do WebSocket:

Melhores práticas:

  • Limite eventos de alta frequência
  • Agrupe várias atualizações juntas
  • Debounce atualizações de UI
  • Evite operações caras em manipuladores

💡 Notas Importantes​

⚠️ Gerenciamento do Estado da Conexão​

Sempre verifique o estado da conexão antes de se inscrever

🔄 Tratamento de Reconexão​

As conexões WebSocket podem cair inesperadamente:

  • Mudanças de rede (WiFi para celular)
  • Reinicializações do servidor
  • Timeout de inatividade

Sempre implemente lógica de reconexão

🧹 Prevenção de Vazamentos de Memória​

Desinscreva-se quando terminar para evitar vazamentos de memória

🔒 Segurança​

As conexões WebSocket são autenticadas:

  • Autenticação baseada em token (mesmo que a API REST)
  • Protocolo WebSocket Seguro (WSS)
  • Não é necessário enviar o token com cada mensagem

Melhores práticas:

  • Use WSS (WebSocket seguro) em produção
  • Não exponha dados sensíveis em manipuladores de eventos
  • Valide as cargas úteis dos eventos antes de processá-las

📱 Considerações para Dispositivos Móveis​

WebSocket em dispositivos móveis:

  • Uso da bateria (eficiente, mas conexão persistente)
  • Conexões em segundo plano podem ser encerradas
  • Mudanças de rede exigem reconexão

Melhores práticas:

  • Reconecte quando o aplicativo voltar ao primeiro plano
  • Trate mudanças no estado da rede
  • Considere polling para atualizações não críticas em dispositivos móveis

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
connect()Conectar ao servidor WebSocketEstabelecer conexão

🔐 connect() requer um usuário autorizado — autentique primeiro via AuthProvider. Após conectar, anexe manipuladores de eventos com socket.on(...).

❓ Perguntas Comuns (FAQ)​

Como me conecto ao servidor WebSocket?​

Use WS.connect() para abrir uma conexão — ele retorna um Socket do socket.io. Requer um usuário autorizado, então chame AuthProvider.auth(...) primeiro. Aguarde o evento connect antes de confiar no socket, depois anexe manipuladores com socket.on('<event_marker>', callback). A conexão é autenticada com o token de acesso do usuário mais seu token de aplicativo de defineOneEntry().

Quais eventos posso me inscrever?​

Não há uma lista fixa de eventos do SDK. Os eventos são definidos pela configuração do seu módulo de Eventos no painel de administração (com a opção WebSocket habilitada), e você escuta um evento pelo seu marcador com socket.on('<event_marker>', callback). Veja connect() para exemplos de carga útil (produto, usuário, pedido, formulário).

Como trato quedas de conexão?​

Implemente reconexão automática com backoff exponencial. Escute os eventos disconnect e connect_error do socket.io, e então tente reconectar após um atraso (por exemplo, 1s, 2s, 4s, 8s, até no máximo 30s). Redefina o contador de atraso em uma connect bem-sucedida. (o socket.io também reconecta automaticamente por padrão.)

Devo usar WebSocket ou polling para meu aplicativo?​

Use WebSocket para recursos em tempo real (chat ao vivo, notificações, painéis) onde atualizações instantâneas são importantes. Use polling para atualizações não críticas ou quando as conexões WebSocket forem problemáticas (firewalls restritivos, modo de fundo em dispositivos móveis).

Como evito vazamentos de memória com inscrições WebSocket?​

Sempre desinscreva-se de eventos quando os componentes forem desmontados ou quando a conexão não for mais necessária. No React, use funções de limpeza em useEffect. No Vue, use o hook de ciclo de vida beforeUnmount.

Posso usar WebSocket em dispositivos móveis?​

Sim, mas esteja ciente de que o sistema operacional móvel pode encerrar conexões WebSocket em segundo plano. Reconecte quando o aplicativo retornar ao primeiro plano. Considere o impacto na bateria de conexões persistentes em dispositivos móveis.

🎓 Melhores Práticas​

  • Verifique o estado da conexão - Inscreva-se apenas após a conexão ser aberta
  • Implemente reconexão - Reconexão automática em caso de desconexão com backoff exponencial
  • Desinscreva-se na limpeza - Desanexe manipuladores (socket.off) e socket.disconnect() para evitar vazamentos de memória em SPAs
  • Trate erros de forma adequada - Capture erros em manipuladores de eventos
  • Limite eventos de alta frequência - Evite sobrecarregar a UI com atualizações
  • Valide cargas úteis de eventos - Verifique a estrutura dos dados antes de processá-los
  • Use callbacks nomeados - Mais fácil de desinscrever e depurar
  • Registre o estado da conexão - Acompanhe eventos de abertura/fechamento/erro para depuração

Definição do módulo WS​

Você pode se inscrever em eventos via WebSocket para receber notificações


const { WS } = defineOneEntry(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

🔗 Documentação Relacionada​