Leaderboard SDK
Track high scores and other ranked data with the VIVERSE Leaderboard SDK
BEFORE GETTING STARTED: you must authenticate with VIVERSE before requesting leaderboard services.
Leaderboard Setup in VIVERSE Studio
Before integrating the Leaderboard SDK, you must first configure the leaderboard metadata settings for your content in VIVERSE Studio.
Go to the Upload section in the sidebar to open the "Manage Content" page in VIVERSE Studio.\
Click "Upload Content" for the world you want to edit, then navigate to the SDK Settings tab.\
In the Leaderboard Configuration section, define the necessary leaderboard parameters. This configuration is required to enable proper interaction between your content and the leaderboard system.\
Game Dashboard Client Setup
To then make use of your VIVERSE Leaderboard, you must instantiate the gameDashboardClient
after authentication.
// If the user is logged in, get the token; if not, return `undefined`
const accessToken = await globalThis.viverseClient.getToken();
// initialize game dashboard client instance
globalThis.gameDashboardClient = new globalThis.viverse.gameDashboard({
baseURL: 'https://www.viveport.com/',
communityBaseURL: 'https://www.viverse.com/',
token: accessToken
});
Then call uploadLeaderboardScore()
to change leaderboard data:
// Can upload multiple leaderboard scores at once
const scores = [
{ name: "high_scores", value: "100.0" },
{ name: "number_of_times_played", value: "60.0" }
];
const uploadLeaderboard = await globalThis.gameDashboardClient.uploadLeaderboardScore(appID, scores)
Or call getLeaderboard()
to check scores:
// A valid leaderboardConfig example:
const leaderboardConfig = {
name: "high_scores", // string
range_start: 0, // number, show number of users beyond user's rank
range_end: 100, // number, show number of users below user's rank
region: "global", // string, get by local/global
time_range: "alltime",
around_user: false
};
const leaderboard = await globalThis.gameDashboardClient.getLeaderboard(appID, config);
The response will be formatted like so, which you can integrate into your game's UI and logic:
{
ranking: [
{
uid: string,
name: string,
value: number, // the score or stored data
rank: number, // the rank of the user's score
}
],
meta: {
app_id: string,
meta_name: string,
display_name: [
{
lang: string,
name: string
}
],
sort_type: number,
update_type: number,
data_type: number,
},
total_count: number
}
API Reference
new viverse.gameDashboard(options)
new viverse.gameDashboard(options)
Initializes a new Game Dashboard client instance.
options
object
An object containing configuration for the client.
Yes
↳ baseURL
string
The base URL for the Viveport API. Should be https://www.viveport.com/
.
Yes
↳ communityBaseURL
string
The base URL for the VIVERSE community API. Should be https://www.viverse.com/
.
Yes
↳ token
string
The access token obtained from the VIVERSE client. Required for user-specific data.
Yes
uploadLeaderboardScore(appID, scores)
uploadLeaderboardScore(appID, scores)
Uploads one or more scores to the leaderboard.
appID
string
Your application's unique ID from VIVERSE Studio.
Yes
scores
Array<Score>
An array of Score
objects to upload.
Yes
Score Object
name
string
The name of the leaderboard to upload the score to. This corresponds to the meta_name
configured in VIVERSE Studio.
value
string
The score value to upload.
getLeaderboard(appID, config)
getLeaderboard(appID, config)
Retrieves leaderboard data based on the provided configuration.
appID
string
Your application's unique ID from VIVERSE Studio.
Yes
config
object
A configuration object for the leaderboard query.
Yes
Leaderboard Config Object
name
string
The name of the leaderboard to retrieve.
range_start
number
The starting rank for the query.
range_end
number
The ending rank for the query.
region
string
The region for the leaderboard. Can be "global"
or "local"
.
time_range
string
The time range for the leaderboard. e.g., "alltime"
.
around_user
boolean
Whether to fetch ranks around the current user.
Leaderboard Response Object
The getLeaderboard
method returns a Promise
that resolves to an object with the following structure.
ranking
Array<RankingEntry>
An array of objects representing the leaderboard rankings.
meta
object
Metadata about the leaderboard.
total_count
number
The total number of entries in the leaderboard.
RankingEntry Object
uid
string
The unique ID of the user.
name
string
The display name of the user.
value
number
The user's score.
rank
number
The user's rank in the leaderboard.
Meta Object
app_id
string
The application ID.
meta_name
string
The internal name of the leaderboard.
display_name
Array<object>
An array of display names for different languages.
↳ lang
string
The language code (e.g., "en-US"
).
↳ name
string
The display name in the specified language.
sort_type
number
The method used for sorting scores (e.g., ascending, descending).
update_type
number
The rule for updating scores (e.g., keep highest, latest).
data_type
number
The data type of the score value.
Last updated
Was this helpful?