The Inventory API enables developers to store, manage and access items for their games and allow players to unlock and/or purchase these items.
Items are created by developers in the developer dashboard (Edit game → APIs), and should consist of the following features:
There are two basic types of items: persistent items and consumables. While persistent items are singular and remain in the player’s inventory indefinitely, consumables will expire after use but can be stackable. This includes time based items, such as temporary access passes.
Currently, items will belong to a single game and can only be accessed from said game. At a later date, items could become independent of a single game and as such, be used across multiple games. There is no ETA for this functionality at the moment.
To create and manage catalogue items, navigate to the “APIs”-tab in the game-edit-screen in the developer dashboard. There you will need to set a name, ID, and Price for the item, and decide on one of the following types:
You will also be able to add a Model (absolute path), Class, Status (Active/Disabled) and set the item's expiration time in days (enter 0 to disable).
In order to get access to an item (or items) for testing purposes, without making it available in the catalog for the live version, a JSON configuration file of the inventory is provided via the Developer Dashboard, under the API tab.
Once downloaded, you can feed the configuration file to the sandbox SDK by using heyVR.inventory.mock().
All the features are accessible via the heyVR.inventory object. This object offers the following methods:
The following method allows developers to list all available items in the game. These items are set up via the Developer Dashboard. There you can set the various attributes as mentioned below.
heyVR.inventory.getCatalog() : Promise<Array<Catalog>>
Promise that resolve to the items available for purchase in the current game (Promise<Catalog>), or rejected in case of network failure.The Catalog interface structure is as follows:
interface Catalog {
'name': string;
'slug': string;
'description': string;
'price': number;
'price_discounted': number;
'model': string | null;
'thumbnail': string;
'type': 'singular' | 'stackable';
'item_class': string | null;
'expires_after': number;
}
An example of the output data will look like this:
[
{
"name": "Amazing Item #1",
"slug": "amazing_item_1",
"price": 100,
"price_discounted": 100,
"model": "models/amazing_item_1.glb",
"thumbnail": "/relative/path/to/thumbnail.jpg",
"type": "stackable",
"item_class": "optional item class 1",
"expires_after": 20
},
{
"name": "Amazing Item #2",
"slug": "amazing_item_2",
"price": 200,
"price_discounted": 100,
"model": "models/amazing_item_2.glb",
"thumbnail": null,
"type": "singular",
"item_class": "optional item class 2",
"expires_after": 0
}
]
The following method allows developers to list all the items owned by the user for the current game.
heyVR.inventory.get() : Promise<Array<OwnedItem>>
The OwnedItem interface will look like the following:
interface OwnedItem {
'name': string;
'slug': string;
'type': 'singular' | 'stackable';
'description': string;
'item_class': string | null;
'model': string | null;
'thumbnail': string | null;
'owned_count': number;
'acquired_at': string; // ISO 8601 datetime string
'expires_on' : string; // ISO 8601 datetime string
}
Promise that resolves to the items the current user owns for the current game. (Promise<Array<OwnedItem>>). The promise is rejected in case of network failure.Here's an example resultset of calling this method:
[
{
"name": "Amazing Item #1",
"slug": "amazing_item_1",
"description": "Amazing item's description",
"item_class": "class_1",
"thumbnail": "/relative/path/to/thumbnail.jpg",
"model": null,
"type": "singular",
"owned_count": 1,
"acquired_at": "2023-02-08T11:40:12.000000Z",
"expires_on": null,
},
{
"name": "Amazing Item #2",
"slug": "amazing_item_2",
"description": "Amazing item's description",
"item_class": "class_2",
"thumbnail": null,
"model": "models/amazing_item_2.glb",
"type": "stackable",
"owned_count": 20,
"acquired_at": "2023-03-09T03:44:26.000000Z",
"expires_on": "2023-06-09T03:44:26.000000Z",
}
]
The following method allows developers to execute an item sale on behalf of a user.
heyVR.inventory.purchase( item: string, count: number ) : Promise<string>
item: Required. It is the slug of the item the user wants to purchase.count: Optional. Number of items to purchase. Only applicable to stackable items.Promise that is resolved to a success message if the purchase is successful (Promise<string>), or rejected in case an error occurs.Catalog items have their own dedicated page on our platform's marketplace. You are encouraged to use the SDK to retrieve the full URL to an item's page, as the URL is subject to change at any time.
To get the URL to an item's page, you can call the method below:
heyVR.inventory.getItemURL( game: string, item: string ) : Promise<string>
game: Required. The slug of the game that this item belongs to, in case you want to promote your game's items within another game.item: Required. It is the slug of the item the user wants to get the URL of.Promise that is resolved to the item page's full URL, or rejected in case the item doesn't exist or there's a network failure.