Skip to main content
Version: 5.7.0

Leaderboard

Leaderboards are key for building communities around your application. A leaderboard is an aggregation of player scores. Leaderboards are retrieved, assembled, and sorted on the server. brainCloud provides fast real-time access to leaderboards.

Multiple leaderboards can be configured for the application. Leaderboards can be configured as to how posted scores will be handled (e.g. player's highest score only, accumulate player's score, current posting, …) and how the leaderboard resets (daily, weekly, monthly, yearly, or not at all).

Leaderboards can be viewed from a global perspective or a social perspective. The global perspective comprises the entire leaderboard with an order imposed on it. Each posted score will have a zero-based index and a one-based rank based on the imposed order. The social perspective comprises a subset of the overall leaderboard consisting of the player, the player's friends, and the pacers configured for the leaderboard.

Leaderboard tournaments are supported and are applied to the social perspective after the leaderboard resets.

Pacers provide a set of "pseudo-friends" with pre-defined scores for the social leaderboard perspective and are useful for motivating players at the beginning of the reset period (before enough new scores have been posted).

There are five categories of leaderboard APIs:

  • those relating to leaderboard score postings
  • those for retrieving a player's social leaderboard
  • those for retrieving global leaderboard entries
  • those for retrieving historical versions of global leaderboards
  • those relating to tournaments

Note that brainCloud also supports the concept of dynamically created leaderboards – which are leaderboards that are created on the fly via client code, instead of ahead-of-time via the design portal. Dynamic leaderboards can be useful if your game has a leaderboard for each level, and has so many levels that datafilling them via the tool would be cumbersome!

The leaderboard APIs are detailed below in order of the categories list above.

Valid sort keys for the retrieval APIs:

  • "HIGH_TO_LOW" – returns leaderboard entries in standard order (high scores at the top, lower scores at the bottom)
  • "LOW_TO_HIGH" – returns leaderboard entries in reverse order (lower scores at the top, higher scores at the bottom)

Keys for posting to dynamic leaderboards:

  • Leaderboard type – defines how the leaderboard will behave and be interpreted.

    • "HIGH_VALUE" – player's score is posted only if it is higher than the player's previously posted score
    • "LOW_VALUE" – player's score is posted only if it is lower than the player's previously posted score
    • "CUMULATIVE" – player's score is added to the player's previously posted score
    • "LAST_VALUE" – player's score replaces the player's previously posted score
    • "ARCADE_LOW" – multiple player's scores are allowed to post and ranked in ascending order (i.e. lower scores are better)
    • "ARCADE_HIGH" – multiple player's scores are allowed to post and ranked in descending order (i.e. higher scores are better)

  • Rotation type – defines when the leaderboard will reset. At reset, the leaderboard becomes the most recent retained version.

    • "NEVER" – leaderboard does not reset (i.e. perpetual)
    • "DAILY" – leaderboard resets once per day at the defined reset timestamp
    • "WEEKLY" – leaderboard resets once per week at the defined reset timestamp
    • "MONTHLY" – leaderboard resets once per month at the defined reset timestamp
    • "YEARLY" – leaderboard resets once per year at the defined reset timestamp

  • Rotation reset – Timestamp at which the leaderboard will next reset. The reset timestamp is applicable only to a leaderboard that has been configured to reset (i.e. rotation types other than "NEVER"). The timestamp is specified as a formatted - string and can be provided in either of two formats: "dd-MM-yyyy" or "dd-MM-yyyy HH:mm" (note: all numeric digits).

  • Retained count – the number of leaderboard versions (including the current leaderboard) that will be retained (e.g. set to 1 will keep only the current period's leaderboard). The maximum is 8, which will keep the current period's leaderboard, - plus the 7 previous periods' leaderboards. Retained count is only applicable to a leaderboard that resets.

Notes regarding the data returned by the leaderboard calls:

  • timeBeforeReset – returns the time until the next leaderboard reset in milliseconds.

API Summary​

Global Leaderboard Views​

Social Leaderboard Views​

Posting Scores​

Group Leaderboards​

Leaderboard Managerment​

  • ListAllLeaderboards - retrieves a list of all leaderboards
  • CreateLeaderboard - creates a leaderboard
  • EditLeaderboard - updates a leaderboard
  • DeleteLeaderboards - deletes a leaderboard
  • SysResetNeverLeaderboard - manually reset a never-rotating leaderboard
  • SysCreateLeaderboard - Create a new player or group entry leaderboard configuration.
  • SysEditLeaderboard - Edit a player or group entry leaderboard configuration.
  • SysCreateLeaderboardConfig - Creates a leaderboard configuration, with support for tournament leaderboards.
  • SysEditLeaderboardConfig - Edits a leaderboard configuration, with support for tournament leaderboards.
  • SysGetLeaderboardConfig - Returns leaderboard configuration information, including tournament settings, for future and current (active) version of the specified leaderboard.
  • SysListLeaderboardConfigs - Returns list of applicable leaderboards, with summary leaderboard configuration information, including tournament flags, if applicable. Any supported optionsJson flag not specified will default to false.
  • SysEditTournamentSettingsForFuturePeriodsOnly - Updates the tournament settings for the leaderboard configuration, for future recurring periods only (does not affect current rotation). Supported tSettingsJson settings include: 'tTournament' (with 'tConfigs' to configure tournament templates, 'tAutoJoin' flag, 'tAutoClaim' flag), and 'tPhases' (to schedule 'enrolMins', 'announcementMins', 'disallowMins' and 'bufferMins' minutes).
  • SysEditTournamentSettingsIncludingCurrentPeriod - Updates the tournament settings for the leaderboard configuration, for the current period in progress, as well as the future periods if recurring periods (not ADHOC). Supported tSettingsJson settings include: 'tTournament' (with 'tConfigs' to configure tournament templates, 'tAutoJoin' flag, 'tAutoClaim' flag), and 'tPhases' (to schedule 'enrolMins', 'announcementMins', 'disallowMins' and 'bufferMins' minutes), and, if ADHOC tournament in progress, API also supports 'tPeriod' duration settings ('durationDays', 'durationDays', 'durationDays').
  • SysCreateAdhocTournamentPeriod - Schedules a new tournament period for the ADHOC leaderboard configuration. Tournament must be scheduled in the future. Tournament settings ('tSettingsJson') must include tournament period ('tPeriod'), tournament configs and associated flags ('tTournament') and tournament phases ('tPhases').
  • SysEditAdhocTournamentPeriod - Updates a future ADHOC tournament period scheduled for the leaderboard configuration, identified by the existing period's UTC startingAt time, in milliseconds. Period being edited must be scheduled in the future, not in-progress. Tournament settings may include tournament period ('tPeriod'), tournament configs and associated flags ('tTournament') and tournament phases ('tPhases').
  • SysDeleteAdhocTournamentPeriod - Deletes a future ADHOC tournament period scheduled for the leaderboard configuration, identified by the existing period's UTC startingAt time, in milliseconds. Period being edited must be scheduled in the future, not in-progress. Tournament settings may include tournament period ('tPeriod'), tournament configs and associated flags ('tTournament') and tournament phases ('tPhases').
  • SysGetLeaderboardConfigsPage - Returns a page of leaderboard configurations from the server based on the specified context.
  • SysGetLeaderboardConfigsPageOffset - Gets the page of leaderboard configuration information from the server based on the encoded context and specified page offset.

📄️ SysEditTournamentSettingsIncludingCurrentPeriod

Updates the tournament settings for the leaderboard configuration, for the current period in progress, as well as the future periods if recurring periods (not ADHOC). Supported tSettingsJson settings include: 'tTournament' (with 'tConfigs' to configure tournament templates, 'tAutoJoin' flag, 'tAutoClaim' flag), and 'tPhases' (to schedule 'enrolMins', 'announcementMins', 'disallowMins' and 'bufferMins' minutes), and, if ADHOC tournament in progress, API also supports 'tPeriod' duration settings ('durationDays', 'durationDays', 'durationDays').

Last updated on by Jason Liang