Módulo da Loja de Recompensas

O módulo da Loja de Recompensas fornece funcionalidade para interagir com o sistema da Loja de Recompensas do Gamanza Engage. Ele permite que os desenvolvedores recuperem produtos, façam pedidos, gerenciem assinaturas de disponibilidade de produtos e recuperem informações sobre pedidos.

Acessando o Módulo

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

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

Métodos

getAllProducts

Retorna uma lista paginada de produtos disponíveis na Loja de Recompensas com base nas preferências do jogador autenticado atual.

Assinatura:

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

Parâmetros

Nome	Tipo	Descrição
request	ProductFiltersRequest	Parâmetros de filtragem e paginação para a solicitação de produtos

Retornos

Tipo	Descrição
Promise<PaginationResponse<ProductType[]>>	Uma promessa que é resolvida para uma resposta paginada contendo uma matriz de produtos

Exemplo

// Busca a primeira página de produtos BÔNUS ativos para a lista da 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; verifique o tipo para direcionar regras de UI
  if (product.productEligibility.type === EligibilityType.QUICK_FILTERS) {
    // Exemplo: ler mensagens de erro de visibilidade por idioma
    const visibility = product.productEligibility.productVisibility;
    if (visibility.type === VisibilityType.QUICK_FILTERS) {
      visibility.errorMessages.forEach((m) => console.log(m.language, m.title));
    }
  }
});

getProductById

Obtém os detalhes de um produto específico por ID.

Assinatura:

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

Parâmetros

Nome	Tipo	Descrição
id	string	O identificador exclusivo do produto

Retornos

Tipo	Descrição
Promise<ProductType | null>	Uma promessa que é resolvida para os detalhes do produto ou nulo se não for encontrado

Exemplo

const produto = await sdk.RewardShop.getProductById("product-id-123");
if (!produto) {
  console.log("Produto não encontrado ou indisponível");
} else {
  console.log(produto.name, produto.reward);
  // Exemplo: verifique remainingItems/stock e elegibilidade
  const remaining = produto.remainingItems ?? produto.stock ?? 0;
  const elegivel =
    produto.productEligibility.type === EligibilityType.ALL_PLAYERS |
    (produto.productEligibility.type === EligibilityType.QUICK_FILTERS &&
      produto.productEligibility.isPlayerEligibility);
  console.log(`Restante: ${remaining} | Elegível: ${elegivel}`);
}

subscrevaParaDisponibilidadeDoProduto

Permite que um jogador seja assinante da lista de canais para ser notificado quando um produto que está esgotado ficar disponível novamente.

Assinatura:

subscrevaParaDisponibilidadeDoProduto(productId: string): Promise<SimpleResponse<null>>

Parâmetros

Nome	Tipo	Descrição
productId	string	O identificador único do produto para se inscrever

Retornos

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

Exemplo

const response = await sdk.RewardShop.subscrevaParaDisponibilidadeDoProduto("product-id-123");
if (response.ok) {
  console.log("Assinatura para disponibilidade do produto feita com sucesso");
}

isPlayerSubscribedToProductAvailability

Valida se o jogador já está assinante para receber notificações sobre o ID do produto referenciado.

Assinatura:

isPlayerSubscribedToProductAvailability(productId: string): Promise<SubscribedToProductAvailabilityResponse | null>

Parâmetros

Nome	Tipo	Descrição
productId	string	O identificador único do produto

Retornos

Tipo	Descrição
Promise<SubscribedToProductAvailabilityResponse | null>	Uma promessa que é resolvida em informações de assinatura ou nulo se não assinado

Exemplo

const subscription = await sdk.RewardShop.isPlayerSubscribedToProductAvailability("product-id-123");
if (subscription) {
  console.log(`Jogador está assinante desde ${subscription.createdAt}`);
}

playerPlaceRewardShopOrder

Permite que o jogador autenticado no momento compre um produto da Rewards Shop. Esta função permite que os jogadores façam um pedido na loja de recompensas.

Assinatura:

playerPlaceRewardShopOrder(productOrder: ProductOrderRequest): Promise<SimpleResponse<OrderProductType>>

Parâmetros

Nome	Tipo	Descrição
pedido de produto	SolicitaçãoDePedidoDeProduto	Os detalhes do pedido, incluindo o ID do produto, a quantidade, as informações de envio, etc.

Retornos

Tipo	Descrição
Promise<SimpleResponse<OrderProductType>>	Uma promessa que se resolve em uma resposta simples contendo o pedido criado ou um erro

Exemplo

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

O Gamanza Engage permite criar campos personalizados para o formulário de compra da Reward Shop. Esta função retorna a lista de campos personalizados disponíveis criados na interface administrativa.

Assinatura:

getOrderFormCustomFields(): Promise<RewardShopOrderFormCustomField[]>

Retornos

Tipo	Descrição
Promise<RewardShopOrderFormCustomField[]>	Uma promessa que se resolve em um array de campos personalizados para o formulário de pedidos

Exemplo

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

getPlayerOrders

Retorna uma lista paginada de pedidos feitos pelo jogador autenticado atual.

Assinatura:

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

Parâmetros

Nome	Tipo	Descrição
request	PlayerOrderFiltersType	Parâmetros de filtragem e paginação para a solicitação de pedidos

Retornos

Tipo	Descrição
Promise<PaginationResponse<OrderProductType[]>>	Uma promessa que se resolve em uma resposta paginada contendo um array de pedidos

Exemplo

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

Interfaces Relacionadas

ProductFiltersRequest

Estende a interface PaginationRequest com opções de filtragem adicionais para produtos.

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

PlayerOrderFiltersType

Estende a interface PaginationRequest com opções de filtragem adicionais para pedidos de jogadores.

interface PlayerOrderFiltersType extends PaginationRequest {
  status?: string;
  rewardType?: string;
  sortBy?: string;
}

Tipo de Produto

Representa um produto na Loja de Recompensas.

interface ProductType {
  _id: string;
  name: string;
  label?: string;
  description: string;
  tags: NameIdType[];
  translations: ProductTranslationType[];
  mobileImage: string;
  desktopImage: string;
  images?: ImagePreviewType[];
  reward: Reward;
  stock?: number;
  remainingItems?: number;
  ranks?: Omit<Rank, 'imageUrl'>[];
  /**
   * This step determines which players can purchase the Product from the Rewards Shop.
   * There will be 2 options available.
   */
  productEligibility: EligibilityMap[keyof EligibilityMap];
  status: GeneralStatusEnum;
  brands: unknown[];
  createdBy?: string;
  createdAt?: string;
  updatedAt?: string;
}

Tipo de Tradução de Produto

Representa o conteúdo localizado para um produto.

type ProductTranslationType = TranslationType & {
  longDescription?: string;
};

Opções de Visibilidade

Configuração usada quando o tipo de visibilidade é QUICK_FILTERS.

interface VisibilityOptions {
  type: VisibilityType;
  errorMessages: (Pick<TranslationType, 'language' | 'description'> & { title: string; })[];
  countries: {
    type: FilterRuleType;
    filters: { id: string; name: string; }[]; // ISO country code and human-readable name
  };
  ranks: {
    type: FilterRuleType;
    filters: (Pick<Rank, 'name'> & { id: string })[];
  };
}

Mapa de Visibilidade

Determina quais jogadores podem ver um produto na loja.

interface VisibilityMap {
  [VisibilityType.ALL_PLAYERS]: Pick<VisibilityOptions, 'errorMessages'> & {
    type: VisibilityType.ALL_PLAYERS;
  };
  [VisibilityType.QUICK_FILTERS]: VisibilityOptions & { type: VisibilityType.QUICK_FILTERS };
  [VisibilityType.ONLY_ELIGIBLE]: Pick<VisibilityOptions, 'errorMessages'> & {
    type: VisibilityType.ONLY_ELIGIBLE;
  };
}

Mapa de Elegibilidade

Define quais jogadores podem comprar o produto.

interface EligibilityMap {
  [EligibilityType.ALL_PLAYERS]: {
    type: EligibilityType.ALL_PLAYERS;
    isPlayerEligibility: boolean;
  };
  [EligibilityType.QUICK_FILTERS]: {
    type: EligibilityType.QUICK_FILTERS;
    isPlayerEligibility: boolean;
    countries: {
      type: FilterRuleType;
      filters: { id: string; name: string; }[];
    };
    ranks: {
      type: FilterRuleType;
      filters: (Pick<Rank, 'name'> & { id: string })[];
    };
    productVisibility: VisibilityMap[keyof VisibilityMap];
  };
}

Solicitação de Pedido de Produto

Representa a solicitação para colocar um pedido de um produto.

interface ProductOrderRequest {
  recipientName: string;
  playerLanguage: string;
  shippingAddress: ProductShippingAddressType;
  dateOfPurchase: string;
  itemId: string;
  quantity: number;
  comment: {
    comment: string;
    createdBy: string;
  };
  activation: boolean;
  playerPhone?: string;
  playerEmail?: string;
  customFields?: Record<string, string | number>;
}

Tipo de Produto de Pedido

Representa um pedido feito por um jogador.

interface OrderProductType extends Omit<ProductOrderRequest, 'activation' | 'comment'> {
  playerId: string;
  _id: string;
  activation?: boolean;
  status: string;
  comments: [
    {
      comment: string;
      createdBy: string;
      status?: string;
    },
  ];
  rewardType: RewardShopTypeEnum;
  dateOfPurchase: string;
  playerLanguage: string;
  price: {
    virtualCurrencyPrice: number;
    realMoneyPrice: number;
    currency: string;
  };
  quantity: number;
  recipientName: string;
  shippingAddress: ProductShippingAddressType;
  balanceRemainingItems: number;
  item: ProductType;
  balanceAfter: number;
  balanceBefore: number;
  playerRank: Pick<Rank, '_id' | 'name'>;
}

Tipo de Endereço de Entrega de Produto

Representa um endereço de entrega para um pedido de produto.

type ProductShippingAddressType = {
  streetNumber: string;
  street: string;
  city: string;
  zipCode: string;
  country: string;
  deliverInCasino: boolean;
  houseNameOrNumber?: string;
};

Campo Personalizado do Formulário de Pedido da Loja de Recompensas

Representa um campo personalizado para o formulário de pedido da Loja de Recompensas.

interface RewardShopOrderFormCustomField {
  type: string | number;
  required: boolean;
  key: string;
  fieldName: string;
  fieldDistribution: 'oneColumn' | 'twoColumns';
  display: {
    fieldDisplayName: string;
    helperText: string;
    language: string;
  }[];
}

Resposta de Assinatura da Disponibilidade de Produto

Representa a resposta ao verificar se um jogador está inscrito na disponibilidade do produto.

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

PaginationResponse

Uma interface genérica para respostas 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

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

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

RewardShopTypeEnum

Enum definindo os tipos de recompensas disponíveis na Reward Shop.

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

ProductListTypeEnum

Enum definindo os tipos de listas de produtos.

enum ProductListTypeEnum {
  SIDEBAR_SHOP = 'SIDEBAR_SHOP',
}