# Leaderboard SDK
***
> **BEFORE GETTING STARTED:** you must [authenticate with VIVERSE](https://docs.viverse.com/developer-tools/login-and-authentication-for-the-sdk) 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.
1. Go to the Upload section in the sidebar to open the "Manage Content" page in VIVERSE Studio.\\
2. Click "Upload Content" for the world you want to edit, then navigate to the SDK Settings tab, and click Add New Leaderboard.\
\
\\
3. 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](https://github.com/VIVERSE-DOCS/viverse-docs/blob/main/DeveloperTools/broken-reference/README.md).
```
// 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: "highScores", value: "100.0" },
{ name: "numberOfTimesPlayed", value: "60.0" }
];
const uploadLeaderboard = await globalThis.gameDashboardClient.uploadLeaderboardScore(appID, scores)
```
Or call `getLeaderboard()` to check scores:
// A valid leaderboardConfig example:
const leaderboardConfig = {
name: "highScores", // 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, leaderboardConfig);
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)`
Initializes a new Game Dashboard client instance.
| Parameter | Type | Description | Required |
| -------------------- | -------- | ----------------------------------------------------------------------------------- | -------- |
| `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)`
Uploads one or more scores to the leaderboard.
| Parameter | Type | Description | Required |
| --------- | -------------- | ------------------------------------------------- | -------- |
| `appID` | `string` | Your application's unique ID from VIVERSE Studio. | Yes |
| `scores` | `Array` | An array of `Score` objects to upload. | Yes |
**Score Object**
| Property | Type | Description |
| -------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `name` | `string` | The name of the leaderboard to upload the score to. This corresponds to the name configured in VIVERSE Studio. |
| `value` | `string` | The score value to upload. |
***
### `getLeaderboard(appID, config)`
Retrieves leaderboard data based on the provided configuration.
| Parameter | Type | Description | Required |
| --------- | -------- | ------------------------------------------------- | -------- |
| `appID` | `string` | Your application's unique ID from VIVERSE Studio. | Yes |
| `config` | `object` | A configuration object for the leaderboard query. | Yes |
**Leaderboard Config Object**
| Property | Type | Description |
| ------------- | --------- | --------------------------------------------------------------- |
| `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. |
***
### `getGuestLeaderboard(appID, config)`
Retrieves leaderboard data based on the provided configuration.
| Parameter | Type | Description | Required |
| --------- | -------- | ------------------------------------------------- | -------- |
| `appID` | `string` | Your application's unique ID from VIVERSE Studio. | Yes |
| `config` | `object` | A configuration object for the leaderboard query. | Yes |
**Leaderboard Config Object**
| Property | Type | Description |
| -------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `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"`. |
| `country_code` | `string` | The language of the leaderboard name. ISO 3166-1 alpha-2 country code, now is only support 'US' |
***
### Leaderboard Response Object
The `getLeaderboard` and `getGuestLeaderboard` methods returns a `Promise` that resolves to an object with the following structure.
| Property | Type | Description |
| ------------- | --------------------- | ---------------------------------------------------------- |
| `ranking` | `Array` | 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**
| Property | Type | Description |
| -------- | -------- | ----------------------------------- |
| `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**
| Property | Type | Description |
| -------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `app_id` | `string` | The application ID. |
| `meta_name` | `string` | The internal name of the leaderboard. |
| `display_name` | `Array
