Pular para o conteúdo principal

Introdução

🎯 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, mudanças 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 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 de status de pedidos instantâneas
  • 📝 Atualizações de Conteúdo - Mudanças e publicações de conteúdo ao vivo
  • 👥 Atividade do Usuário - Presença e ações de usuários em tempo real
  • 🔄 Sincronização de Dados - Sincronização automática entre dispositivos

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

// ❌ Ruim - Polling a cada 5 segundos
setInterval(async () => {
  const orders = await Orders.getOrders();
  // Verifica se algo mudou
  // Desperdiça largura de banda, atrasa atualizações, carga no servidor
}, 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 no servidor - Requisições desnecessárias a cada poucos segundos

A solução WebSocket:

// ✅ Bom - Conexão WebSocket em tempo real
const { WS } = defineOneEntry('https://your-site.oneentry.cloud', {
  token: 'your-app-token'
});

// Inscreva-se em eventos
WS.subscribe('order.created', (order) => {
  console.log('Novo pedido recebido!', order);
  // Notificação instantânea, sem polling!
});

WS.subscribe('content.updated', (content) => {
  console.log('Conteúdo atualizado!', content);
  // Atualize a interface imediatamente
});

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 - Inscreva-se em eventos específicos
  • Eficiente - Baixo overhead em comparação com polling HTTP

WebSocket vs HTTP Polling​

RecursoWebSocketHTTP Polling
ConexãoPersistente (permanece aberta)Conexões repetidas
LatênciaMenos de um segundoDepende do intervalo (2-30s)
EficiênciaMuito eficienteDesperdiçador (muitas respostas vazias)
Carga no 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. O cliente se conecta ao servidor WebSocket
   (WS.connect())
   ↓
2. Conexão estabelecida
   (evento onOpen é acionado)
   ↓
3. O cliente se inscreve em eventos
   (WS.subscribe('event.name', callback))
   ↓
4. O servidor envia eventos quando ocorrem
   (Entrega instantânea)
   ↓
5. O cliente recebe mensagens de eventos
   (A função de callback é executada)
   ↓
6. A conexão permanece aberta
   (Sem necessidade de reconexão)
   ↓
7. O cliente se desconecta quando terminar
   (WS.disconnect())

Eventos Comuns do WebSocket​

Tipo de EventoDescriçãoCaso de Uso Exemplo
order.createdNovo pedido realizadoMostrar notificação "Novo Pedido!"
order.updatedStatus do pedido alteradoAtualizar status do pedido na interface
content.publishedNovo conteúdo publicadoAtualizar lista de conteúdo
content.updatedConteúdo editadoAtualizar conteúdo exibido
user.registeredNovo usuário cadastradoMostrar novo usuário no painel administrativo
payment.completedPagamento processadoAtualizar status do pedido para "Pago"
product.outOfStockProduto fora de estoqueMostrar badge "Fora de Estoque"

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

🚀 Exemplo Rápido​

📋 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 em 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 caso de conexão bem-sucedida
  • Permita desconexão manual sem reconexão

Estrutura do Payload de Evento​

Os payloads de eventos seguem uma estrutura consistente:

Melhores práticas:

  • Valide a estrutura do payload do evento
  • Trate campos ausentes de forma adequada
  • Verifique o tipo do payload 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 a frequência de eventos de alta frequência
  • Agrupe várias atualizações juntas
  • Debounce atualizações da interface
  • 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
  • Tempo limite 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 (mesma do REST API)
  • 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 os payloads de eventos antes de processá-los

📱 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

❓ Perguntas Comuns (FAQ)​

Como me conecto ao servidor WebSocket?​

Use WS.connect() para estabelecer uma conexão. Aguarde a conexão ser aberta (escute o evento onOpen) antes de se inscrever em eventos. A conexão é autenticada usando seu token de aplicativo de defineOneEntry().

Quais eventos posso me inscrever?​

Inscreva-se em eventos como order.created, order.updated, content.published, payment.completed, user.registered, etc. Os eventos disponíveis dependem da sua configuração do OneEntry e da configuração do módulo Events no painel administrativo.

Como trato quedas de conexão?​

Implemente reconexão automática com backoff exponencial. Escute os eventos onClose e onError, 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 caso de conexão bem-sucedida.

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 em 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 - Previna 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 interface com atualizações
  • Valide payloads de eventos - Verifique a estrutura dos dados antes de processá-los
  • Use callbacks nomeados - Facilita a desinscrição e depuração
  • Registre o estado da conexão - Acompanhe eventos de abertura/fechamento/erro para depuração

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

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​