Virtual Store #

The virtual store in Blocks and Cities by Kyoso Interactive.
The virtual store in Blocks and Cities by Kyoso Interactive.

A virtual store is a way for players to spend hard currency and/or soft currency to obtain consumables, collectables, or other items relevant in your gameplay. Hard currency can also be used to purchase soft currency.

The virtual store is defined in Hiro using a JSON file and can be configured to support a variety of purchase types, including single purchases and subscriptions. Offers can be configured to be available for a limited time, and can be configured to be available to players who have completed a specific level or have reached a specific score.

Purchase “intents” have been added to the server to allow you to disambiguate on a hard currency purchase between what the user wanted to buy if two store items share the same SKU code (possible with LiveOps configured for the game).

Customization Parameters #

The following JSON represents the customization parameters you can use to configure store items.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

{
  "store_items": {
    "<itemId1>": {
      "category": "<categoryName>",
      "cost": {
        "currencies": {},
        "sku": "com.example.item1"
      },
      "description": "The description for item one",
      "name": "Item one",
      "reward": {
        "guaranteed": {
          "currencies": {
            "gold": {
              "min": 100
            }
          },
          "items": {
            "hero_card": {
              "min": 1,
              "max": 5
            }
          }
        }
      },
      "additional_properties": {
        "<propertyName>": "value"
      },
      "disabled": false
    }
  }
}

This JSON is for the economy system configuration, but for the sake of this example, only shows store items.

PropertyTypeDescription
initialize_userInitializeUserThe currencies and items a user should start with when their account is created.
donationsstring:DonationA map of all donations.
store_itemsstring:StoreItemA map of all store items.
placementsstring:PlacementA map of all placements.
allow_fake_receiptsboolShould fake receipts be allowed? A receipt is fake if it contains the string: fake receipt.

Store Item #

PropertyTypeDescription
categorystringThe category that this store item belongs to.
costStoreItemCostThe item’s purchase cost.
descriptionstringThe description text for this store item.
namestringThe display-friendly name for this store item.
rewardRewardThe rewards that a user should receive once they purchase this store item.
additional_propertiesstring:stringA map of key value pairs that can contain additional context.
disabledboolUsed to make this item non-purchaseable and not return in queries.
unavailableboolUsed to make this item non-purchaseable but still return in queries.

Store Item Cost #

PropertyTypeDescription
currenciesstring:int64A map of currency IDs and quantities the user must pay to purchase this store item.
skustringThe SKU code of the in-app purchase the user must complete to obtain this store item.

Hard Currency Purchases #

Our Virtual Store supports Hard Currency payments from multiple store types. Currently we support:

  • Apple App Store
  • Google Play Store
  • Facebook Instant Games
  • Discord Store

Purchase Flow #

This is the typical flow when purchasing store items with hard currency. Check out the client pages for the specifics based on the engine you are using.

  1. The User selects an item from the game’s store UI that they wish to purchase.
  2. A Purchase Intent is registered to trigger the specific store provider’s purchasing display.
  3. When the purchase has been completed, a Receipt is returned to the client.
  4. The client can then send this Receipt to the server to try redeeming the in-game rewards from the purchase.
  5. Upon receiving the Receipt, the server will validate it with the specific store provider to make sure that it is legitimate.
  6. If successful, the server will then grant the reward(s) to the player.