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.

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.

   
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.

// 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
}