Módulo de Jogador

O Módulo de Jogador fornece acesso às informações do jogador e às preferências de gamificação no Gamanza Engage Web Client SDK.

Acessando o Módulo

O PlayerModule é inicializado internamente pelo SDK e não deve ser instanciado diretamente. Ele é acessível através da instância principal do SDK.

// Exemplo de acesso ao PlayerModule através do SDK
const { Player } = GamanzaEngageWebClientSDK.getInstance();

Métodos

obterJogador

Retorna as informações do jogador autenticado atual da plataforma Gamanza Engage.

Assinatura:

obterJogador(): Promise<PlayerData | null>

Retorna:

Tipo	Descrição
Promise<PlayerData | null>	Uma promessa que é resolvida com os dados do jogador ou nulo se o jogador estiver faltando ou houver um erro.

Exemplo:

// Obter informações do jogador
const player = await sdk.Player.obterJogador();
if (player) {
  console.log(`ID do Jogador: ${player.playerId}`);
  console.log(`Nome do Jogador: ${player.firstName} ${player.lastName}`);
  
  // Acessar o status da gamificação
  console.log(`Gamificação Habilitada: ${player.gamificationOpt.enable}`);
  
  // Acessar os dados de classificação, se disponíveis
  if (player.ranksData) {
    console.log(`Classificação Atual: ${player.ranksData.rank.name}`);
    console.log(`Nível Atual: ${player.ranksData.level.levelNumber}`);
    console.log(`Saldo de XP: ${player.ranksData.xpBalance}`);
  }
  
  // Acessar os dados da carteira, se disponíveis
  if (player.walletData) {
    console.log(`Saldo da Carteira: ${player.walletData.balance}`);
  }
}

opçõesGamificaçãoJogador

Permite habilitar ou desabilitar os recursos de Gamificação Gamanza Engage para o jogador autenticado atual.

Assinatura:

opçõesGamificaçãoJogador(enable: boolean, reasons: Reason[]): Promise<SimpleResponse<void>>

Parâmetros:

Nome	Tipo	Descrição
enable	Tipo boolean	Define se o jogador está optando por participar (verdadeiro) ou optando por não participar (falso)
reasons	Reason[]	Lista de possíveis razões pelas quais o jogador está optando por não participar (obrigatório ao optar por não participar)

Retorna:

Tipo	Descrição
Promise<SimpleResponse<void>>	Uma promessa que é resolvida com uma resposta simples indicando sucesso ou falha

Exemplo:

// Optar por não participar da gamificação com razões
const reasons = await sdk.Player.obterListaDeRazõesParaOptarPorNãoParticipar();
const selectedReasons = [reasons[0]]; // Selecionar a primeira razão da lista

const response = await sdk.Player.opçõesGamificaçãoJogador(false, selectedReasons);
if (response.ok) {
  console.log('Optou com sucesso por não participar da gamificação');
} else {
  console.error('Falha ao optar por não participar da gamificação:', response.error);
}

// Optar por participar da gamificação (sem razões necessárias)
const optInResponse = await sdk.Player.opçõesGamificaçãoJogador(true, []);
if (optInResponse.ok) {
  console.log('Optou com sucesso por participar da gamificação');
}

obterListaDeRazõesParaOptarPorNãoParticipar

Retorna a lista de razões predefinidas configuradas na instância Gamanza Engage Admin para serem exibidas ao jogador quando eles decidirem optar por não participar da gamificação.

Assinatura:

getListOfOptOutReasons(): Promise<Reason[]>

Retorna:

Tipo	Descrição
Promise<Razão[]>	Uma promessa que é resolvida em um array de motivos pré-definidos para opt-out

Exemplo:

// Obter a lista de motivos de opt-out
const razoes = await sdk.Player.getListOfOptOutReasons();
console.log('Motivos de opt-out disponíveis:');
razoes.forEach(razao => {
  // Exibir o motivo no idioma do usuário, se disponível
  const traducao = razao.translations?.find(t => t.language === userLanguage);
  console.log(traducao?.text || razao.option);
});

Interfaces Relacionadas

PlayerData

A interface principal para informações do jogador.

interface PlayerData {
  playerId: string;
  firstName?: string;
  lastName?: string;
  gender?: string;
  phone?: string;
  username?: string;
  email?: string;
  language?: string;
  currency?: string;
  birthDate?: string;
  nationality?: string;
  address?: Endereço;
  session?: SessãoJogador;
  gamificationOpt: OpçãoGamificação;
  ranksData?: DadosRanks;
  walletData?: DadosCarteira;
}

Propriedade	Tipo	Obrigatório	Descrição
playerId	Tipo string	Sim	Identificador único do jogador
firstName	Tipo string	Não	Primeiro nome do jogador
lastName	Tipo string	Não	Sobrenome do jogador
gender	Tipo string	Não	Gênero do jogador
phone	Tipo string	Não	Número de telefone do jogador
username	Tipo string	Não	Nome de usuário do jogador
email	Tipo string	Não	Endereço de email do jogador
language	Tipo string	Não	Idioma preferido do jogador
currency	Tipo string	Não	Moeda preferida do jogador
birthDate	Tipo string	Não	Data de nascimento do jogador
nationality	Tipo string	Não	Nacionalidade do jogador
address	Address	Não	Informações de endereço do jogador
session	PlayerSession	Não	Informações da sessão do jogador
gamificationOpt	GamificationOpt	Sim	Preferências de gamificação do jogador
ranksData	RanksData	Não	Informações de classificação do jogador
walletData	WalletData	Não	Informações da carteira do jogador

Endereço

Interface para informações de endereço do jogador.

interface Address {
  country?: string;
  city?: string;
  street?: string;
  postcode?: string;
}

Propriedade	Tipo	Obrigatório	Descrição
country	Tipo string	Não	País do jogador
city	Tipo string	Não	Cidade do jogador
rua	string	Não	Endereço residencial do jogador
código postal	string	Não	Código postal do jogador

PlayerSession

Interface para informações da sessão do jogador.

interface PlayerSession {
  registrationDate?: string;
  registrationDevice?: string;
  verificationDate?: string;
  verificationChannel?: string;
  numberDaysInLastTwoLogins?: number;
  lastLoginDate?: string;
  secondLastLoginDate?: string;
  loginCount?: number;
  lastLogoutDate?: string;
}

Propriedade	Tipo	Obrigatório	Descrição
registrationDate	string	Não	Data em que o jogador se registrou
registrationDevice	string	Não	Dispositivo usado para registro
verificationDate	string	Não	Data em que o jogador foi verificado
verificationChannel	string	Não	Canal usado para verificação
numberDaysInLastTwoLogins	number	Não	Número de dias entre os dois últimos logins
lastLoginDate	string	Não	Data do último login do jogador
secondLastLoginDate	string	Não	Data do penúltimo login do jogador
loginCount	number	Não	Número total de logins
última data de logout	string	Não	Data do último logout do jogador

GamificationOpt

Interface para preferências de gamificação do jogador.

interface GamificationOpt {
  ativar: boolean;
  razão?: Razão[];
  políticaDeRedefinição?: Record<string, unknown>;
  solicitadaPorTipo?: string;
  solicitadaPor?: string;
  solicitadaEm?: string;
}

Propriedade	Tipo	Obrigatório	Descrição
ativar	boolean	Sim	Se a gamificação está ativada para o jogador
razão	Razão[]	Não	Razões para se desligar da gamificação
políticaDeRedefinição	Record<string, unknown>	Não	Política para redefinir a gamificação
solicitadaPorTipo	string	Não	Tipo de entidade que solicitou a mudança no status da gamificação
solicitadaPor	string	Não	Entidade que solicitou a mudança no status da gamificação
solicitadaEm	Tipo string	Não	Data em que a mudança no status da gamificação foi solicitada

Razão

Interface para razões de desativação.

interface Razão {
  opção?: string;
  traduções?: Tradução[];
}

Propriedade	Tipo	Obrigatório	Descrição
opção	Tipo string	Não	Identificador para a razão
traduções	Tradução[]	Não	Traduções do texto da razão

Tradução

Interface para traduções.

interface Tradução {
  idioma?: string;
  texto?: string;
}

Propriedade	Tipo	Obrigatório	Descrição
idioma	Tipo string	Não	Código de idioma
texto	Tipo string	Não	Texto traduzido

DadosClassificação

Interface para informações de classificação do jogador.

interface DadosClassificação {
  _id: string;
  jogadorId: string;
  categoria: Categoria;
  classificação: Classificação;
  nível: Nível;
  saldoXP: number;
  criadoEm: string;
  atualizadoEm: string;
  moeda: string;
  períodoAnterior?: PadrãoPeriodo;
  progressoClassificação: number;
  progressoNível: number;
  posiçãoNível?: PosiçãoNível;
  pontosAteProximoNível: number;
  pontosAteProximaClassificação: number;
  próximoNível?: Nível;
  próximaClassificação?: Classificação;
  pontosParaManterClassificação?: number;
  xpPeríodoComparativo?: string;
  atividadeAposta?: TipoAtividadeAposta;
}

Propriedade	Tipo	Obrigatório	Descrição
_id	Tipo string	Sim	Identificador único para os dados de classificação
jogadorId	Tipo string	Sim	Identificador do jogador
categoria	Categoria	Sim	Categoria de classificação
classificação	Classificação	Sim	Classificação atual
nível	Nível	Sim	Nível atual
saldoXP	Tipo number	Sim	Saldo atual de XP
createdAt	Tipo string	Sim	Data de criação
updatedAt	Tipo string	Sim	Última data de atualização
currency	Tipo string	Sim	Moeda utilizada
previousPeriod	PreviousPeriod	Não	Dados do período anterior
rankProgress	Tipo number	Sim	Progresso para a próxima classificação (0-100)
levelProgress	Tipo number	Sim	Progresso para o próximo nível (0-100)
levelPosition	LevelPosition	Não	Posição dentro do nível atual
pointsUntilNextLevel	Tipo number	Sim	Pontos necessários para alcançar o próximo nível
pointsUntilNextRank	Tipo number	Sim	Pontos necessários para alcançar a próxima classificação
nextLevel	Nível	Não	Informações sobre o próximo nível
nextRank	Classificação	Não	Informações sobre a próxima classificação
pointsToKeepRank	Tipo number	Não	Pontos necessários para manter a classificação atual
xpComparativePeriod	Tipo string	Não	Período usado para comparação de XP
betActivity	BetActivityType	Não	Informações sobre a atividade de apostas

Categoria

Interface para categorias de classificação.

interface Categoria {
  _id: string;
  name: string;
}

Propriedade	Tipo	Obrigatório	Descrição
_id	Tipo string	Sim	Identificador único para a categoria
nome	Tipo string	Sim	Nome da categoria

Classificação

Interface para classificações de jogadores.

interface Rank {
  _id: string;
  name: string;
  imageUrl: string;
  translations: RanksTranslation[];
}

Propriedade	Tipo	Obrigatório	Descrição
_id	Tipo string	Sim	Identificador único para a classificação
nome	Tipo string	Sim	Nome da classificação
imageUrl	Tipo string	Sim	URL para a imagem da classificação
traduções	RanksTranslation[]	Sim	Traduções das informações da classificação

Nível

Interface para níveis de jogadores.

interface Nível {
  _id: string;
  numeroDaNivel: number;
}

Propriedade	Tipo	Obrigatório	Descrição
_id	Tipo string	Sim	Identificador único para o nível
numeroDaNivel	Tipo number	Sim	Número do nível

DadosDeCarteira

Interface para informações da carteira do jogador.

interface DadosDeCarteira {
  _id: string;
  saldo: number;
  criadoEm: string;
  atualizadoEm: string;
}

Propriedade	Tipo	Obrigatório	Descrição
_id	Tipo string	Sim	Identificador único para a carteira
saldo	Tipo number	Sim	Saldo atual da carteira
criadoEm	Tipo string	Sim	Data de criação
atualizadoEm	Tipo string	Sim	Data da última atualização

RespostaSimples

Interface genérica para respostas simples.

interface RespostaSimples<T> {
  ok: boolean;
  data: T | null;
  error?: {
    code: string;
    message: string;
  };
}

Propriedade	Tipo	Obrigatório	Descrição
ok	Tipo boolean	Sim	Se a operação foi bem-sucedida
data	T | null	Sim	Dados de resposta (nulo para respostas vazias)
erro	{ code: string; message: string; }	Não	Informações de erro se a operação falhar