Módulo de Torneos

El módulo de Torneos proporciona funcionalidad para interactuar con el sistema de Torneos de Gamanza Engage. Permite a los desarrolladores recuperar torneos activos, historial de torneos, tablas de clasificación y optar a los jugadores en los torneos.

Acceso al Módulo

El módulo de Torneos se puede acceder a través del SDK del Cliente Web de Gamanza Engage:

const sdk = GamanzaEngageWebClientSDK.getInstance();
const tournaments = sdk.Tournaments;

Métodos

getPlayerActiveTournaments

Devuelve la lista de torneos activos y elegibles para el jugador autenticado actual.

Firma:

getPlayerActiveTournaments(): Promise<TournamentType[]>

Devuelve

Tipo	Descripción
`Promise<TournamentType[]>`	Una promesa que se resuelve en una matriz de torneos activos

Ejemplo

const activeTournaments = await sdk.Tournaments.getPlayerActiveTournaments();

getLeaderboardForTournament

Devuelve la tabla de clasificación para el ID de torneo dado. La respuesta siempre incluye al jugador autenticado actual como parte de la respuesta.

Para torneos activos: la tabla de clasificación siempre devuelve las primeras 25 posiciones, y si el jugador no está entre las primeras 25 se agrega al final.
Para torneos finalizados: la tabla de clasificación puede recibir el número de elementos a devolver con un máximo de 100 elementos.

Firma:

getLeaderboardForTournament(tournamentId: string, items = 25): Promise<PlayerLeaderboard[]>

Parámetros

Nombre	Tipo	Descripción
tournamentId	string	El identificador único del torneo
items	number	El número de posiciones de la tabla de clasificación a devolver (predeterminado: 25, máximo: 100)

Devuelve

Tipo	Descripción
`Promise<PlayerLeaderboard[]>`	Una promesa que se resuelve en una matriz de posiciones de la tabla de clasificación de jugadores

Ejemplo

const leaderboard = await sdk.Tournaments.getLeaderboardForTournament("tournament-id-123", 50);

getLeaderboardForTournamentWithParticipantCount

Devuelve la tabla de clasificación para el ID de torneo dado, incluido el recuento total de participantes. La respuesta siempre incluye al jugador autenticado actual como parte de la respuesta.

Para torneos activos: la tabla de clasificación siempre devuelve las primeras 25 posiciones, y si el jugador no está entre las primeras 25 se agrega al final.
Para torneos finalizados: la tabla de clasificación puede recibir el número de elementos a devolver con un máximo de 100 elementos.

Firma:

getLeaderboardForTournamentWithParticipantCount(tournamentId: string, items = 25): Promise<LeaderboardWithParticipantCount>

Parámetros

Nombre	Tipo	Descripción
tournamentId	string	El identificador único del torneo
items	number	La cantidad de posiciones en el marcador a devolver (predeterminado: 25, máximo: 100)

Devuelve

Tipo	Descripción
`Promise<LeaderboardWithParticipantCount>`	Una promesa que se resuelve con los datos del marcador y el recuento total de participantes

Ejemplo

const { playerLeaderboard, participantCount } = await sdk.Tournaments.getLeaderboardForTournamentWithParticipantCount("tournament-id-123", 50);

getPlayerPositionInLeaderboardTournament

Devuelve la posición y el puntaje actuales para el ID de torneo dado para el jugador autenticado.

Nota: Este método está obsoleto. Esta información se propaga en tiempo real suscribiéndose al método subscribeForTournamentPositionChange o al evento EVENTS.TOURNAMENTS.ON_TOURNAMENT_PLAYER_LEADERBOARD_UPDATED. Alternativamente, puede usar Tournaments.getLeaderboardForTournament y filtrar por el playerId autenticado actual en la respuesta.

Firma:

getPlayerPositionInLeaderboardTournament(tournamentId: string): Promise<{
  position: number;
  score: number;
} | null>

Parámetros

Nombre	Tipo	Descripción
tournamentId	string	El identificador único del torneo

Devuelve

Tipo	Descripción
`Promise<{ position: number; score: number; } \| null>`	Una promesa que se resuelve con la posición y el puntaje del jugador, o null si no se encuentra

Ejemplo

const position = await sdk.Tournaments.getPlayerPositionInLeaderboardTournament("tournament-id-123");
if (position) {
  console.log(`Posición actual: ${position.position}, Puntuación: ${position.score}`);
}

subscribeForTournamentPositionChange

Se suscribe a los cambios de posición en tiempo real del marcador para el torneo especificado.

Firma:

subscribeForTournamentPositionChange(
  tournamentId: string,
  callback: (positionInfo: LeaderboardPositionsChangedData) => void | Promise<void>,
  options?: SubscriptionOptions,
): () => void

Parámetros

Nombre	Tipo	Descripción
identificadorDelTorneo	cadena	El identificador único del torneo
función de devolución de llamada	función	Una función de devolución de llamada que recibe un objeto `LeaderboardPositionsChangedData` cuando se produce un cambio.
opciones	`SubscriptionOptions`	Configuración opcional para la suscripción (p. ej., `once`, `filter`).

Devuelve

Tipo	Descripción
() => void	Una función de cancelación de suscripción. Llámala para dejar de recibir actualizaciones.

Ejemplo

const unsubscribe = sdk.Tournaments.subscribeForTournamentPositionChange(
  'tournament-abc-123',
  (positionInfo) => {
    console.log(`La posición cambió en el torneo ${positionInfo.tournamentId}`);
    
    if (currentPlayerTournamentLeaderboard.position > positionInfo.position) {
      // Actualiza el tablero de clasificación para reflejar los últimos puestos
      sdk.Tournaments.getLeaderboardForTournament(positionInfo.tournamentId);
    }
  },
);

// Más tarde, cuando ya no necesites la suscripción:
unsubscribe();

getPlayerTournamentsHistory

Devuelve el historial reciente de participación en torneos del jugador autenticado actual. El historial se basa en los últimos 30 días de forma predeterminada. Si necesitas cambiar esta configuración, comunícate con tu Gerente de Éxito del Cliente y solicita ajustar la configuración Tournaments.HISTORY_DAYS_COUNT.

Firma:

getPlayerTournamentsHistory(): Promise<TournamentType[]>

Devuelve

Tipo	Descripción
`Promise<TournamentType[]>`	Una promesa que se resuelve en una matriz de entradas del historial de torneos

Ejemplo

const tournamentHistory = await sdk.Tournaments.getPlayerTournamentsHistory();

playerOptInTournament

Inscribe al jugador autenticado actualmente en un torneo específico. Usa esto solo cuando el torneo tiene optIn: true. Si optIn es false, los jugadores participan automáticamente y no se requiere esta llamada.

Torneos gratuitos (BuyInOptions.FREE)
- Comportamiento: el jugador comienza a contribuir de inmediato después de la inscripción exitosa
- Costo: Ninguno
- Respuesta: { ok: true, data: null }
Torneos con compra de fichas (BuyInOptions.TOKENS)
- Comportamiento: Valida el saldo de la moneda virtual del jugador y deduce la cuota de inscripción con éxito
- Requisito: El jugador debe tener suficientes monedas/fichas
- Errores: Devuelve faultCode = 402 (Pago requerido) cuando el saldo es insuficiente

En caso de éxito, el SDK borra las memorias caché relacionadas con torneos (torneos activos, historial) y las memorias caché de recompensas para que las lecturas posteriores reflejen el estado actualizado.

Firma:

playerOptInTournament(tournamentId: string): Promise<SimpleResponse<null>>

Parámetros

Nombre	Tipo	Descripción
tournamentId	cadena	El identificador único del torneo (de getPlayerActiveTournaments)

Retorna

Tipo	Descripción
`Promise<SimpleResponse<null>>`	Se resuelve con `{ ok: true, data: null }` en caso de éxito o `{ ok: false, data: null, error }` en caso de fallo

Manejo de errores

Fondos insuficientes (compra de fichas de torneo): error.details.faultCode === 402
Otros posibles errores: torneo no encontrado, ya comenzó/terminó, ya se inscribió, capacidad máxima alcanzada

const res = await sdk.Tournaments.playerOptInTournament(tournamentId);
if (!res.ok) {
  switch (res.error?.details?.faultCode) {
    case 402:
      // Fondos insuficientes para la inscripción al torneo
      break;
    default:
      // Manejar otros errores
      break;
  }
}

Ejemplos

Básico (torneo gratuito):

const response = await sdk.Tournaments.playerOptInTournament("tournament-id-123");
if (response.ok) {
  console.log("Se inscribió al torneo con éxito");
}

Con pre-verificación de compra de fichas:

const tournaments = await sdk.Tournaments.getPlayerActiveTournaments();
const t = tournaments.find(x => x._id === "tournament-456");

if (t?.buyOptions?.tokens) {
  const balance = await sdk.Player.getPlayerVirtualCurrencyBalance();
  if (balance.coins < t.buyOptions.tokens) {
    // Solicitar al usuario que compre más fichas
  }
}

const res2 = await sdk.Tournaments.playerOptInTournament("tournament-456");
if (!res2.ok && res2.error?.details?.faultCode === 402) {
  // Mostrar interfaz de fondos insuficientes
}

Eventos relacionados

EVENTS.TOURNAMENTS.ON_TOURNAMENT_STARTS — El torneo ha comenzado
EVENTS.TOURNAMENTS.ON_TOURNAMENT_PLAYER_LEADERBOARD_UPDATED — Posición del jugador actualizada
EVENTS.TOURNAMENTS.ON_TOURNAMENT_ENDS — El torneo ha finalizado
EVENTS.TOURNAMENTS.ON_TOURNAMENT_PLAYER_REWARDS — El jugador recibió recompensas

getPlayerLeaderboardsPositionInfo

Recupera la información de posición del tablero de clasificación del jugador autenticado para múltiples torneos. Esto devuelve la propia posición, puntuación y giros restantes (si corresponde) del jugador para cada torneo solicitado.

Específico del jugador: solo los datos del jugador autenticado
Operación por lotes: hasta 5 torneos por llamada
Truncamiento automático: si se proporcionan más de 5 ID, solo se procesan los primeros 5

Firma:

getPlayerLeaderboardsPositionInfo(tournamentIds: string[]): Promise<PositionInfo[]>

Parámetros

Nombre	Tipo	Descripción
tournamentIds	string[]	Array de identificadores de torneo para consultar. Solo se procesarán los primeros 5.

Devuelve

Tipo	Descripción
`Promise<PositionInfo[]>`	Una promesa que se resuelve en una matriz con la información de posición del jugador por torneo.

Estructura de datos: PositionInfo

Cada elemento PositionInfo describe las estadísticas actuales del torneo del jugador:

tournamentId (cadena): el identificador único del torneo
position (cadena): Posición del jugador en el tablero de clasificación (por ejemplo, "1", "25", "150")
score (cadena): Puntaje acumulado del jugador en el torneo (por ejemplo, "5000", "125000")
spinsLeft (cadena): Giros/intentos restantes disponibles (por ejemplo, "10", "0")

Consulta también la referencia de la interfaz en la sección Interfaces relacionadas a continuación.

Ejemplos

Uso básico (un solo torneo):

const [info] = await sdk.Tournaments.getPlayerLeaderboardsPositionInfo(["tournament-abc-123"]);
if (info) {
  console.log(`#${info.position} • puntaje: ${info.score} • giros restantes: ${info.spinsLeft}`);
}

Varios torneos (hasta 5):

const ids = ["t1", "t2", "t3", "t4", "t5"];
const myPositions = await sdk.Tournaments.getPlayerLeaderboardsPositionInfo(ids);

Truncamiento automático (más de 5 proporcionados):

const manyIds = ["t1", "t2", "t3", "t4", "t5", "t6", "t7"];
const positions = await sdk.Tournaments.getPlayerLeaderboardsPositionInfo(manyIds);
// Solo procesa y devuelve datos para t1..t5; t6 y t7 se ignoran.

Eventos relacionados

EVENTS.TOURNAMENTS.ON_TOURNAMENT_PLAYER_LEADERBOARD_UPDATED — Suscríbete para recibir actualizaciones en tiempo real de la posición del jugador sin sondear
subscribeForTournamentPositionChange — Método para suscribirse a los cambios de posición en un torneo específico

Interfaces relacionadas

LeaderboardPositionsChangedData

Datos recibidos cuando la posición de un jugador en el tablero de clasificación de un torneo cambia.

interface LeaderboardPositionsChangedData {
  tournamentId: string;
  position: number;
  /**
   * Indica si el jugador requiere sincronizar el tablero de clasificación en la interfaz de usuario utilizando uno de los siguientes métodos
   * en el SDK `getLeaderboardForTournament` o `getLeaderboardForTournamentWithParticipantCount`.
   * Si este valor es verdadero, es posible que las otras propiedades estén vacías.
   */
  requireSync: boolean;
  timestamp: number;
}

SubscriptionOptions

Opciones para controlar el comportamiento de la suscripción.

interface SubscriptionOptions {
  once?: boolean;
  timeout?: number;
  filter?: (data: any) => boolean;
  maxRetries?: number;
  autoAck?: boolean;
}

TournamentType

Representa un torneo en el sistema.

interface TournamentType {
  _id?: string;
  internalDetails: {} & Pick<TranslationType, 'name' | 'description'>;
  externalDetails: ExternalDetailsEntity[];
  /**
   * Se requiere incorporación manual (verdadero) o participación automática (falso).
   */
  optIn: boolean;
  /**
   * Indica si el jugador actual ya se ha incorporado.
   */
  isPlayerOptIn: boolean;
  /**
   * Tipo de compra para el torneo.
   * Si optIn = false, siempre será BuyInOptions.FREE.
   */
  buyIn: BuyInOptions; // FREE | TOKENS
  /**
   * Detalles de la transacción requeridos para ingresar al torneo. Presente cuando el jugador aún no se ha comprado.
   * Para torneos basados en tokens, incluye: { tokens: number }
   */
  buyOptions?: Record<string, number>;
  tags?: string[];
  smallImage?: string;
  largeImage?: string;
  industry: TournamentIndustryTypeEnum;
  type: TournamentTypeEnum;
  gameCategories?: string[];
  gameProviders?: string[];
  games?: string[];
  sports?: string[];
  leagues?: string[];
  teams?: string[];
  markets?: string[];
  minBetAmount: MinAmountCurrencyEntity[];
  maxNumberOfBets: number;
  timePeriod?: TimePeriodType;
  leaderboardRewards: LeaderboardReward[];
  eligibility: TournamentEligibilityType;
  status: StatusTournamentsEnum;
  objectives: TournamentObjective[];
  createdBy: string;
  updatedBy: string;
}

Detalles de compra y opciones de compra

optIn
- Cuando true, el jugador debe optar manualmente mediante playerOptInTournament().
- Cuando false, el jugador contribuye automáticamente; buyIn será GRATIS.
buyIn (BuyInOptions)
- GRATIS: Sin costo de entrada. buyOptions generalmente es indefinido/nulo.
- TOKENS: La entrada requiere moneda virtual. La cantidad exacta se expone a través de buyOptions.tokens hasta que el jugador se registre.
buyOptions (Record<string, number> | undefined)
- Visibilidad:
  - Presente solo cuando el jugador aún no ha comprado la entrada y el torneo requiere pago.
  - Indefinido/nulo después de un registro exitoso o para torneos gratuitos.
- Estructura para torneos basados en tokens:
  - { tokens: number }
- Futuros torneos basados en efectivo:
  - { USD: número, EUR: número, GBP: número, ... }`(códigos de moneda ISO 4217)
- Notas:
  - Siempre verifica la existencia antes de leer los valores.
  - Después de un playerOptInTournament exitoso, actualiza los datos; buyOptions ya no estará presente para ese jugador.

Ejemplo de uso:

const tournaments = await sdk.Tournaments.getPlayerActiveTournaments();

for (const t of tournaments) {
  if (t.buyOptions?.tokens !== undefined) {
    console.log(`Cuota de entrada: ${t.buyOptions.tokens} tokens`);
  }
}

PlayerLeaderboard

Representa la posición de un jugador en el tablero de clasificación de un torneo.

type PlayerLeaderboard = {
  leaderboardRewards: LeaderboardReward[];
  playerId: string;
  position?: number;
  score?: number;
  level?: number;
  rank?: string;
  rankImageUrl?: string;
  userName: string;
  /**
   * The number of spins left for the player only available when
   * tournament configuration Max Number of Bets is defined.
   */
  spinsLeft?: number;
  tournamentId: string;
  type: TournamentTypeEnum;
  /**
   * Round only exists for tournaments of type TournamentTypeEnum.HIGHEST_WIN but can be undefined
   * under certain conditions.
   *
   *  1- If the type is TournamentTypeEnum.MOST_POINTS
   *
   *  2- If type is TournamentTypeEnum.HIGHEST_WIN, and the player does not have any winning rounds
   */
  round?: RoundInfo;
};

PositionInfo

Representa la instantánea del tablero de clasificación del jugador autenticado para un torneo, como lo devuelve getPlayerLeaderboardsPositionInfo.

type PositionInfo = {
  tournamentId: string;
  position: string;
  score: string;
  spinsLeft: string;
};

Notas:

Todos los valores numéricos se devuelven como cadenas.
spinsLeft es relevante cuando el torneo tiene un "Número máximo de apuestas" (giros/intentos) configurado.

LeaderboardReward

Define las recompensas para las posiciones del tablero de clasificación.

type LeaderboardReward = {
  fromPosition: number;
  toPosition?: number;
  rewards: Reward[];
};

LeaderboardaConaConteoadeaParticipantes

Contiene los datos del tablero de clasificación y el número total de participantes en el torneo.

tipo LeaderboardaConaConteoadeaParticipantes = {
  tableroadeaClasificaciónaJugadores: TableroadeaClasificaciónadeaJugadores[];
  conteoadeaParticipantes: number;
};

ObjetivoadeaTorneo

Define los objetivos de los torneos.

tipo ObjetivoadeaTorneo = {
  cantidadadeaCondición: number;
  tipoadeaCondición: EnumaDeaTipoadeaCondiciónadeaObjetivo;
  categoriasadeaJuego: string[];
  tipoadeaObjetivo: EnumaDeaTipoadeaObjetivo;
  puntosaasignados: number;
};

TipoadeaElegibilidadadeaTorneo

Define los criterios de elegibilidad para los torneos.

tipo TipoadeaElegibilidadadeaTorneo = {
  tipoadeaElegibilidad: EnumaDeaTipoadeaElegibilidadadeaTorneo;
  idadeaRango?: string;
  idadeaSegmento?: string;
};

TipodeaPeriodoadeaTiempo

Define el período de tiempo de un torneo.

tipo TipodeaPeriodoadeaTiempo = {
  tipoadeaPeriodo: EnumaDeaUnidadesadeaTiempo;
  fechadeaInicio: string;
  fechadeaFin: string;
};

EntidadadeaCantidadaMínimaadeaMoneda

Define el monto mínimo y la moneda.

tipo EntidadadeaCantidadaMínimaadeaMoneda = {
  cantidad: number;
  moneda: string;
};

RespuestaaSencilla

Una interfaz genérica para respuestas sencillas con estado de éxito/error.

interfaz RespuestaaSencilla<T> {
  correcto: boolean;
  error?: RespuestaadeaError;
  datos: T | null;
}

EnumaDeaTipoadeaTorneo

Enum que define los tipos de torneos.

enum EnumaDeaTipoadeaTorneo {
  MÁSAPUNTOS = 'más_puntos',
  MAYORAGANANCIA = 'mayor_multiplicador_de_victoria',
}

EnumaDeaEstatusTorneos

Enum que define los posibles estados de los torneos.

enum EnumaDeaEstatusTorneos {
  EnaDiseño = 'en_diseño',
  Programado = 'programado',
  Activo = 'activo',
  Finalizado = 'finalizado',
  Cancelado = 'cancelado',
  SinaGiros = 'sin-giros',
}

EnumaDeaTipoadeaIndustria

Enum que define los tipos de industria para los torneos.

enum EnumaDeaTipoadeaIndustria {
  CASINO = 'casino',
  DEPORTE = 'deporte',
}

EnumaDeaTipoadeaObjetivo

Enum que define los tipos de objetivos para los torneos.

enum EnumaDeaTipoadeaObjetivo {
  DepósitoaCompletado = 'depósito_completado',
  ApostaadeaCasino = 'apuesta_casino',
  GananciaadeaCasino = 'ganancia_casino',
  PérdidaaadeaCasino = 'pérdida_casino',
  ApostaadeaDeporte = 'apuesta_deporte',
  GananciaadeaDeporte = 'ganancia_deporte',
  PérdidaaadeaDeporte = 'pérdida_deporte',
}

EnumaDeaTipoadeaCondiciónadeaObjetivo

Enum que define los tipos de condiciones para los objetivos.

enum EnumaDeaTipoadeaCondiciónadeaObjetivo {
  Cantidad = 'cantidad',
  MontoadeaGananciaaTotala = 'monto_total_de_ganancia',
  CantidadaSucesiva = 'cantidad_sucesiva',
  MontoadeaApostaaTotala = 'monto_total_de_apuesta',
}

EnumaDeaTipoadeaElegibilidadadeaTorneo

Enum que define los tipos de elegibilidad para los torneos.

enum EnumaDeaTipoadeaElegibilidadadeaTorneo {
  Todo = 'todo',
  Rangos = 'rangos',
  Segmento = 'segmento',
}

Acceso al Módulo​

Métodos​

getPlayerActiveTournaments​

Devuelve​

Ejemplo​

getLeaderboardForTournament​

Parámetros​

Devuelve​

Ejemplo​

getLeaderboardForTournamentWithParticipantCount​

Parámetros​

Devuelve​

Ejemplo​

getPlayerPositionInLeaderboardTournament​

Parámetros​

Devuelve​

Ejemplo​

subscribeForTournamentPositionChange​

Parámetros​

Devuelve​

Ejemplo​

getPlayerTournamentsHistory​

Devuelve​

Ejemplo​

playerOptInTournament​

Parámetros​

Retorna​

Manejo de errores​

Ejemplos​

Eventos relacionados​

getPlayerLeaderboardsPositionInfo​

Parámetros​

Devuelve​

Estructura de datos: PositionInfo​

Ejemplos​

Eventos relacionados​

Interfaces relacionadas​

LeaderboardPositionsChangedData​

SubscriptionOptions​

TournamentType​

Detalles de compra y opciones de compra​

PlayerLeaderboard​

PositionInfo​

LeaderboardReward​

LeaderboardaConaConteoadeaParticipantes​

ObjetivoadeaTorneo​

TipoadeaElegibilidadadeaTorneo​

TipodeaPeriodoadeaTiempo​

EntidadadeaCantidadaMínimaadeaMoneda​

RespuestaaSencilla​

EnumaDeaTipoadeaTorneo​

EnumaDeaEstatusTorneos​

EnumaDeaTipoadeaIndustria​

EnumaDeaTipoadeaObjetivo​

EnumaDeaTipoadeaCondiciónadeaObjetivo​

EnumaDeaTipoadeaElegibilidadadeaTorneo​

Acceso al Módulo

Métodos

getPlayerActiveTournaments

Devuelve

Ejemplo

getLeaderboardForTournament

Parámetros

Devuelve

Ejemplo

getLeaderboardForTournamentWithParticipantCount

Parámetros

Devuelve

Ejemplo

getPlayerPositionInLeaderboardTournament

Parámetros

Devuelve

Ejemplo

subscribeForTournamentPositionChange

Parámetros

Devuelve

Ejemplo

getPlayerTournamentsHistory

Devuelve

Ejemplo

playerOptInTournament

Parámetros

Retorna

Manejo de errores

Ejemplos

Eventos relacionados

getPlayerLeaderboardsPositionInfo

Parámetros

Devuelve

Estructura de datos: PositionInfo

Ejemplos

Eventos relacionados

Interfaces relacionadas

LeaderboardPositionsChangedData

SubscriptionOptions

TournamentType

Detalles de compra y opciones de compra

PlayerLeaderboard

PositionInfo

LeaderboardReward

LeaderboardaConaConteoadeaParticipantes

ObjetivoadeaTorneo

TipoadeaElegibilidadadeaTorneo

TipodeaPeriodoadeaTiempo

EntidadadeaCantidadaMínimaadeaMoneda

RespuestaaSencilla

EnumaDeaTipoadeaTorneo

EnumaDeaEstatusTorneos

EnumaDeaTipoadeaIndustria

EnumaDeaTipoadeaObjetivo

EnumaDeaTipoadeaCondiciónadeaObjetivo

EnumaDeaTipoadeaElegibilidadadeaTorneo