Subscrição GraphQL (WebSocket)

Esta página explica como conectar-se ao WebSocket da API GraphQL de Recompensas para atualizações em tempo real

A API GraphQL de Recompensas fornece uma única assinatura WebSocket (StatusUpdate) que entrega notificações em tempo real para:
  1. Mudanças de XP e nível
  2. Atualizações de saldo de moeda virtual
  3. Concessões e uso de tokens de roda
  4. Progresso e conclusão de desafios
  5. Prêmios bônus
Todas as atualizações são definidas pelo escopo do usuário e requerem autenticação.

Configuração da Conexão

Endpoint

Protocolo

O WebSocket usa o protocolo graphql-ws (também conhecido como graphql-transport-ws). Este é o protocolo moderno GraphQL sobre WebSocket, NÃO o protocolo legado subscriptions-transport-ws.
Ao estabelecer a conexão, o cliente deve:
  1. Atualizar a conexão HTTP para WebSocket
  2. Enviar uma mensagem connection_init com parâmetros de autenticação
  3. Aguardar connection_ack antes de assinar

Autenticação

A autenticação acontece durante o handshake do WebSocket via connectionParams (enviado na mensagem connection_init).
Parâmetros obrigatórios:
ParâmetroTipoDescrição
connection_id
string
Obrigatório. Um identificador único para esta conexão (ex.: UUID). Usado para rastrear múltiplas conexões por usuário.
Authorization
string
Recomendado. Token JWT Bearer (ex.: Bearer eyJhbGci...).
Você deve fornecer Authorization. O cabeçalho Authorization com um JWT é o método preferido.
Requisitos do Token JWT:
  1. Deve ser um JWT válido assinado com o segredo configurado (RSA ou HMAC)
  2. Deve conter claims de identidade do usuário
  3. A expiração do token é validada

Parâmetros de Conexão

Assinando Atualizações

Uma vez conectado e autenticado, assine a assinatura StatusUpdate:
Assinatura GraphQL:
Formato de Resposta:
CampoTipoDescrição
Type
string
O tipo de atualização (veja Tipos de Evento)
Timestamp
string
Timestamp ISO 8601 quando a atualização ocorreu
UserID
int
O ID do usuário ao qual esta atualização pertence
Data
string
Payload codificado em JSON com detalhes da atualização

Lidando com Desconexões

As conexões WebSocket podem ser interrompidas por várias razões:
  1. Problemas de rede
  2. Reinicializações do servidor
  3. Expiração de token
  4. Timeout por inatividade

Estratégia de Reconexão Recomendada

Implemente backoff exponencial com jitter:

Gerenciamento de Estado da Conexão

Rastreie estados de conexão e trate transições:
  1. Conectando - Tentativa de conexão inicial
  2. Conectado - Recebido connection_ack
  3. Assinado - Assinatura ativa, recebendo eventos
  4. Desconectado - Conexão perdida, deve tentar reconectar
  5. Erro - Falha de autenticação ou erro irrecuperável