The Gameplay SDK provides a convenient way for developers to interact with our various Gameplay APIs that helps quickly integrate game enhancing functionality into your WebXR games.
Important Note!
If you're using NPM to manage your packages, take a look at this guide on how to use the SDK via NPM.
The Gameplay SDK currently includes the following features:
This document provides an overview of our Gameplay SDK, explains how to use it & handle positive responses, as well as how to handle promise rejections.
The gameplay SDK follows a version numbering scheme consisting of major, minor, and patch numbers. This scheme helps developers track changes and updates. The current version v1.0.0 indicates the first major release.
Developers do not have the option to choose the minor or patch version. Patches exclusively fix bugs, ensuring that a broken version is never selected over a fixed one. Games that worked with SDK x.0.y are guaranteed to work with SDK x.1.y, so there is no reason to choose the older version.
We automatically upgrade games to the latest version of the SDK, ensuring compatibility while respecting the selected major version, which may impact game functionality.
Release notes will be provided with all major releases of the gameplay SDK, that offer detailed information about the version change, new features, fixes and known introduced issues.
The Gameplay SDK is automatically deployed with your game. Everything is now available via the window.heyVR object.
Using NPM?
The following steps only apply to the built-in SDK. To learn how to use the NPM package, please checkout this guide.
We also provide a development version (sandbox) of the Game play SDK which functions offline and can be used in any local development environment.
The Sandbox Gameplay SDK closely mimics the behavior of the live Gameplay SDK, with the exception of server connections. This means that items and leaderboards created in the Developer Dashboard do not exist in the Sandbox environment. Additionally, certain methods that require user information and would result in a 403 error cannot be replicated.
The Sandbox Gameplay SDK offers several configuration options to simulate items (download the JSON configuration file for the items you created directly from the Developer Dashboard), leaderboards, user login status and the amount of coins owned by a user.
To make the sandbox SDK available to your game, simply include this like directly after the <head> element of your index.html file:
<script src="https://static.heyvr.io/sdk/heyvr/latest.sandbox.js"></script>
You can also download the latest sandbox SDK using this link and instead include the local URL in the
<script>tag.
The SDK will inject a global heyVR object into the window object of your iframe ( or main window if not in an iframe ). This object has the same signature as the actual SDK, with an additional key:
mock: {
config: ( config: SandboxConfigKeys ) => void;
import: ( config: SandboxData ) => void;
importURL: ( url: string ) => void;
inventory: ( config: SandboxConfigInventory ) => void;
leaderboard: ( config: SandboxConfigLeaderboard ) => void;
marketing: ( config: SandboxConfigMarketing ) => void;
saveGame: ( config: SandboxConfigSaveGame ) => void;
user: ( config: SandboxConfigUser ) => void;
}
You will mostly be only using the 1st and 2nd methods, unless you know exactly what you're doing.
Wonderland Engine automatically bundles every file in your project and outputs an automatically generated HTML file, which will not allow you to include the <script> tag. To get around this problem, you can follow these steps:
1- Download the sandbox SDK using the link provided above
2- Place the sandbox SDK in the static directory in your game project. The files inside this directory will not be automatically bundled by the Wonderland Engine.
3- Import the SDK in your game's main JavaScript file using one of the following:
If you're using CommonJS module system, e.g. you have "type"="commonjs" in your package.json file, or no type at all:
import heyVRSDK from './static/latest.sandbox.js';
or if you have the "type"="module" in your package.json file:
const heyVRSDK = require('./static/latest.sandbox.js');
You will only need to use the line above Once, in your main JavaScript file. Now, the SDK will be available to your game after the bundling, via the window.heyVR object.
Make sure to remove the heyVR sandbox SDK from your code before uploading your build to heyVR.
You can load a sample data in the sandbox SDK to be used for testing. To import the sample data, you have 2 options:
You can download a JSON object containing your actual game data from the developer area, under the "My Games > Select a game > APIs"
You can ownload the sandbox.json file from this link. Afterward, you can simply copy/paste the content of the data to your code, and assign it to a variable. Then you can provide this variable to the importConfig() method:
const configData = "The content of latest.sandbox.json goes here, without the quotes.";
heyVR.mock.import( configData );
After doing above, you should see a message in the console that indicates the successful importing of the sample data.
You can place the latest.sandbox.json file anywhere on your local or online server, and import it remotely:
heyVR.mock.importURL( 'https://your-server.test/path/to/sdk/latest.sandbox.json' );
You will again see a message in the console if everything goes fine or if any error occurs.
The rest of the methods are mostly used internally, so we won't be covering them here.
heyVR provides type definition for the entire SDK, which will greatly help with reducing bugs and faster development. To install the type definitions for heyVR SDK, you can run the following command in your project's directory:
npm install -D @heyvr/sdk-types
We assume that you've already installed Node.js and NPM on your system.
Before using the SDK, it's a good idea to check whether it's been loaded or not, specially if you're immediately calling the SDK on page load.
Once the SDK has finished loading, it will emit the heyVR.SDKLoaded event on the window object. Here's a full example of how to handle SDK loading:
const doStuff = () => {
// The SDK is loaded now.
// You can call any of its methods without further checks.
}
window.heyVR ?
doStuff() :
window.addEventListener( 'heyVR.SDKLoaded', doStuff );
This will make sure your script runs even if the event has already been triggered.
You can use the code above as many times as you need, but remember that the event is only triggered once on load, so make sure to use the full snippet instead of just listening to the event.
As most of the functionalities of the Gameplay SDK require API calls to the server, all functions return a Promise.
To access the actual return value, call the return-value's .then function and pass it the function that handles the actual return value.
Here's an example of how to use the SDK to get the user's amount of coins:
heyVR.user.getAmountCoins().then(
numCoins => {
// If the promise is resolved, it will always contain the expected data
coinDisplayComponent.set(numCoins);
}
).catch(
error => {
// Make sure to handle errors! An unhandled rejected Promise can crash the whole game!
// The error object always has the same structure, regardless of why the request failed.
console.error(error);
coinDisplayComponent.set("Couldn't load coins.");
}
);
In this example, we use the .getAmountCoins() function to retrieve the number of coins the user has.
The .then() function is then used to set the number of coins in the coinDisplayComponent.
This method always returns a promise that resolves with a number.
To ensure a great user experience, it's important to handle any errors that may occur when using the Gameplay SDK. The Promise you receive by calling a SDK-function may be rejected due to several reasons. No matter what the rejection reason was, the error object always has the following structure:
{
"status": {
"success": "false", // Boolean, Always false when an error occurs
"code": 403, // Number. The http response code for this error.
"debug": "...", // String. A unique machine-readable string for each error type.
"message": "..." // String. A human-readable string that explains the error.
},
"errors": [ ... ], // Array. If there are more than 1 error, this key will contain them.
"data": null // Data key is always present, but is always NULL if an error occurs.
}
The most common cause of a Promise being rejected is that the function requires the user to be logged in.
To prevent this, check whether the user is logged in beforehand by calling heyVR.user.isLoggedIn():
heyVR.user.isLoggedIn().then(
isLoggedIn=>{
if (isLoggedIn) {
heyVR.user.getName().then(
name => {
greetingComponent.set(`Welcome ${name}!`);
}
).catch(
error => {
// An unexpected error occurred
// Check error.debug to provide specific reactions.
greetingComponent.set('Welcome stranger!');
}
);
} else {
greetingComponent.set('Welcome stranger!');
}
}
);
In this example, we use the isLoggedIn() function to check whether the user is logged in. If the user is logged in, we retrieve their name using the getName() function and set the greeting component to display a welcome message with the user's name. If the user is not logged in, we set the greeting component to display a default welcome message.
Other reasons for a Promise being rejected include invalid parameters (e.g. trying to overwrite a savegame without passing overwrite=true or getting a leaderboard that doesn't exist) or the server connection being interrupted (e.g. the user's internet went down).
Make sure to handle these cases in a sensible manner by logging the error message and providing a default value.