The site has a new content architecture. We've added the ability to select your development device to show device-specific content. Please read our blog post Oculus Developer Center Update: Device-centric Documentation Architecture for more information.
All Oculus Quest developers MUST PASS the concept review prior to gaining publishing access to the Quest Store and additional resources. Submit a concept document for review as early in your Quest application development cycle as possible. For additional information and context, please see Submitting Your App to the Oculus Quest Store.
Leaderboards create competition and increase engagement among your users.
The Oculus Platform will manage your leaderboard data, and you can opt in to user-facing leaderboards, meaning a user can see their rank compared to friends and other users in the Oculus app. In addition, you can optionally choose to have notifications automatically generated when a user passes a friend’s leaderboard score. However, you will be responsible for displaying, reporting, and verifying the leaderboard data in your app.
The following image shows a user-facing leaderboard.
This page will walk you through how to create your global leaderboards, interact with the leaderboards service, and provide an example Unity implementation you can review or use as a leaderboard template.
The first step in adding leaderboards to your game is defining them in the developer dashboard. Navigate to Leaderboards and select the app that you would like to create a leaderboard for.
Select Create Leaderboard and enter the following information:
Select Submit when finished to save the leaderboard.
You can update leaderboard settings at any time in the Developer Center. You may also clear the results in a leaderboard and reset the scores.
To help increase engagement with your leaderboards, follow these best practices:
You can edit any of a leaderboard’s properties except its API Name. This means you can add translations and social feature after you have created it. To edit a leaderboard:
The following image shows an example of the Edit Leaderboard page.
Once you’re finished creating the achievements, you can begin to integrate them in your game. When calling the SDK methods in this section use the API Name you defined in the Developer Center.
Detail about each function can be found in the Platform SDK Reference Content.
Retrieves an array of leaderboard entries for a specified leaderboard.
Retrieves a list of entries starting after a rank that you define. For example, if you specify a list with an ‘afterRank’ of 10, you’ll get a list starting with the 11th position.
Retrieves the next group of leaderboard entries. This can be used to paginate the leaderboard data.
Retrieves the previous group of leaderboard entries. This can be used to paginate the leaderboard data.
This method will write a new leaderboard entry to a specified leaderboard for the current user. It is not an incremental update, it will overwrite the existing entry.
Use this method to get the total number of entries in the leaderboard so that you can show a users rank within the total number of entries. For example, use this method to display that a user is number 50 out of 200 entries.
To implement leaderboards, there are two different processes.
Retrieve and Display Leaderboards - Display the current leaderboard state before a game begins. For example,
ovr_Leaderboard_GetEntries for a native app . There are other methods you can use to get a subset of leaderboard entries based on input criteria.
Update Leaderboard Entries - Write the results of the current game to your leaderboard. For example,
ovr_Leaderboard_WriteEntry for a native app . A user may only have one entry on each leaderboard, subsequent entries will overwrite the existing entry on the specified leaderboard.
When implementing leaderboards, there are two common scenarios you should be aware of. They are:
LeaderboardStartAtenum to define where the values returned start or are centered. To retrieve only the current user, center on the viewer and limit results returned to 1.
LeaderboardFilterTypeenum to define the results returned.
You may need to manipulate a leaderboard from your trusted server. For details on leaderboard server-to-server APIs, see Leaderboard Server to Server APIs.