Meta Developers

The Leaderboards API provides a way to manage and interact with leaderboards in your application. The API allows you to retrieve information about a single leaderboard, write entries to a leaderboard, and retrieve blocks of leaderboard entries based on different criterias. Leaderboard-integrated apps get Challenges for free, accessible through the Scoreboards UI. Visit our website for more information about leaderboards.

Static Member Functions

static Request< Models.LeaderboardEntryList > GetNextEntries

( Models.LeaderboardEntryList list )

static Request< Models.LeaderboardEntryList > GetPreviousEntries

( Models.LeaderboardEntryList list )

static Request< Models.LeaderboardList > Get

( string leaderboardName )

Retrieves detailed information for a single leaderboard with a specified name, returning an array of Models.Leaderboard.

Parameters

leaderboardName

The name of the leaderboard to retrieve.

static Request< Models.LeaderboardEntryList > GetEntries

( string leaderboardName,

int limit,

LeaderboardFilterType filter,

LeaderboardStartAt startAt )

Retrieves a list of leaderboard entries for a specified leaderboardName, with options to filter and limit the number of results returned.

Parameters

leaderboardName

The name of the leaderboard from which to retrieve entries.

limit

Specifies the maximum number of entries to be returned.

filter

By using ovrLeaderboard_FilterFriends, this allows you to filter the returned values to bidirectional followers.

startAt

Defines whether to center the query on the user or start at the top of the leaderboard.

Error codes

100: Parameter {parameter}: invalid user id: {user_id}
100: Something went wrong.
12074: You're not yet ranked on this leaderboard.

static Request< Models.LeaderboardEntryList > GetEntriesAfterRank

( string leaderboardName,

int limit,

ulong afterRank )

Retrieves a block of leaderboard entries starting from a specific rank.

Parameters

leaderboardName

The name of the leaderboard from which to retrieve entries.

limit

The maximum number of entries to return.

afterRank

The position after which to start. For example, 10 returns leaderboard results starting with the 11th user.

static Request< Models.LeaderboardEntryList > GetEntriesByIds

( string leaderboardName,

int limit,

LeaderboardStartAt startAt,

UInt64 [] userIDs )

Retrieves a block of leaderboard entries that match the specified user IDs. Only entries corresponding to the provided user IDs will be returned.

Parameters

leaderboardName

The name of the leaderboard from which to retrieve entries.

limit

The maximum number of entries to return.

startAt

Defines whether to center the query on the user or start at the top of the leaderboard. If this is LeaderboardStartAt.CenteredOnViewer or LeaderboardStartAt.CenteredOnViewerOrTop, then the current user's ID will be automatically added to the query.

userIDs

Defines a list of user ids to get entries for.

static Request< bool > WriteEntry

( string leaderboardName,

long score,

byte [] extraData,

bool forceUpdate )

Writes a single entry to the leaderboard, returning Models.LeaderboardUpdateStatus indicating whether the update was successful and providing the updated challenge IDs.

Parameters

leaderboardName

The name of the leaderboard to which the entry should be written.

score

The score to be written in the leaderboard.

extraData

A 2KB custom data field that is associated with the leaderboard entry. This can be a game replay or any additional information that provides more context about the entry for the viewer.

forceUpdate

If true, the score always updates. This happens even if it is not the user's best score.

Error codes

100: Parameter {parameter}: invalid user id: {user_id}
100: Something went wrong.
100: This leaderboard entry is too late for the leaderboard's allowed time window.

static Request< bool > WriteEntryWithSupplementaryMetric

( string leaderboardName,

long score,

long supplementaryMetric,

byte [] extraData,

bool forceUpdate )

Writes a single entry to a leaderboard which can include supplementary metrics, returning Models.LeaderboardUpdateStatus indicating whether the update was successful and providing the updated challenge IDs.

Parameters

leaderboardName

The name of the leaderboard to which the entry should be written.

score

The score to be written in the leaderboard.

supplementaryMetric

Supplemental piece of data that can be used for tiebreakers.

extraData

A 2KB custom data field that is associated with the leaderboard entry. This can be a game replay or any additional information that provides more context about the entry for the viewer.

forceUpdate

If true, the score always updates. This happens even if it is not the user's best score.

Error codes

100: Parameter {parameter}: invalid user id: {user_id}
100: Something went wrong.
100: This leaderboard entry is too late for the leaderboard's allowed time window.

static Request< Models.LeaderboardList > GetNextLeaderboardListPage

( Models.LeaderboardList list )

Did you find this page helpful?