Suscripci贸n GraphQL (WebSocket)

Esta p谩gina explica c贸mo conectarse al WebSocket de la API GraphQL de Recompensas para actualizaciones en tiempo real

La API GraphQL de Recompensas proporciona una 煤nica suscripci贸n WebSocket (StatusUpdate) que entrega notificaciones en tiempo real para:
  1. Cambios de XP y nivel
  2. Actualizaciones de saldo de moneda virtual
  3. Concesiones y uso de tokens de ruleta
  4. Progreso y finalizaci贸n de desaf铆os
  5. Premios de bonificaci贸n
Todas las actualizaciones est谩n limitadas al usuario y requieren autenticaci贸n.

Configuraci贸n de Conexi贸n

Endpoint

Protocolo

El WebSocket utiliza el protocolo graphql-ws (tambi茅n conocido como graphql-transport-ws). Este es el protocolo moderno de GraphQL sobre WebSocket, NO el protocolo heredado subscriptions-transport-ws.
Al establecer la conexi贸n, el cliente debe:
  1. Actualizar la conexi贸n HTTP a WebSocket
  2. Enviar un mensaje connection_init con par谩metros de autenticaci贸n
  3. Esperar connection_ack antes de suscribirse

Autenticaci贸n

La autenticaci贸n ocurre durante el handshake del WebSocket a trav茅s de los connectionParams (enviados en el mensaje connection_init).
Par谩metros requeridos:
Par谩metroTipoDescripci贸n
connection_id
string
Requerido. Un identificador 煤nico para esta conexi贸n (ej., UUID). Usado para rastrear m煤ltiples conexiones por usuario.
Authorization
string
Recomendado. Token JWT Bearer (ej., Bearer eyJhbGci...).
Debes proporcionar Authorization. El header Authorization con un JWT es el m茅todo preferido.
Requisitos del Token JWT:
  1. Debe ser un JWT v谩lido firmado con el secreto configurado (RSA o HMAC)
  2. Debe contener claims de identidad del usuario
  3. Se valida la expiraci贸n del token

Par谩metros de Conexi贸n

Suscribirse a Actualizaciones

Una vez conectado y autenticado, suscr铆bete a la suscripci贸n StatusUpdate:
Suscripci贸n GraphQL:
Formato de Respuesta:
CampoTipoDescripci贸n
Type
string
El tipo de actualizaci贸n (ver Tipos de Evento)
Timestamp
string
Timestamp ISO 8601 cuando ocurri贸 la actualizaci贸n
UserID
int
El ID de usuario al que pertenece esta actualizaci贸n
Data
string
Payload codificado en JSON con detalles de la actualizaci贸n

Manejo de Desconexiones

Las conexiones WebSocket pueden interrumpirse por varias razones:
  1. Problemas de red
  2. Reinicios del servidor
  3. Expiraci贸n del token
  4. Timeout por inactividad

Estrategia de Reconexi贸n Recomendada

Implementa retroceso exponencial con jitter:

Gesti贸n del Estado de Conexi贸n

Rastrea los estados de conexi贸n y maneja las transiciones:
  1. Conectando - Intento de conexi贸n inicial
  2. Conectado - Se recibi贸 connection_ack
  3. Suscrito - Suscripci贸n activa, recibiendo eventos
  4. Desconectado - Conexi贸n perdida, deber铆a intentar reconectar
  5. Error - Autenticaci贸n fall贸 o error irrecuperable