Leaderboards

Description

Leaderboards are where you record and/or retrieve your player rankings and scores. There are different types of leaderboards that offer different features, but they all track your players' scores.

Time spans

One thing to note about leaderboards is that they track scores for several different time spans. This allows you to use the same leaderboard to track rankings for various time spans. The currently supported time spans are as follows:

• all-time

• daily

• monthly

• weekly

• yearly

Whenever a score is recorded, it is recorded for each of the aforementioned timespans. So, when a score is recorded, the all-time time span for the leaderboard is updated, as are the daily, weekly, monthly, and yearly time spans for the leaderboard for the specific day, week, month, and year that correspond to the recording's date/time.

This powerful feature allows you to easily retrieve and display rankings for any given day, week, month, or year for which scores have been recorded as well as the all-time rankings.

If no scores have been recorded for a given time-span, then an empty set of leaderboard rankings will be returned.

Properties

Leaderboards have the following properties:

Name	Type	Default
custom_id	string	-
name	string	-
description	string	empty
custom_data	json	empty
type	string	standard
custom_session_id	string	empty
ordering	string	larger-is-better
score_preference	string	prefer-higher

Click here for information about common properties.

Type

There are currently three types of leaderboards supported in r4nkt. A leaderboard's type can be found in its type property and can have one of the following values:

• standard: This type of leaderboard is one based on players' achievement points. Whenever an achievement is earned, then the points for all of their earned achievements are added together and recorded. This is done automatically and for each time span. No other customization is required.

• session: This type of leaderboard is nearly identical to the standard type. The difference is that it only reflects achievement points that have been earned within the context of a session.

• custom: A custom leaderboard is one where the players' scores must be uploaded directly. When a player's score is submitted for a custom leaderboard, then it will be compared to the player's old score on that leaderboard, if it exists. If none exist, then the new one will be recorded. If the new one is better than the old one, then the new one will be added and the old one will be forgotten. This is done for each time span. Again, no other customization is required.

For any given game, no more than one standard leaderboard is allowed.

You cannot submit scores tostandard or session leaderboards.

When comparing scores the leaderboard's ordering property is used to determine which score is better and how to rank. Read more here.

Please note that, once created, a leaderboard's type property cannot be changed.

Custom Session ID

For session-based leaderboards (type is set to session), a custom session ID is required. This ID is used when reporting activity if the activity took place within some sort of custom session. Whenever activity is reported when a custom session ID is provided, then those activities will be processed within such a context first.

Please note that, once created, a leaderboard's custom_session_id property cannot be changed.

Ordering

A leaderboard's ordering property determines how the scores are interpreted as well as how rankings are determined. It can have one of the following values:

• larger-is-better: These leaderboards consider larger scores as better than lower ones.

• smaller-is-better: These leaderboards consider smaller scores as better than larger ones.

Score Preference

A leaderboard's score_preference property determines how new scores are compared to old scores when updating a given leaderboard. This applies to all leaderboard types and is applying the same regardless of the leaderboard's ordering property.

A leaderboard's score_preference can be set to one of the following values:

• prefer-higher: When comparing a new score to an old one, the new one will be added if it's greater than the old one.

• prefer-lower: When comparing a new score to an old one, the new one will be added if it's less than the old one.

• prefer-first: The first score will be added. All subsequent scores will be ignored.

• prefer-last: Each score that is submitted will added. Any previous scores will be removed.

Rankings

Of course, a leaderboard is somewhat boring without the ability to see how the players are ranked.

Leaderboard Rankings

Leaderboard rankings can be requested for any leaderboard. Pagination is supported and rankings can be requested for any given time span, which defaults to all-time.

Player Rankings

An individual player's ranking for a specified leaderboard is also available. It can be requested for any given time span, but it defaults to all-time.