Assinatura GraphQL (WebSocket)

Esta página explica como conectar 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 da roda
  4. Progresso e conclusão de desafios
  5. Prêmios bônus
Todas as atualizações têm escopo de 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. Fazer upgrade da conexão HTTP para WebSocket
  2. Enviar uma mensagem connection_init com parâmetros de autenticação
  3. Aguardar connection_ack antes de se inscrever

Autenticação

A autenticação acontece durante o handshake 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

Inscrevendo-se nas Atualizações

Uma vez conectado e autenticado, inscreva-se na 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 de quando a atualização ocorreu
UserID
int
O ID do usuário a quem esta atualização pertence
Data
string
Payload codificado em JSON com detalhes da atualização

Lidando com Desconexões

Conexões WebSocket podem ser interrompidas por várias razões:
  1. Problemas de rede
  2. Reinicializações do servidor
  3. Expiração do 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 lide com transições:
  1. Conectando - Tentativa de conexão inicial
  2. Conectado - Recebeu connection_ack
  3. Inscrito - Assinatura ativa, recebendo eventos
  4. Desconectado - Conexão perdida, deve tentar reconectar
  5. Erro - Falha na autenticação ou erro irrecuperável