Overview

Item actions improve game discoverability and engagement for HandCash users. It allows them to interact with the game from HandCash.

Examples

• Users have an item in their inventory that represents a box. They can redeem 20x game items from that box.
  • The box should get burned.
  • 20x new items should be created and sent to the user.
• Users can sell an item instantly to the game publisher for a fixed price.
  • The item should be sent to an account controlled by the game publisher.
  • The game publisher should send the expected amount to the user.
• An item that can evolve or mutate
  • The item should get burned.
  • A new item with the new state after the mutation should be created and sent to the user.

Full process

1. The developer defines the actions when creating a new item.
2. The action includes the fields: name, descriptionand url.
3. The action is displayed in HandCash along with the item.
4. The user decides to execute the action. At that point, the user authorizes the app to access their account.
5. The user gets redirected to the URL defined by action.url. The final URL includes the following query parameters:
   1. authToken: an auth token that grants permissions to the application. Check app permissions for more.
   2. itemOrigin: the unique reference in the blockchain for the item.

Developer process

 1. Create actions for the item

When creating a new item, you can define the actions attached to it:

const creationOrder = await handCashMinter.createItemsOrder({
  collectionId,
  items: [
    {
      user: "612cba70e108780b4f6817ad",
      name: "Mystery box",
      rarity: "Mythic",
      mediaDetails: {
        image: {
          url: "https://res.cloudinary.com/handcash-iae/image/upload/v1702398977/items/jyn2a2yqyepqhqi9p661.webp",
          imageHighResUrl: "https://res.cloudinary.com/handcash-iae/image/upload/v1702398977/items/jyn2a2yqyepqhqi9p661.png",
          contentType: "image/png"
        }
      },
      actions: [
        {
          name: "Open",
          description: "Redeem this box for 10x random items.",
          url: "https://mygame.com/actions/open"
        }
      ],
      quantity: 1,
    }
  ]
});

2. Capture the item action redirection

If your item actions are defined as https://mygame.com/actions/openthe user will be redirected to a URL with the following format: <https://mygame.com/actions/open?itemOrigin=<string>&authToken=<string>.

Capture the query parameters in your application domain so that you can execute your action.

3. Execute your custom action

At this point, you can leverage the HandCash Connect SDK using the authToken. Some of the options available are:

• Transfer items
• Craft and burn items
• Transfer money

You can also perform any custom action included by your game logic.