App Store Connect Help

Support / App Store Connect / Reference / Leaderboards

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

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

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 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.

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.

Start Date and Time1

The date and time in which scores begin posting to your leaderboard. The date and time are based on Coordinated Universal Time (UTC).

Duration1

The length of time scores on this leaderboard are posted for.

Restarts Interval1

How often scores on this leaderboard are reset.

1This 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

Localization

The language in which your leaderboard appears. There must be at least one language defined.

Display Name

The display name of the leaderboard in the specified language.

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.”

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 score format type you set for your leaderboard will automatically apply to all languages unless you specify a different type. This is optional.

Image

A localized image that represents the leaderboard. The image must be a .jpeg, .jpg, or .png file that’s 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

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.