Módulo de jugador

El Módulo de jugador proporciona acceso a la información del jugador y las preferencias de gamificación en el SDK web de Gamanza Engage.

Acceso al módulo

El PlayerModule se inicializa internamente por el SDK y no debe ser instanciado directamente. Se puede acceder a través de la instancia principal del SDK.

// Ejemplo de acceso al PlayerModule a través del SDK
const { Player } = GamanzaEngageWebClientSDK.getInstance();

Métodos

getJugador

Devuelve la información del jugador autenticado actual desde la plataforma Gamanza Engage.

Firma:

getJugador(): Promise<DatosJugador | null>

Devuelve:

Tipo	Descripción
Promise<PlayerData | null>	Una promesa que se resuelve con los datos del jugador o null si falta el jugador o hay un error.

Ejemplo:

// Obtener información del jugador
const player = await sdk.Player.getPlayer();
if (player) {
  console.log(`ID de jugador: ${player.playerId}`);
  console.log(`Nombre de jugador: ${player.firstName} ${player.lastName}`);
  
  // Acceder al estado de gamificación
  console.log(`Gamificación habilitada: ${player.gamificationOpt.enable}`);
  
  // Acceder a los datos de rango si están disponibles
  if (player.ranksData) {
    console.log(`Rango actual: ${player.ranksData.rank.name}`);
    console.log(`Nivel actual: ${player.ranksData.level.levelNumber}`);
    console.log(`Saldo de XP: ${player.ranksData.xpBalance}`);
  }
  
  // Acceder a los datos de billetera si están disponibles
  if (player.walletData) {
    console.log(`Saldo de billetera: ${player.walletData.balance}`);
  }
}

opcionesGamificaciónJugador

Permite habilitar o deshabilitar las funciones de gamificación de Gamanza Engage para el jugador autenticado actual.

Firma:

opcionesGamificaciónJugador(activar: boolean, razones: Razón[]): Promise<RespuestaSimple<void>>

Parámetros:

Nombre	Tipo	Descripción
activar	boolean	Define si el jugador se suscribe (verdadero) o se da de baja (falso)
razones	Razón[]	Lista de posibles razones por las que el jugador se da de baja (obligatorio al darse de baja)

Devuelve:

Tipo	Descripción
Promise<RespuestaSimple<void>>	Una promesa que se resuelve en una respuesta simple que indica éxito o fallo

Ejemplo:

// Darse de baja de la gamificación con razones
const reasons = await sdk.Player.getListOfOptOutReasons();
const selectedReasons = [reasons[0]]; // Seleccionar la primera razón de la lista

const response = await sdk.Player.playerGamificationOpts(false, selectedReasons);
if (response.ok) {
  console.log('Se ha dado de baja de la gamificación con éxito');
} else {
  console.error('No se pudo dar de baja de la gamificación:', response.error);
}

// Suscribirse a la gamificación (no se necesitan razones)
const optInResponse = await sdk.Player.playerGamificationOpts(true, []);
if (optInResponse.ok) {
  console.log('Se ha suscrito a la gamificación con éxito');
}

obtenerListaDeRazonesDeExclusión

Devuelve la lista de razones predefinidas configuradas en la instancia de administración de Gamanza Engage para ser mostradas al jugador cuando decida darse de baja de la gamificación.

Firma:

obtenerListaDeRazonesDeExclusión(): Promise<Razón[]>

Devuelve:

Tipo	Descripción
Promise<Razón[]>	Una promesa que se resuelve en una matriz de razones predefinidas para la exclusión voluntaria

Ejemplo:

// Obtener la lista de razones de exclusión voluntaria
const reasons = await sdk.Player.obtenerListaDeRazonesDeExclusión();
console.log('Razones de exclusión voluntaria disponibles:');
reasons.forEach(reason => {
  // Mostrar la razón en el idioma del usuario si está disponible
  const translation = reason.translations?.find(t => t.language === userLanguage);
  console.log(translation?.text || reason.option);
};

Interfaces relacionadas

PlayerData

La interfaz principal para la información del jugador.

interface DatosJugador {
  playerId: string;
  firstName?: string;
  lastName?: string;
  gender?: string;
  phone?: string;
  username?: string;
  email?: string;
  language?: string;
  currency?: string;
  birthDate?: string;
  nationality?: string;
  address?: Dirección;
  session?: SesiónJugador;
  gamificationOpt: OpciónGamificación;
  ranksData?: DatosRanking;
  walletData?: DatosCartera;
}

Propiedad	Tipo	Requerido	Descripción
playerId	string	Sí	Identificador único para el jugador
firstName	string	No	Nombre del jugador
lastName	string	No	Apellido del jugador
gender	string	No	Género del jugador
phone	string	No	Número de teléfono del jugador
username	string	No	Nombre de usuario del jugador
email	string	No	Dirección de correo electrónico del jugador
language	string	No	Idioma preferido del jugador
currency	string	No	Moneda preferida del jugador
birthDate	string	No	Fecha de nacimiento del jugador
nationality	string	No	Nacionalidad del jugador
address	Dirección	No	Información de dirección del jugador
session	Sesión del jugador	No	Información de la sesión del jugador
gamificationOpt	Opt de gamificación	Sí	Preferencias de gamificación del jugador
ranksData	Datos de rango	No	Información de rango del jugador
walletData	Datos de cartera	No	Información de la cartera del jugador

Dirección

Interfaz para la información de dirección del jugador.

interfaz Dirección {
  país?: cadena;
  ciudad?: cadena;
  calle?: cadena;
  código postal?: cadena;
}

Propiedad	Tipo	Requerido	Descripción
país	cadena	No	País del jugador
ciudad	cadena	No	Ciudad del jugador
calle	cadena	No	Dirección del jugador
código postal	cadena	No	Código postal del jugador

PlayerSession

Interfaz para la información de la sesión del jugador.

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

Propiedad	Tipo	Requerido	Descripción
registrationDate	string	No	Fecha de registro del jugador
registrationDevice	string	No	Dispositivo utilizado para el registro
verificationDate	string	No	Fecha de verificación del jugador
verificationChannel	string	No	Canal utilizado para la verificación
numberDaysInLastTwoLogins	number	No	Número de días entre los dos últimos inicios de sesión
lastLoginDate	string	No	Fecha del último inicio de sesión del jugador
secondLastLoginDate	string	No	Fecha del penúltimo inicio de sesión del jugador
loginCount	number	No	Número total de inicios de sesión
"lastLogoutDate"	"string"	No	Fecha del último cierre de sesión del jugador

GamificationOpt

Interfaz para las preferencias de gamificación del jugador.

interface GamificationOpt {
  enable: boolean;
  reason?: Reason[];
  resetPolicy?: Record<string, unknown>;
  requestedByType?: string;
  requestedBy?: string;
  requestedAt?: string;
}

Propiedad	Tipo	Requerido	Descripción
"enable"	"boolean"	Sí	Si la gamificación está habilitada para el jugador
"reason"	"Reason[]"	No	Razones para optar por no participar en la gamificación
"resetPolicy"	Record<string, unknown>	No	Política para restablecer la gamificación
"requestedByType"	"string"	No	Tipo de entidad que solicitó el cambio de estado de la gamificación
"requestedBy"	"string"	No	Entidad que solicitó el cambio de estado de la gamificación
"requestedAt"	"string"	No	Fecha en que se solicitó el cambio de estado de la gamificación

Razón

Interfaz para razones de exclusión.

interface Reason {
  option?: string;
  translations?: Translation[];
}

Propiedad	Tipo	Requerido	Descripción
"option"	"string"	No	Identificador de la razón
"translations"	"Translation[]"	No	Traducciones del texto del motivo

Traducción

Interfaz para traducciones.

interfaz Traducción {
  idioma?: string;
  texto?: string;
}

Propiedad	Tipo	Obligatorio	Descripción
idioma	string	No	Código de idioma
texto	string	No	Texto traducido

DatosDeRango

Interfaz para información de rango de jugador.

interfaz DatosDeRango {
  _id: string;
  idJugador: string;
  categoría: Categoría;
  rango: Rango;
  nivel: Nivel;
  balanceXP: number;
  creadoEn: string;
  actualizadoEn: string;
  moneda: string;
  periodoAnterior?: PeriodoAnterior;
  progresióndRango: number;
  progresióndNivel: number;
  posiciónDeNivel?: PosiciónDeNivel;
  puntosHastaProximoNivel: number;
  puntosHastaProximoRango: number;
  proximoNivel?: Nivel;
  proximoRango?: Rango;
  puntosParaMantenerRango?: number;
  xpComparativoPeríodo?: string;
  actividadDeApuesta?: TipoDeActividadDeApuesta;
}

Propiedad	Tipo	Obligatorio	Descripción
_id	string	Sí	Identificador único para los datos de rango
idJugador	string	Sí	Identificador de jugador
categoría	Categoría	Sí	Categoría de rango
rango	Rango	Sí	Rango actual
nivel	Nivel	Sí	Nivel actual
balanceXP	number	Sí	Saldo actual de XP
createdAt	string	Sí	Fecha de creación
updatedAt	string	Sí	Última fecha de actualización
currency	string	Sí	Moneda utilizada
previousPeriod	PreviousPeriod	No	Datos del período anterior
rankProgress	number	Sí	Progreso hacia el siguiente rango (0-100)
Progreso del nivel	Número	Sí	Progreso hacia el siguiente nivel (0-100)
Posición del nivel	Posición del nivel	No	Posición dentro del nivel actual
Puntos hasta el siguiente nivel	Número	Sí	Puntos necesarios para alcanzar el siguiente nivel
Puntos hasta el siguiente rango	Número	Sí	Puntos necesarios para alcanzar el siguiente rango
Siguiente nivel	Nivel	No	Información del siguiente nivel
Siguiente rango	Rango	No	Información del siguiente rango
Puntos para mantener el rango	Número	No	Puntos necesarios para mantener el rango actual
Período comparativo de XP	Cadena	No	Período utilizado para la comparación de XP
Actividad de apuesta	Tipo de actividad de apuesta	No	Información de actividad de apuestas

Categoría

Interfaz para categorías de rango.

interfaz Categoría {
  _id: cadena;
  nombre: cadena;
}

Propiedad	Tipo	Requerido	Descripción
_id	cadena	Sí	Identificador único para la categoría
nombre	cadena	Sí	Nombre de categoría

Rango

Interfaz para los rangos de jugador.

interfaz Rango {
  _id: cadena;
  nombre: cadena;
  urlImagen: cadena;
  traducciones: RanksTranslation[];
}

Propiedad	Tipo	Requerido	Descripción
_id	cadena	Sí	Identificador único para el rango
nombre	cadena	Sí	Nombre de rango
urlImagen	cadena	Sí	URL de la imagen del rango
traducciones	RanksTranslation[]	Sí	Traducciones de la información de rango

Nivel

Interfaz para los niveles de jugador.

interfaz Nivel {
  _id: string;
  levelNumber: number;
}

Propiedad	Tipo	Requerido	Descripción
_id	Cadena	Sí	Identificador único para el nivel
Número de nivel	Número	Sí	Número de nivel

DatosDeCartera

Interfaz para información de la cartera del jugador.

interfaz DatosDeCartera {
  _id: string;
  balance: number;
  createdAt: string;
  updatedAt: string;
}

Propiedad	Tipo	Requerido	Descripción
_id	Cadena	Sí	Identificador único para la cartera
Saldo	Número	Sí	Saldo actual de la cartera
Creado en	Cadena	Sí	Fecha de creación
Actualizado en	Cadena	Sí	Fecha de la última actualización

RespuestaSimple

Interfaz genérica para respuestas simples.

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

Propiedad	Tipo	Requerido	Descripción
Correcto	Booleano	Sí	Si la operación tuvo éxito
Datos	T | null	Sí	Datos de respuesta (nulo para respuestas vacías)
Error	{ code: string; message: string; }	No	Información de error si la operación falló