The Leaderboard API enables developers to create and manage leaderboards for their games, which allows players to compete with each other and compare their scores.
The Leaderboard API provides several ways for accessing, creating, modifying and deleting leaderboards, highscores, and user-specific data, as needed.
To create and manage the leaderboards, navigate to the “APIs”-tab in the game-edit-screen in the developer dashboard. There you will need to set a name, ID and reset interval for the leaderboard, and decide on one of the following types:
All the features are accessible via the heyVR.leaderboard object. This object offers the following methods:
The following method allows developers to retrieve score data from a specific leaderboard.
heyVR.leaderboard.get(
id: string,
numScores: number,
page: number
) : Promise<Array<Score>>
The Score interface will consist of the following data:
interface Score {
user: string;
rank: number;
score: number;
created_at: string; // ISO 8601 datetime string
}
id: Required. The ID of the leaderboard. You will set this ID yourself when creating a new leaderboard via the Developer Dashboard. Required.numScores: The number of scores you want to retrieve. Defaults to 10 if left empty.page: Used for pagination. If provided, it will set the number of page of the resultset.Promise that resolve to the scores on the leaderboard (Promise<Array<Score>>), or rejected if the leaderboard does not exist.An example output will look like the following:
[
{
"rank": 1,
"score": 123,
"user": "Username1",
"created_at": "2023-03-09T03:44:26.000000Z"
},
{
"rank": 2,
"score": 120,
"user": "Username2",
"created_at": "2023-02-08T02:25:12.000000Z"
}
]
The following method allows developers to retrieve score data from the current user and the scores around. Effectively a snippet of the leaderboard centered on the current user.
heyVR.leaderboard.getMy(id:string , numScores: number) : Promise<Array<Score>>
id: Required. The ID of the leaderboard. You will set this ID yourself when creating a new leaderboard via the Developer Dashboard.numScores: The number of scores you want to retrieve. Defaults to 10 if not provided.heyVR.leaderboard.get() if not on the leaderboard yet. (Promise<Array<Score>>). THe promise is rejected in case of network errors.An example output will look like the following if the numScores is set to 3:
[
{
"rank": 15,
"score": 130,
"user": "Username1",
"created_at": "2023-03-09T03:44:26.000000Z"
},
{
"rank": 16,
"score": 100,
"user": "Username2", // Currently authenticated user
"created_at": "2023-02-08T02:25:12.000000Z"
},
{
"rank": 17,
"score": 70,
"user": "Username3",
"created_at": "2023-01-02T12:30:07.000000Z"
},
]
The following method allows developers to submit a users score to an existing leaderboard.
heyVR.leaderboard.postScore(id: string, score: number) : Promise<boolean>
id: Required. The ID of the leaderboard. You will set this ID yourself when creating a new leaderboard via the Developer Dashboard.score: The score the user just achieved (must be integer! Multiply by e.g. 100 if you need floats)Promise that is resolved when the score was successfully submitted, and whether it was better than the previous score. (Promise<boolean>). The promise is rejected in case an error occurs.