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, mudanças de pedidos, ações de usuários - através de uma conexão persistente, de modo que o servidor envie atualizações para você instantaneamente em vez de você fazer polling por elas. Isso possibilita recursos ao vivo, como notificações, chat ao vivo e painéis em tempo real.

O único método, connect(), abre a conexão e retorna um Socket do socket.io. É síncrono e requer um usuário autorizado, então autentique primeiro.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


const { WS } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

connect() é síncrono e retorna um Socket do socket.io (sem await). Anexe manipuladores de eventos com socket.on(...):

// connect() requires an authorized user — authenticate first via AuthProvider.
const socket = WS.connect();

socket.on('connect', () => {
  console.log('WebSocket connected');
});

// Listen for an event by its marker (configured in the Events module).
socket.on('my_event', (payload) => {
  console.log('Update received!', payload);
});

✨ 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ênciaSub-segundoDepende do intervalo (2-30s)
EficiênciaMuito eficienteDesperdiçador (muitas respostas vazias)
Carga do ServidorBaixa (apenas eventos)Alta (requisições constantes)
Caso de UsoAtualizações em tempo realAceitável para atualizações não críticas

Ciclo de Vida da Conexão​

1. Authenticate the user (AuthProvider.auth)
   ↓
2. Open the connection: const socket = WS.connect()
   ↓
3. Wait for the 'connect' event: socket.on('connect', ...)
   ↓
4. Listen for events: socket.on('<event_marker>', callback)
   ↓
5. Server pushes events as they occur
   ↓
6. Disconnect 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 do 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

📋 O que você precisa saber​

Autorização é necessária​

connect() requer um usuário autorizado — chame AuthProvider.auth(...) antes de conectar. A conexão é autenticada com o token de acesso do usuário mais seu token de aplicativo de defineOneEntry(). Se nenhum usuário estiver autorizado, o SDK registra um erro.

connect() é síncrono​

connect() retorna um Socket do socket.io imediatamente — não faça await nele. Aguarde o evento connect antes de confiar no socket, então anexe manipuladores com socket.on(...).

socket.io é carregado sob demanda​

socket.io-client (~41 kB) é importado a primeira vez que connect() é chamado, então projetos que nunca abrem um socket não o incluem — veja Tamanho do Pacote & Formatos de Módulo.

A assinatura não muda e o uso normal não é afetado: até que o chunk seja resolvido, o objeto retornado enfileira tudo o que você faz com ele (on, emit, disconnect) e o reproduz no socket real no mesmo tick em que é criado — antes que a conexão possa entregar qualquer coisa — então nenhum evento é perdido. Ler o estado cedo também é preciso: um socket recém-criado não está conectado, então id é undefined e connected é false.

A única diferença: um método que precisa retornar um valor (por exemplo, listeners()) não pode responder antes que o chunk chegue, e objetos aninhados como socket.io só são acessíveis uma vez que ele é carregado.

Inscreva-se após a conexão abrir, limpe quando terminar​

Anexe manipuladores de eventos após o evento connect ser acionado, e desanexe-os (socket.off) além de chamar socket.disconnect() quando a conexão não for mais necessária (por exemplo, na desmontagem do componente ou logout do usuário) para evitar vazamentos de memória em SPAs.

Reconexão​

O socket.io reconecta automaticamente por padrão. Para personalizar, escute os eventos disconnect e connect_error e reconecte com backoff exponencial, redefinindo o atraso em uma connect bem-sucedida.

📊 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 — é síncrono e 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, então anexe manipuladores com socket.on('<event_marker>', callback).

A 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 lido com quedas de conexão?​

O socket.io reconecta automaticamente por padrão. Para personalizar, escute os eventos disconnect e connect_error e reconecte com backoff exponencial (por exemplo, 1s, 2s, 4s, 8s, até um máximo), redefinindo o contador de atraso em uma connect bem-sucedida.

Como evito vazamentos de memória com assinaturas WebSocket?​

Desanexe manipuladores de eventos (socket.off) e chame socket.disconnect() quando os componentes forem desmontados ou a conexão não for mais necessária. No React, faça isso na limpeza do useEffect; no Vue, no beforeUnmount.

🎓 Melhores Práticas​

  • Autentique primeiro - connect() requer um usuário autorizado.
  • Não aguarde connect() - É síncrono e retorna um Socket.
  • Inscreva-se após a conexão abrir - Anexe manipuladores após o evento connect ser acionado.
  • Limpe - Desanexe manipuladores (socket.off) e socket.disconnect() para evitar vazamentos de memória em SPAs.
  • Lide com a reconexão - o socket.io reconecta automaticamente; personalize com disconnect / connect_error e backoff se necessário.
  • Valide as cargas úteis dos eventos - A forma da carga útil depende da fonte do evento; verifique os campos antes de usá-los.

🔗 Documentação Relacionada​