RewardShop Module

The RewardShop module provides functionality for interacting with the Gamanza Engage Reward Shop system. It allows developers to retrieve products, place orders, manage product availability subscriptions, and retrieve order information.

Accessing the Module

The RewardShop module is accessible through the Gamanza Engage Web Client SDK:

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

Methods

getAllProducts

Returns a paginated list of products available in the RewardShop based on the current authenticated player preferences.

Signature:

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

Parameters

Name	Type	Description
request	ProductFiltersRequest	Filtering and pagination parameters for the products request

Returns

Type	Description
Promise<PaginationResponse<ProductType[]>>	A promise that resolves to a paginated response containing an array of products

Example

const products = await sdk.RewardShop.getAllProducts({
  page: 1,
  limit: 10,
  rewardType: [RewardShopTypeEnum.BONUS]
});

getProductById

Gets the details for a specific product by ID.

Signature:

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

Parameters

Name	Type	Description
id	string	The unique identifier of the product

Returns

Type	Description
Promise<ProductType | null>	A promise that resolves to the product details or null if not found

Example

const product = await sdk.RewardShop.getProductById("product-id-123");

subscribeToProductAvailability

Allows a player to be subscribed to the channel list to be notified when a product that is out of stock becomes available again.

Signature:

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

Parameters

Name	Type	Description
productId	string	The unique identifier of the product to subscribe to

Returns

Type	Description
Promise<SimpleResponse<null>>	A promise that resolves to a simple response indicating success or failure

Example

const response = await sdk.RewardShop.subscribeToProductAvailability("product-id-123");
if (response.ok) {
  console.log("Successfully subscribed to product availability");
}

isPlayerSubscribedToProductAvailability

Validates if the player is already subscribed to receive notifications about the referenced product ID.

Signature:

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

Parameters

Name	Type	Description
productId	string	The unique identifier of the product

Returns

Type	Description
Promise<SubscribedToProductAvailabilityResponse | null>	A promise that resolves to subscription information or null if not subscribed

Example

const subscription = await sdk.RewardShop.isPlayerSubscribedToProductAvailability("product-id-123");
if (subscription) {
  console.log(`Player is subscribed since ${subscription.createdAt}`);
}

playerPlaceRewardShopOrder

Allows the current authenticated player to purchase a Rewards Shop product. This function enables players to place an order in the reward shop.

Signature:

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

Parameters

Name	Type	Description
productOrder	ProductOrderRequest	The order details including product ID, quantity, shipping information, etc.

Returns

Type	Description
Promise<SimpleResponse<OrderProductType>>	A promise that resolves to a simple response containing the created order or an error

Example

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 allows creating custom fields for the Reward Shop purchase form. This function returns the list of available custom fields created in the Admin UI.

Signature:

getOrderFormCustomFields(): Promise<RewardShopOrderFormCustomField[]>

Returns

Type	Description
Promise<RewardShopOrderFormCustomField[]>	A promise that resolves to an array of custom fields for the order form

Example

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

getPlayerOrders

Returns a paginated list of orders placed by the current authenticated player.

Signature:

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

Parameters

Name	Type	Description
request	PlayerOrderFiltersType	Filtering and pagination parameters for the orders request

Returns

Type	Description
Promise<PaginationResponse<OrderProductType[]>>	A promise that resolves to a paginated response containing an array of orders

Example

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

Related Interfaces

ProductFiltersRequest

Extends the PaginationRequest interface with additional filtering options for products.

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

PlayerOrderFiltersType

Extends the PaginationRequest interface with additional filtering options for player orders.

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

ProductType

Represents a product in the Reward Shop.

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'>[];
  status: GeneralStatusEnum;
  brands: unknown[];
  createdBy?: string;
  createdAt?: string;
  updatedAt?: string;
}

ProductOrderRequest

Represents the request to place an order for a product.

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>;
}

OrderProductType

Represents an order placed by a player.

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'>;
}

ProductShippingAddressType

Represents a shipping address for a product order.

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

RewardShopOrderFormCustomField

Represents a custom field for the Reward Shop order form.

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

SubscribedToProductAvailabilityResponse

Represents the response when checking if a player is subscribed to product availability.

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

PaginationResponse

A generic interface for paginated responses.

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

A generic interface for simple responses with success/error status.

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

RewardShopTypeEnum

Enum defining the types of rewards available in the Reward Shop.

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

ProductListTypeEnum

Enum defining the types of product lists.

enum ProductListTypeEnum {
  SIDEBAR_SHOP = 'SIDEBAR_SHOP',
}