Módulo de tienda de recompensas

El módulo de la tienda de recompensas proporciona funcionalidad para interactuar con el sistema de la tienda de recompensas de Gamanza Engage. Permite a los desarrolladores recuperar productos, realizar pedidos, administrar suscripciones de disponibilidad de productos y recuperar información de pedidos.

Acceder al módulo

El módulo de la tienda de recompensas se puede acceder a través del SDK del cliente web de Gamanza Engage:

const sdk = GamanzaEngageWebClientSDK.getInstance();
const rewardShop = sdk.RewardShop;

Métodos

getAllProducts

Devuelve una lista paginada de productos disponibles en la tienda de recompensas en función de las preferencias del jugador autenticado actual.

Firma:

getAllProducts(request: ProductFiltersRequest): Promise<PaginationResponse<ProductType[]>>

Parámetros

Nombre	Tipo	Descripción
request	ProductFiltersRequest	Parámetros de filtrado y paginación para la solicitud de productos

Devuelve

Tipo	Descripción
Promise<PaginationResponse<ProductType[]>>	Una promesa que se resuelve en una respuesta paginada que contiene una matriz de productos

Ejemplo

// Recuperar la primera página de productos activos BONUS para la lista de la barra lateral
const response = await sdk.RewardShop.getAllProducts({
  page: 1,
  limit: 12,
  listType: ProductListTypeEnum.SIDEBAR_SHOP,
  rewardType: [RewardShopTypeEnum.BONUS]
});

// PaginationResponse<ProductType[]>
console.log(response.page, response.totalPages);
response.docs.forEach((product) => {
  console.log(product._id, product.name, product.status);
  // productEligibility usa EligibilityMap; comprueba el tipo para impulsar las reglas de la IU
  if (product.productEligibility.type === EligibilityType.QUICK_FILTERS) {
    // Ejemplo: leer mensajes de error de visibilidad por idioma
    const visibility = product.productEligibility.productVisibility;
    if (visibility.type === VisibilityType.QUICK_FILTERS) {
      visibility.errorMessages.forEach((m) => console.log(m.language, m.title));
    }
  }
});

getProductById

Obtiene los detalles de un producto específico por ID.

Firma:

getProductById(id: string): Promise<ProductType | null>

Parámetros

Nombre	Tipo	Descripción
id	string	El identificador único del producto

Devuelve

Tipo	Descripción
Promise<ProductType | null>	Una promesa que se resuelve en los detalles del producto o nulo si no se encuentra

Ejemplo

const producto = await sdk.RewardShop.getProductById("product-id-123");
if (!producto) {
  console.log("Producto no encontrado o no disponible");
} else {
  console.log(producto.name, producto.reward);
  // Ejemplo: revisar remainingItems/stock y elegibilidad
  const remaining = producto.remainingItems ?? producto.stock ?? 0;
  const eligible =
    producto.productEligibility.type === EligibilityType.ALL_PLAYERS ||
    (producto.productEligibility.type === EligibilityType.QUICK_FILTERS &&
      producto.productEligibility.isPlayerEligibility);
  console.log(`Quedan: ${remaining} | Elegible: ${eligible}`);
}

suscribirse a la disponibilidad del producto

Permite que un jugador se suscriba a la lista de canales para ser notificado cuando un producto que está agotado vuelve a estar disponible.

Firma:

suscribirse a la disponibilidad del producto(idProducto: string): Promise<SimpleResponse<null>>

Parámetros

Nombre	Tipo	Descripción
idProducto	string	El identificador único del producto al que suscribirse

Devuelve

Tipo	Descripción
Promise<SimpleResponse<null>>	Una promesa que se resuelve en una respuesta simple que indica éxito o fracaso

Ejemplo

const response = await sdk.RewardShop.suscribirse a la disponibilidad del producto("product-id-123");
if (response.ok) {
  console.log("Suscripción a la disponibilidad del producto exitosa");
}

¿El jugador está suscrito a la disponibilidad del producto

Valida si el jugador ya está suscrito para recibir notificaciones sobre el ID de producto de referencia.

Firma:

¿El jugador está suscrito a la disponibilidad del producto?(idProducto: string): Promise<SubscribedToProductAvailabilityResponse | null>

Parámetros

Nombre	Tipo	Descripción
idProducto	string	El identificador único del producto

Devuelve

Tipo	Descripción
Promise<SubscribedToProductAvailabilityResponse | null>	Una promesa que se resuelve en información de suscripción o nulo si no está suscrito

Ejemplo

const subscription = await sdk.RewardShop.¿El jugador está suscrito a la disponibilidad del producto?("product-id-123");
if (subscription) {
  console.log(`El jugador está suscrito desde ${subscription.createdAt}`);
}

el jugador realiza un pedido en la tienda de recompensas

Permite al jugador autenticado actual comprar un producto de la tienda de recompensas. Esta función permite a los jugadores realizar un pedido en la tienda de recompensas.

Firma:

el jugador realiza un pedido en la tienda de recompensas(pedidoProducto: ProductOrderRequest): Promise<SimpleResponse<OrderProductType>>

Parámetros

Nombre	Tipo	Descripción
pedido de producto	Solicitud de orden de compra	Los detalles del pedido, incluidos el ID del producto, la cantidad, la información de envío, etc.

Devoluciones

Tipo	Descripción
Promise<SimpleResponse<OrderProductType>>	Una promesa que se resuelve en una respuesta simple que contiene el pedido creado o un error

Ejemplo

const order = await sdk.RewardShop.playerPlaceRewardShopOrder({
  recipientName: "John Doe",
  playerLanguage: "en",
  shippingAddress: {
    streetNumber: "123",
    street: "Main St",
    city: "New York",
    zipCode: "10001",
    country: "USA",
    deliverInCasino: false
  },
  dateOfPurchase: new Date().toISOString(),
  itemId: "product-id-123",
  quantity: 1,
  comment: {
    comment: "Please deliver ASAP",
    createdBy: "player"
  },
  activation: true
});

getOrderFormCustomFields

Gamanza Engage permite crear campos personalizados para el formulario de compra de la Tienda de Recompensas. Esta función devuelve la lista de campos personalizados disponibles creados en la interfaz de administración.

Firma:

getOrderFormCustomFields(): Promise<RewardShopOrderFormCustomField[]>

Devoluciones

Tipo	Descripción
Promise<RewardShopOrderFormCustomField[]>	Una promesa que se resuelve en una matriz de campos personalizados para el formulario de pedido

Ejemplo

const customFields = await sdk.RewardShop.getOrderFormCustomFields();

getPlayerOrders

Devuelve una lista paginada de pedidos realizados por el jugador autenticado actual.

Firma:

getPlayerOrders(request: PlayerOrderFiltersType): Promise<PaginationResponse<OrderProductType[]>>

Parámetros

Nombre	Tipo	Descripción
solicitud	PlayerOrderFiltersType	Parámetros de filtrado y paginación para la solicitud de pedidos

Devoluciones

Tipo	Descripción
Promise<PaginationResponse<OrderProductType[]>>	Una promesa que se resuelve en una respuesta paginada que contiene una matriz de pedidos

Ejemplo

const orders = await sdk.RewardShop.getPlayerOrders({
  page: 1,
  limit: 10,
  status: "completed"
});

Interfaces relacionadas

ProductFiltersRequest

Extiende la interfaz PaginationRequest con opciones de filtrado adicionales para los productos.

interface ProductFiltersRequest extends Omit<PaginationRequest, 'sortBy'> {
  rewardType?: RewardShopTypeEnum[];
  listType?: ProductListTypeEnum;
}

PlayerOrderFiltersType

Extiende la interfaz PaginationRequest con opciones de filtrado adicionales para los pedidos de los jugadores.

interfaz PlayerOrderFiltersType extiende PaginationRequest {
  status?: string;
  rewardType?: string;
  sortBy?: string;
}

TipoDeProducto

Representa un producto en la Tienda de Recompensas.

interfaz TipoDeProducto {
  _id: string;
  name: string;
  label?: string;
  description: string;
  tags: NameIdType[];
  translations: TipoDeTranslacionDeProducto[];
  imagenMóvil: string;
  imagenDePc: string;
  images?: TipoDePrevisualización[];
  recompensa: Recompensa;
  stock?: number;
  itemsRestantes?: number;
  ranks?: Omitir<Rango, 'imageUrl'>[];
  /**
   * Este paso determina qué jugadores pueden comprar el Producto de la Tienda de Recompensas.
   * Habrá 2 opciones disponibles.
   */
  eligibilidadDeProducto: ElegibilidadMap[keyof ElegibilidadMap];
  status: TipoDeStatusGeneral;
  brands: unknown[];
  creadoPor?: string;
  creadoEn?: string;
  actualizadoEn?: string;
}

TipoDeTranslacionDeProducto

Representa el contenido localizado de un producto.

type TipoDeTranslacionDeProducto = TipoDeTranslacion & {
  descripcionLarga?: string;
};

OpcionesDeVisibilidad

Configuración utilizada cuando el tipo de visibilidad es QUICK_FILTERS.

interfaz OpcionesDeVisibilidad {
  type: TipoDeVisibilidad;
  mensajesDeError: (Pick<TipoDeTranslacion, 'language' | 'description'> & { title: string; })[];
  paises: {
    type: TipoDeReglaDeFiltro;
    filters: { id: string; name: string; }[]; // Código ISO del país y nombre legible por humanos
  };
  ranks: {
    type: TipoDeReglaDeFiltro;
    filters: (Pick<Rango, 'name'> & { id: string })[];
  };
}

MapaDeVisibilidad

Determina qué jugadores pueden ver un producto en la tienda.

interfaz MapaDeVisibilidad {
  [TipoDeVisibilidad.ALL_PLAYERS]: Pick<OpcionesDeVisibilidad, 'errorMessages'> & {
    type: TipoDeVisibilidad.ALL_PLAYERS;
  };
  [TipoDeVisibilidad.QUICK_FILTERS]: OpcionesDeVisibilidad & { type: TipoDeVisibilidad.QUICK_FILTERS };
  [TipoDeVisibilidad.ONLY_ELIGIBLE]: Pick<OpcionesDeVisibilidad, 'errorMessages'> & {
    type: TipoDeVisibilidad.ONLY_ELIGIBLE;
  };
}

MapaDeElegibilidad

Define qué jugadores pueden comprar el producto.

interfaz MapaDeElegibilidad {
  [TipoDeElegibilidad.ALL_PLAYERS]: {
    type: TipoDeElegibilidad.ALL_PLAYERS;
    isPlayerEligibility: boolean;
  };
  [TipoDeElegibilidad.QUICK_FILTERS]: {
    type: TipoDeElegibilidad.QUICK_FILTERS;
    isPlayerEligibility: boolean;
    países: {
      type: TipoDeReglaDeFiltro;
      filters: { id: string; name: string; }[];
    };
    ranks: {
      type: TipoDeReglaDeFiltro;
      filters: (Pick<Rango, 'name'> & { id: string })[];
    };
    visibilidadDeProducto: MapaDeVisibilidad[keyof MapaDeVisibilidad];
  };
}

SolicitudDeOrdenDeProducto

Representa la solicitud para colocar una orden de un producto.

interfaz SolicitudDeOrdenDeProducto {
  nombreDelDestinatario: string;
  idiomaDeljugador: string;
  direccionDeEnvío: TipoDeAgregarDeDireccionDeEnvioDeProducto;
  fechaDeCompra: string;
  idDelElemento: string;
  cantidad: number;
  comentario: {
    comentario: string;
    creadoPor: string;
  };
  activación: boolean;
  teléfonoDelJugador?: string;
  emailDelJugador?: string;
  camposPersonalizados?: Record<string, string | number>;
}

TipoDeOrdenDeProducto

Representa una orden realizada por un jugador.

interfaz TipoDeOrdenDeProducto extiende Omitir<SolicitudDeOrdenDeProducto, 'activación' | 'comentario'> {
  idDelJugador: string;
  _id: string;
  activación?: boolean;
  status: string;
  comentarios: [
    {
      comentario: string;
      creadoPor: string;
      status?: string;
    },
  ];
  tipoDeRecompensa: TipoDeEnumDetiendaDeRecompensas;
  fechaDeCompra: string;
  idiomaDeljugador: string;
  precio: {
    precioEnDivisaVirtual: number;
    precioEnDineroFísico: number;
    moneda: string;
  };
  cantidad: number;
  nombreDelDestinatario: string;
  direcciónDeEnvío: TipoDeAgregarDeDireccionDeEnvioDeProducto;
  itemsRestantesDeBalance: number;
  item: TipoDeProducto;
  balanceDespués: number;
  balanceAnterior: number;
  rangoDeljugador: Pick<Rango, '_id' | 'name'>;
}

TipoDeAgregarDeDireccionDeEnvioDeProducto

Representa una dirección de envío para una orden de producto.

type TipoDeAgregarDeDireccionDeEnvioDeProducto = {
  númeroDeCalle: string;
  calle: string;
  ciudad: string;
  codigoPostal: string;
  país: string;
  entregarEnCasino: boolean;
  nombreONumeroDeCasa?: string;
};

CampoPersonalizadoDeFormularioDeOrdenDetiendaDeRecompensas

Representa un campo personalizado para el formulario de orden de la Tienda de Recompensas.

interfaz CampoPersonalizadoDeFormularioDeOrdenDetiendaDeRecompensas {
  type: string | number;
  required: boolean;
  key: string;
  nombreDelCampo: string;
  distribuciónDelCampo: 'oneColumn' | 'twoColumns';
  display: {
    nombreDelCampoDeVisualización: string;
    textoDeAyuda: string;
    language: string;
  }[];
}

RespuestaDeHaberSuscritosADisponibilidadDeProducto

Representa la respuesta al comprobar si un jugador está suscrito a la disponibilidad del producto.

interface SubscribedToProductAvailabilityResponse {
  createdAt: string;
  itemId: string;
  playerId: string;
  _id: string;
}

PaginationResponse

Una interfaz genérica para respuestas paginadas.

interface PaginationResponse<T> {
  docs: T;
  hasNextPage: boolean;
  hasPrevPage: boolean;
  limit: number;
  nextPage: number;
  page: number;
  pagingCounter: number;
  prevPage: number | null;
  totalDocs: number;
  totalPages: number;
}

SimpleResponse

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

interface SimpleResponse<T> {
  ok: boolean;
  error?: ErrorResponse;
  data: T | null;
}

RewardShopTypeEnum

Enum que define los tipos de recompensas disponibles en la Tienda de Recompensas.

enum RewardShopTypeEnum {
  BONUS = 'bonus',
  BOOSTER = 'booster',
  EXTERNAL = 'external_product',
  XP = 'xp',
  PRIZESHARK = 'prizeshark',
}

ProductListTypeEnum

Enum que define los tipos de listas de productos.

enum ProductListTypeEnum {
  SIDEBAR_SHOP = 'SIDEBAR_SHOP',
}