Módulo de Torneios

O módulo de Torneios fornece funcionalidades para interagir com o sistema de Torneios do Gamanza Engage. Ele permite que os desenvolvedores recuperem torneios ativos, histórico de torneios, quadros de liderança e inscrevam jogadores em torneios.

Acessando o Módulo

O módulo de Torneios é acessível através do SDK do Cliente Web do Gamanza Engage:

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

Métodos

getPlayerActiveTournaments

Retorna a lista de torneios ativos e elegíveis para o jogador autenticado atual.

Assinatura:

getPlayerActiveTournaments(): Promise<TournamentType[]>

Retornos

Tipo	Descrição
Promise<TournamentType[]>	Uma promessa que é resolvida em um array de torneios ativos

Exemplo

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

getLeaderboardForTournament

Retorna o quadro de liderança para o ID de torneio fornecido. A resposta sempre inclui o jogador autenticado atual como parte da resposta.

• Para Torneios Ativos: o quadro de liderança sempre retorna as 25 primeiras posições, e se o jogador não estiver nas 25 primeiras, é adicionado no final.
• Para Torneios Encerrados: o quadro de liderança pode receber o número de itens a serem retornados, com um máximo de 100 itens.

Assinatura:

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

Parâmetros

Nome	Tipo	Descrição
tournamentId	string	O identificador exclusivo do torneio
items	number	O número de posições do quadro de liderança a serem retornadas (padrão: 25, máximo: 100)

Retornos

Tipo	Descrição
Promise<PlayerLeaderboard[]>	Uma promessa que é resolvida em um array de posições do quadro de liderança do jogador

Exemplo

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

Novo método:** `getLeaderboardForTournamentWithParticipantCount

Retorna o quadro de liderança para o ID de torneio fornecido, incluindo o total de participantes. A resposta sempre inclui o jogador autenticado atual como parte da resposta.

• Para Torneios Ativos: o quadro de liderança sempre retorna as 25 primeiras posições, e se o jogador não estiver nas 25 primeiras, é adicionado no final.
• Para Torneios Encerrados: o quadro de liderança pode receber o número de itens a serem retornados, com um máximo de 100 itens.

Assinatura:

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

Parâmetros

Nome	Tipo	Descrição
tournamentId	string	O identificador único do torneio
items	number	O número de posições do placar a serem retornadas (padrão: 25, máx: 100)

Retornos

Tipo	Descrição
Promise<LeaderboardWithParticipantCount>	Uma promessa que resolve os dados do placar e a contagem total de participantes

Exemplo

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

getPlayerPositionInLeaderboardTournament

Retorna a posição atual e a pontuação para o ID do torneio especificado para o jogador autenticado.

Observação: Este método está descontinuado. Essas informações são propagadas em tempo real, inscrevendo-se no método subscribeForTournamentPositionChange ou no evento EVENTS.TOURNAMENTS.ON_TOURNAMENT_PLAYER_LEADERBOARD_UPDATED. Alternativamente, você pode usar Tournaments.getLeaderboardForTournament e filtrar pelo playerId autenticado atual na resposta.

Assinatura:

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

Parâmetros

Nome	Tipo	Descrição
tournamentId	string	O identificador único do torneio

Retornos

Tipo	Descrição
Promise<{ position: number; score: number; } | null>	Uma promessa que resolve a posição e a pontuação do jogador, ou nulo se não for encontrado

Exemplo

const position = await sdk.Tournaments.getPlayerPositionInLeaderboardTournament("tournament-id-123");
if (position) {
  console.log(`Posição atual: ${position.position}, Pontuação: ${position.score}`);
}

subscribeForTournamentPositionChange

Inscreve-se em alterações de posição em tempo real do placar para o torneio especificado.

Assinatura:

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

Parâmetros

Nome	Tipo	Descrição
identificador de torneio	string	O identificador exclusivo do torneio
callback	função	Uma função de retorno de chamada que recebe um objeto LeaderboardPositionsChangedData quando ocorre uma mudança.
opções	SubscriptionOptions	Configuração opcional para a assinatura (por exemplo, once, filter).

Retornos

Tipo	Descrição
() => void	Uma função de cancelamento de assinatura. Chame-a para parar de receber atualizações.

Exemplo

const unsubscribe = sdk.Tournaments.subscribeForTournamentPositionChange(
  'tournament-abc-123',
  (positionInfo) => {
    console.log(`A posição mudou no torneio ${positionInfo.tournamentId}`);
    
    if (currentPlayerTournamentLeaderboard.position > positionInfo.position) {
      // Atualize o quadro de classificação para refletir as últimas posições
      sdk.Tournaments.getLeaderboardForTournament(positionInfo.tournamentId);
    }
  },
);

// Mais tarde, quando você não precisar mais da assinatura:
unsubscribe();

getPlayerTournamentsHistory

Retorna o histórico recente de participação em torneios para o jogador autenticado atual. O histórico é baseado nos últimos 30 dias por padrão. Se você precisar alterar essa configuração, entre em contato com seu Gerente de Sucesso do Cliente e solicite o ajuste da configuração Tournaments.HISTORY_DAYS_COUNT.

Assinatura:

getPlayerTournamentsHistory(): Promise<TournamentType[]>

Retornos

Tipo	Descrição
Promise<TournamentType[]>	Uma promessa que é resolvida em uma matriz de entradas do histórico de torneios

Exemplo

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

playerOptInTournament

Faz com que o jogador autenticado atualmente entre em um torneio específico. Use isso apenas quando o torneio tiver optIn: true. Se optIn for false, os jogadores participam automaticamente e essa chamada não é necessária.

• Torneios gratuitos (BuyInOptions.FREE)
  • Comportamento: O jogador começa imediatamente a contribuir após a entrada bem-sucedida
  • Custo: Nenhum
  • Resposta: { ok: true, data: null }
• Torneios com compra de tokens (BuyInOptions.TOKENS)
  • Comportamento: Valida o saldo da moeda virtual do jogador e deduz a taxa de entrada com sucesso
  • Requisito: O jogador deve ter moedas/tokens suficientes
  • Erros: Retorna faultCode = 402 (Pagamento Necessário) quando o saldo é insuficiente

No sucesso, o SDK limpa os caches relacionados a torneios (torneios ativos, histórico) e os caches de recompensas, para que as leituras subsequentes reflitam o estado atualizado.

Assinatura:

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

Parâmetros

Nome	Tipo	Descrição
tournamentId	string	O identificador único do torneio (de getPlayerActiveTournaments)

Retornos

Tipo	Descrição
Promise<SimpleResponse<null>>	Resolve com { ok: true, data: null } em caso de sucesso ou { ok: false, data: null, error } em caso de falha

Tratamento de Erros

• Saldo insuficiente (entrada de token): error.details.faultCode === 402
• Outros possíveis erros: torneio não encontrado, já iniciado/terminado, já participou, capacidade máxima atingida

const res = await sdk.Tournaments.playerOptInTournament(tournamentId);
if (!res.ok) {
  switch (res.error?.details?.faultCode) {
    case 402:
      // Saldo insuficiente para entrada no torneio
      break;
    default:
      // Trate outros erros
      break;
  }
}

Exemplos

Torneio ativo):

const response = await sdk.Tournaments.playerOptInTournament("tournament-id-123");
if (response.ok) {
  console.log("Participação no torneio realizada com sucesso");
}

Com verificação prévia da entrada de token:

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) {
    // Solicite ao usuário a compra de mais moedas
  }
}

const res2 = await sdk.Tournaments.playerOptInTournament("tournament-456");
if (!res2.ok && res2.error?.details?.faultCode === 402) {
  // Exiba a interface de saldo insuficiente
}

Eventos do Jogador

• EVENTS.TOURNAMENTS.ON_TOURNAMENT_STARTS — O torneio começou
• EVENTS.TOURNAMENTS.ON_TOURNAMENT_PLAYER_LEADERBOARD_UPDATED — A posição do jogador foi atualizada
• EVENTS.TOURNAMENTS.ON_TOURNAMENT_ENDS — O torneio terminou
• EVENTS.TOURNAMENTS.ON_TOURNAMENT_PLAYER_REWARDS — O jogador recebeu recompensas

getPlayerLeaderboardsPositionInfo

Recupera as informações da posição do jogador autenticado nos leaderboards de vários torneios. Isso retorna a própria posição do jogador, pontuação e rodadas restantes (se aplicável) para cada torneio solicitado.

• Específico do jogador: apenas os dados do jogador autenticado
• Operação em lote: até 5 torneios por chamada
• Truncamento automático: se mais de 5 IDs forem fornecidos, apenas os primeiros 5 serão processados

Assinatura:

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

Parâmetros

Nome	Tipo	Descrição
tournamentIds	string[]	Array de IDs de torneio a serem consultados. Apenas os primeiros 5 serão processados.

Retornos

Tipo	Descrição
Promise<PositionInfo[]>	Uma promessa que se resolve em uma matriz com as informações de posição do jogador por torneio.

Estrutura de Dados: PositionInfo

Cada item PositionInfo descreve as estatísticas atuais do torneio do jogador:

• tournamentId (string): O identificador exclusivo do torneio
• position (string): Classificação do jogador no leaderboard (por exemplo, "1", "25", "150")
• score (string): Pontuação acumulada do jogador no torneio (por exemplo, "5000", "125000")
• spinsLeft (string): Tentativas/giros restantes disponíveis (por exemplo, "10", "0")

Consulte também a referência de interface na seção Interfaces Relacionadas abaixo.

Exemplos

Uso básico (um único torneio):

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

Vários torneios (até 5):

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

Truncamento automático (mais de 5 fornecidos):

const manyIds = ["t1", "t2", "t3", "t4", "t5", "t6", "t7"];
const positions = await sdk.Tournaments.getPlayerLeaderboardsPositionInfo(manyIds);
// Somente processa e retorna dados para t1..t5; t6 e t7 são ignorados.

Eventos Relacionados

• EVENTS.TOURNAMENTS.ON_TOURNAMENT_PLAYER_LEADERBOARD_UPDATED — Assine para receber atualizações em tempo real da posição do jogador sem sondagem
• subscribeForTournamentPositionChange — Método para assinar por alterações de posição em um torneio específico

Interfaces Relacionadas

LeaderboardPositionsChangedData

Dados recebidos quando a posição de um jogador em um leaderboard de torneio é alterada.

interface LeaderboardPositionsChangedData {
  tournamentId: string;
  position: number;
  /**
   * Indica se o jogador precisa sincronizar o leaderboard na interface do usuário usando um dos seguintes métodos
   * no SDK `getLeaderboardForTournament` ou `getLeaderboardForTournamentWithParticipantCount`.
   * Se este valor for verdadeiro, as outras propriedades podem estar vazias.
   */
  requireSync: boolean;
  timestamp: number;
}

SubscriptionOptions

Opções para controlar o comportamento da assinatura.

interface SubscriptionOptions {
  uma?: boolean;
  tempo?: number;
  filtro?: (dados: any) => boolean;
  maxTentativas?: number;
  autoAcknowledge?: boolean;
}

TipoTorneio

Representa um torneio no sistema.

interface TournamentType {
  _id?: string;
  internalDetails: {} & Pick<TranslationType, 'name' | 'description'>;
  externalDetails: ExternalDetailsEntity[];
  /**
   * Exigir adesão manual (true) ou participação automática (false).
   */
  optIn: boolean;
  /**
   * Indica se o jogador atual já está inscrito.
   */
  isPlayerOptIn: boolean;
  /**
   * Tipo de entrada para o torneio.
   * Se optIn = false, isso sempre será BuyInOptions.FREE.
   */
  buyIn: BuyInOptions; // FREE | TOKENS
  /**
   * Detalhes da transação necessários para entrar no torneio. Presente quando o jogador ainda não comprou.
   * Para torneios baseados em tokens, inclui: { 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;
}

Detalhes de buy-in e opções de compra

• optIn
  • Quando true, o jogador deve optar manualmente usando playerOptInTournament().
  • Quando false, o jogador contribui automaticamente; buyIn será GRATUITO.
• buyIn (BuyInOptions)
  • GRATUITO: Sem custo para entrar. buyOptions geralmente é indefinido/nulo.
  • TOKENS: A entrada requer moeda virtual. O valor exato é exposto via buyOptions.tokens até que o jogador opte.
• buyOptions (Record<string, number> | indefinido)
  • Visibilidade:
    • Presente apenas quando o jogador ainda não adquiriu a entrada e o torneio exige pagamento.
    • Indefinido/nulo após a adesão bem-sucedida ou para torneios gratuitos.
  • Estrutura para torneios baseados em tokens:
    • { tokens: number }
  • Futuros torneios baseados em dinheiro:
    • { USD: number, EUR: number, GBP: number, ... }` (códigos de moeda ISO 4217)
  • Observações:
    • Sempre verifique a existência antes de ler os valores.
    • Após uma playerOptInTournament bem-sucedida, atualize os dados; buyOptions não estará mais presente para esse jogador.

Exemplo de uso:

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

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

LeaderboardJogador

Representa a posição de um jogador no placar de liderança de um torneio.

type LeaderboardJogador = {
  leaderboardRewards: LeaderboardRecompensa[];
  playerId: string;
  posicao?: number;
  pontuacao?: number;
  nivel?: number;
  rank?: string;
  rankImageUrl?: string;
  userName: string;
  /**
   * O número de rodadas restantes para o jogador, disponível apenas quando
   * a configuração do torneio Max Number of Bets é definida.
   */
  spiansRestantes?: number;
  tornamentoId: string;
  type: TipoTorneioEnum;
  /**
   * A rodada só existe para torneios do tipo TipoTorneioEnum.HIGHEST_WIN, mas pode ser indefinida
   * em certas condições.
   *
   *  1- Se o tipo for TipoTorneioEnum.MOST_POINTS
   *
   *  2- Se o tipo for TipoTorneioEnum.HIGHEST_WIN e o jogador não tiver nenhuma rodada vencedora
   */
  rodada?: InformacoesRodada;
};

InformacoesPosition

Representa o instantâneo do placar de liderança do jogador autenticado para um torneio, conforme retornado por getPlayerLeaderboardsPositionInfo.

type InformacoesPosition = {
  tornamentoId: string;
  posicao: string;
  pontuacao: string;
  spiansRestantes: string;
};

Observações:

• Todos os valores numéricos são retornados como strings.
• spinsLeft é relevante quando o torneio tem uma "Quantidade Máxima de Apostas" (giros/tentativas) configurada.

LeaderboardRecompensa

Define as recompensas para as posições no placar de liderança.

type LeaderboardRecompensa = {
  dePosiçao: number;
  atéPosiçao?: number;
  recompensas: Recompensa[];
};

LeaderboardComParticipaçãoContagem

Contém os dados do quadro de liderança e o número total de participantes no torneio.

tipo LeaderboardComParticipaçãoContagem = {
  tabelaLideres: TabelaLideres[];
  contagemParticipantes: number;
};

ObjetivoTorneio

Define os objetivos para os torneios.

tipo ObjetivoTorneio = {
  quantidadeCondição: number;
  tipoCondição: EnumTipoCondiçãoObjetivo;
  categoriasJogo: string[];
  tipoObjetivo: EnumTipoObjetivo;
  pontosAtribuídos: number;
};

TipoElegibilidadeTorneio

Define os critérios de elegibilidade para torneios.

tipo TipoElegibilidadeTorneio = {
  tipoElegibilidade: EnumTipoElegibilidadeTorneio;
  idRanque?: string;
  idSegmento?: string;
};

TipoPeriodoTempo

Define o período de tempo de um torneio.

tipo TipoPeriodoTempo = {
  tipoPeriodo: EnumUnidadesTempo;
  dataInício: string;
  dataFim: string;
};

EntidadeValorMínimoMoeda

Define o valor mínimo e a moeda.

tipo EntidadeValorMínimoMoeda = {
  valor: number;
  moeda: string;
};

RespostaSimples

Uma interface genérica para respostas simples com status de sucesso/erro.

interface RespostaSimples<T> {
  ok: boolean;
  erro?: RespostaErro;
  dados: T | null;
}

EnumTipoTorneio

Enum definindo os tipos de torneios.

enum EnumTipoTorneio {
  MAIORMAIS_PONTOS = 'maior_pontos',
  MAIORVENTEAGEM = 'maior_multiplicador_vencimento',
}

EnumStatusTorneios

Enum definindo os possíveis status dos torneios.

enum EnumStatusTorneios {
  EmDesign = 'em_design',
  Agendado = 'agendado',
  Ativo = 'ativo',
  Finalizado = 'finalizado',
  Cancelado = 'cancelado',
  SemGiros = 'sem-giros',
}

EnumTipoIndustriaTorneio

Enum definindo os tipos de indústria para torneios.

enum EnumTipoIndustriaTorneio {
  CASSINO = 'cassino',
  ESPORTE = 'esporte',
}

EnumTipoObjetivo

Enum definindo os tipos de objetivos para torneios.

enum EnumTipoObjetivo {
  DepósitoCompletado = 'deposito_completado',
  ApostasCassino = 'aposta_cassino',
  VitóriaCassino = 'vitoria_cassino',
  DerrotaCassino = 'derrota_cassino',
  ApostasEsporte = 'aposta_esporte',
  VitóriaEsporte = 'vitoria_esporte',
  DerrotaEsporte = 'derrota_esporte',
}

EnumTipoCondiçãoObjetivo

Enum definindo os tipos de condições para objetivos.

enum EnumTipoCondiçãoObjetivo {
  Quantidade = 'quantidade',
  ValorTotalVitória = 'valor_total_vitoria',
  QuantidadeSequencial = 'quantidade_sequencial',
  ValorTotalAposta = 'valor_total_aposta',
}

EnumTipoElegibilidadeTorneio

Enum definindo os tipos de elegibilidade para torneios.

enum EnumTipoElegibilidadeTorneio {
  Todos = 'todos',
  Ranques = 'ranques',
  Segmento = 'segmento',
}