Skip to main content
Version: 5.9.0

User Items

The User Items service, introduced in 4.2, is used to manage a collection of in-app items that users can be awarded, buy, sell, or trade (using virtual currency). Optionally, these items can be backed up to the blockchain.

Key concepts:

  • Items are first defined in the Item Catalog
  • Defined items can be purchased or awarded to users, where they will be recorded as userItem instances.
  • Using an item may consume it (or a portion of it - or none of it). Consumed items will automatically disappear from the user's user item inventory.
  • Using an item may trigger a status effect (i.e. invulnerability for 60 seconds)
  • Using an item may trigger a cool-down period (before the item can be used again) or a regeneration period (a period after which the item regenerates a "use.")

API Summary​

Read Items​

  • GetUserItem - Retrieves the identified user item from the server.
  • GetUserItemsPage - Retrieves the page of user's items from the server based on the context.
  • GetUserItemsPageOffset - Retrieves the page of user's items from the server based on the encoded context.
  • GetItemPromotionalDetails] - Returns list of promotional details for the specified item definition, for promotions available to the current user.
  • GetItemsOnPromotion - Returns list of promotional details for the specified item definition, for promotions available to the current user.

Affect Item Owner​

  • AwardUserItem - Allows item(s) to be awarded to a user without collecting the purchase amount.
  • AwardUserItemWithOptions - Allows item(s) to be awarded to a user without collecting the purchase amount, with additional options.
  • DropUserItem - Allows a quantity of a specified user item to be dropped, without any recovery of the money paid for the item.
  • SellUserItem - Allows a quantity of a specified user item to be sold.
  • GiveUserItemTo - Gifts item to the specified player.
  • ReceiveUserItemFrom - Retrieves and transfers the gift item from the specified player, who must have previously called giveUserItemTo.
  • PurchaseUserItem - Purchases a quantity of an item from the specified store, if the user has enough funds.
  • PurchaseUserItemWithOptions - Purchases a quantity of an item from the specified store, if the user has enough funds and purchasing for listed buy price is not disabled for associated catalog item definition.
  • SYS_AwardUserItemToUser - Client cloud code only Sys API to allow item(s) to be awarded to the applicable user without collecting the purchase amount. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.
  • SYS_AwardUserItem - Client cloud code only call to allow item(s) to be awarded to the session user without collecting the purchase amount. If includeDef is true, response includes associated itemDef with language fields limited to the current or default language.
  • OpenBundle - Allows a quantity of a specified bundle user item to be opened. Response indicates any items and currency awards configured for the associated bundle user item's BUNDLE type item definition, plus any 'items' awarded and any 'currencies' awarded, along with the resulting currency balances. If includeItemDef is true, the associated item definition will be included in the response for any user items awarded and for the bundle user item being opened (if any quantity of the bundle user item remains), with language fields limited to the current or default language.

Edit Item State​

Blockchain​

📄️ OpenBundle

Allows a quantity of a specified bundle user item to be opened. Response indicates any items and currency awards configured for the associated bundle user item's BUNDLE type item definition, plus any 'items' awarded and any 'currencies' awarded, along with the resulting currency balances. If includeItemDef is true, the associated item definition will be included in the response for any user items awarded and for the bundle user item being opened (if any quantity of the bundle user item remains), with language fields limited to the current or default language.

Last updated on by Jason Liang