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 del saldo de moneda virtual
  3. Concesión 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 la Conexión

Endpoint

Protocolo

El WebSocket utiliza el protocolo graphql-ws (también conocido como graphql-transport-ws). Este es el protocolo moderno GraphQL sobre WebSocket, NO el protocolo legacy 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 por 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 backoff 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 - Falló la autenticación o error irrecuperable