Reference

Leaderboards

Leaderboard metadata identifies each leaderboard in App Store Connect, describes its scores, and collects language-specific text used in leaderboard display. App Store Connect tracks metadata for the type of leaderboard and displays a status indicating whether the leaderboard has been approved and made live with the app.

Set these properties in the Leaderboard section of the Game Center page for an app, as described in Configure leaderboards.

Leaderboard properties

The main leaderboard properties identify each leaderboard in App Store Connect. These properties describe how the scores are organized and formatted.

Properties	Description
Leaderboard Reference Name	An internal name that you must provide for each leaderboard. This is the name that you use if you search for your leaderboard in App Store Connect.
Leaderboard ID	An alphanumeric identifier you choose for your leaderboard. This ID is limited to 100 characters (assumes single-byte characters). Note that the leaderboard ID is equivalent to the “category” in GameKit API. Your leaderboard ID is a permanent setting and therefore can’t be edited at a later date.
Score Format Type	The type of format in which you want scores for this app to be expressed in your leaderboard—for example, integer, elapsed time, or money.
Score Submission Type	The score from players to display in the leaderboard: Best Score or Most Recent Score.
Sort Order	The order of the score. Choose between “Low to High” and “High to Low.” Choose “Low to High” if you want lowest scores displayed first. Choose “High to Low” if you want the highest scores displayed first.
Score Range	The score range using 64-bit signed integers. The values must be between the long min (-2^63) and long max (2^63 - 1). Any scores outside of this range are deleted. Score range values are optional, but if they’re added, both values must be set and they must not be equal. When first adding a score range, or when changing it in the future to a smaller range that will restrict data, all data outside of the range is lost and can’t be recovered.
Start Date and Time¹	The date and time in which scores begin posting to your leaderboard. The date and time are based on Coordinated Universal Time (UTC).
Duration¹	The length of time scores on this leaderboard are posted for.
Resets Every¹	How often scores on this leaderboard are reset.

¹This property is only available for recurring leaderboards.

Leaderboard language properties

Leaderboard language properties collect language-specific text used in a leaderboard’s display. You must include these properties for at least one language.

Property	Description
Language	The language in which your leaderboard appears. There must be at least one language defined.
Name	The display name of the leaderboard in the specified language.
Score Format	This format determines how your scores are displayed on your leaderboard for the specified language. For example, if your app is scored with money, you may want to specify different types of money based on the language you select. The values in this menu reflect the Score Format Type for the leaderboard.
Score Format Suffix (Singular)	This suffix is added to the end of scores displayed in the singular form. This suffix is optional but is useful for clarifying the type of score stored in the leaderboard. Examples include “point,” “coin,” and “hit.”
Score Format Suffix (Plural)	This suffix is added to the end of scores displayed in the plural form. This suffix is optional but is useful for clarifying the type of score stored in the leaderboard. Examples include “points,” “coins,” and “hits.”
Image	A localized image that represents the leaderboard. The image must be a `.jpeg`, `.jpg`, `.tif`, `.tiff`, or `.png` file that’s 512 x 512 or 1024 x 1024 pixels, at least 72 dpi, and in the RGB color space. This property is optional.

Leaderboard types

App Store Connect tracks different data for each type of leaderboard. The leaderboard type determines which scores are included in a leaderboard.

Type	Description
Classic	A leaderboard where score data will never reset unless the leaderboard is deleted.
Recurring	A recurring leaderboard will continually reset based on your preferences.
Combined	A leaderboard that combines and ranks together the players’ scores from multiple single leaderboards.
Attached	A single leaderboard that’s combined with other leaderboards—the attached child of a combined leaderboard.

Leaderboard statuses

Leaderboard statuses indicate whether the leaderboard has been approved and made live with the app.

Status	Description
In Review	The leaderboard was submitted to Apple for review.
Live	The leaderboard was approved with the app.
Not Live	The leaderboard has not been approved with a version of the app. Leaderboards will also have this status if they were previously Live for an app, moved to a group, and haven’t been approved with the group yet.