Creating Single Leaderboards

A single leaderboard allows players to compare their scores with the scores of other players in the same game. When you configure leaderboards in iTunes Connect, you specify details such as the scores to collect and how to order the scores. For each language you want the leaderboard to display in, you specify the leaderboard name, score format, and score unit. You can also include a localized image to illustrate the score in the leaderboard.

You can configure leaderboards for your app in iTunes Connect when the status of your app is anything other than In Review. You can’t delete a leaderboard after the leaderboard appears in a live version of the app.

Important: If you add a leaderboard to an app whose status is “Ready for Sale,” the leaderboard is automatically submitted for review the next time you submit a version of your app. If you don’t want to submit the leaderboard, you can change the default settings in the Game Center section on Versions of the App Details page, as described in Distributing Game Center Apps.

Configuring Leaderboards

When you have more than one leaderboard, you can:

Change the default leaderboard

Edit leaderboard properties

Reorder how leaderboards are listed

Delete leaderboards

For information about managing leaderboards that have been added to a group, see Configuring Groups.

The default leaderboard is the first leaderboard that the user sees in Game Center for the app. The first single leaderboard you create is automatically set as the default leaderboard.

In the row of the leaderboard you want to be the default, select the Default option.

Depending on the state of your app, you may be limited in what leaderboard properties you can edit. Before you submit your app for review, you can change all leaderboard properties except the leaderboard ID. After you submit, most properties aren’t editable. Refer to Leaderboard Properties for details on what properties are editable.

In the Leaderboards section, find the leaderboard you want to reorder.

Using the icon in the first column, drag the leaderboard to a new location in the table.

The status of a leaderboard is displayed in the rightmost column of the Leaderboards table. The possible status values are described in Leaderboard Statuses. If a Delete button appears in this column, the status is none of those values and the leaderboard can be deleted. After a leaderboard is available in Game Center, it can’t be deleted.

The Delete button appears and is enabled only if the leaderboard isn’t already in use in Game Center.

Click Delete to confirm.

Configuring Leaderboard Languages

iTunes Connect provides configuration for leaderboard text separate from the configuration of the score itself. This allows you to repeat the text configuration for each language or region your app supports. You must provide at least one language configuration. Refer to Leaderboard Language Properties for more information about leaderboard language properties.

In the Leaderboards section, select the leaderboard that you want to edit.

In the row of the language you want to remove, click Delete.

Click Delete to confirm.

Configuring Combined Leaderboards

A combined leaderboard ranks player scores from multiple single leaderboards. For example, if you have a leaderboard for the lap times for each level of a race game, you can configure a combined leaderboard that ranks player scores across all levels of the game. You must have at least two single leaderboards before you can create a combined leaderboard. The leaderboards you are combining must have the same score format and sort order. Refer to Leaderboard Properties when entering information about a combined leaderboard.

After you create a combined leaderboard, you manage it with the other leaderboards configured for the app. In the list of leaderboards, the type indicates that a leaderboard is combined; leaderboards that contributed to a combined leaderboard are listed as attached.

Note: If you create a combined leaderboard after an app is available in the App Store, be aware that only new scores are displayed in the new combined leaderboard. Values collected previously in the child leaderboards aren’t shifted to the combined leaderboard.

Combined leaderboards are different from leaderboard sets. A combined leaderboard provides a single list of scores from multiple leaderboards; leaderboard sets simply organize leaderboards without affecting the content of the leaderboard. See Configuring Leaderboard Sets.

Configuring Leaderboard Sets

Leaderboard sets organize several leaderboards into a single unit. For example, in a game that includes many levels, you could define a leaderboard set to organize the leaderboards for each level. Leaderboard sets provide you with a way to expand the number of leaderboards allowed per app: without leaderboard sets, each app can have a maximum of 100 leaderboards. With leaderboard sets, each app can have a maximum of 500 leaderboards arranged across as many as 100 leaderboard sets. A set can have a maximum of 100 leaderboards.

You must have at least one leaderboard for your app before you can create a leaderboard set. After you add leaderboard sets to your app, all future leaderboards that you configure for the app must be included in a leaderboard set.

For more information about the use of leaderboard sets in your game, see Leaderboard Sets.

Leaderboard sets are different from combined leaderboards: a leaderboard set simply organizes existing leaderboards and does not affect the content of the individual leaderboards. A combined leaderboard is an additional leaderboard that ranks scores together from multiple leaderboards. See Configuring Combined Leaderboards.

Creating Leaderboard Sets

The process to start using leaderboard sets to organize your app’s leaderboards includes these steps:

Create the first leaderboard set.

Create additional leaderboard sets.

Add new leaderboards directly into leaderboard sets.

When you create the first leaderboard set, iTunes Connect ensures that all existing leaderboards for the app are included in at least one leaderboard set. Just as you did for a leaderboard, a leaderboard set requires that you configure an internal name and ID and display text for each language the app supports.

In the Leaderboards section, click “Move All Leaderboards into Leaderboard Sets.”

In the Leaderboard Set Reference Name field, enter an internal name for the leaderboard set.

When you add language support, you’ll enter a localized name for the leaderboard that’s displayed to users.

In the Leaderboard Set ID field, enter an alphanumeric identifier for the leaderboard set.

The identifier can contain periods and underscores. It must be unique among leaderboard IDs for all apps in the organization.

Click Continue.

On the Move Leaderboards Into Sets page, click “Add to Leaderboard Set.”

In the Add Leaderboard to Set dialog, configure each leaderboard you want to include in this set.

Choose a leaderboard.

Choose a language.

Set the display name for the leaderboard in this language.

Click Save.

This is your opportunity to give the leaderboard a different name in the context of this leaderboard set. For example, a single leaderboard named “Level 1 Laps” can be named “Laps” when included in the leaderboard set for Level 1.

Repeat for each leaderboard to include in this set.

Make sure that all leaderboards are included in sets.

You can either:

Add leaderboards to existing sets by choosing a leaderboard set from the Leaderboard Set menu and clicking “Add to Leaderboard Set,” as described in steps 6 through 7.

On the Move Leaderboards Into Sets page, click Add Language to specify the display name for the leaderboard set.

In the dialog that appears, select the language, display name, and image for the leaderboard set.

Click Save.

Repeat steps 9 through 11 for each language or region your app supports.

Click Save to accept the new leaderboard set configuration.

You can add new leaderboard sets to your app to further customize how your leaderboards are displayed. Each set provides you with the ability to specify how a particular leaderboard is displayed within the set. You can put the same leaderboard into more than one set and configure a different display name for the leaderboard within each set.

In the dialog that appears, in the Leaderboard Set Reference Name field, enter an internal name for the leaderboard set.

When you add language support, you’ll enter a localized name for the leaderboard that’s displayed to users.

In the Leaderboard Set ID field, enter an alphanumeric identifier for the leaderboard set.

The identifier can contain periods and underscores. It must be unique among leaderboard IDs for all apps in the organization.

Click “Add to Leaderboard Set” to add a leaderboard to the set.

In the Add Leaderboard to Set dialog, configure each leaderboard you want to include in this set.

Choose a leaderboard.

Choose a language.

Set the display name for the leaderboard in this language.

Click Save.

This is your opportunity to give the leaderboard a different name in the context of this leaderboard set. For example, a single leaderboard named “Level 1 Laps” can be named “Laps” when included in the leaderboard set for Level 1.

Repeat this step for each leaderboard to include in this set.

Review the order of the leaderboards in the set.

The order that leaderboards appear in the table is the order they appear when displayed in Game Center.

On the Add Leaderboard Set page, click Add Language to configure at least one language the leaderboard set name will be displayed in.

In the dialog that appears, select the language, display name, and image for the leaderboard set.

The Language and Display Name fields are required. The Image field is optional.

Click Save.

Repeat steps 8 through 10 to include support for additional languages.

Click Save to save the new leaderboard set configuration.

Creating a new leaderboard differs slightly after you start using leaderboard sets in your app. You must associate the new leaderboard with a leaderboard set before you can save the configuration.

You can reorder the leaderboard sets by dragging a set name to the desired location. Click the name of the leaderboard set to edit its contents or change the order of the leaderboards it contains.

To see which leaderboards are included in which leaderboard sets, click “View Leaderboards in Leaderboard Sets.” The dialog shows all leaderboards defined for the app, by name and reference ID with checks to indicate in which sets each leaderboard appears.

Deleting Leaderboard Sets

Before you can delete a leaderboard set, you must make sure all leaderboards in the set are also in another set and then you must remove the leaderboards from the set you want to delete. You can’t remove a leaderboard from a leaderboard set unless that leaderboard is already in another set.

In the Leaderboards in This Set section, click Remove for each leaderboard.

Click Done after removing all of the associated leaderboards.

Back on the Game Center page, click Delete to remove the leaderboard set.

Click Delete to confirm.

If your app contains 100 leaderboards or fewer, you can click “Remove All Leaderboards in Leaderboard Sets” and all of your current leaderboard sets are deleted. This option doesn’t appear for apps with over 100 leaderboards. You must remove any leaderboards over 100 before you can use the “Remove All Leaderboards in Leaderboard Sets” button.

Merging Leaderboard Sets into a Group’s Leaderboard Sets

Merging games into a group provides a way to share leaderboards and achievements across multiple games. Each game is still limited to 500 leaderboards and 100 leaderboard sets. However, the total number of leaderboards and leaderboard sets in a group can surpass these numbers. Each group can have a maximum of 500 leaderboards and 100 leaderboard sets multiplied by the number of games in the group. For example, a group with three games can have a total of 1500 leaderboards and 300 leaderboard sets in the group. For information about creating and managing groups, see Groups.

You merge games into a group one at a time. A single game that has leaderboard sets can only be merged into a game group if one of the following two conditions applies:

The group already uses leaderboard sets.

You’re creating a new group starting with this game.

You can’t merge a game without leaderboard sets into a group with leaderboard sets. You have to add leaderboard sets to the single game before merging it into the existing group.

Similarly, you can’t merge a game with leaderboard sets into an existing group without leaderboard sets. You first have to move all of the group leaderboards into leaderboard sets before you can merge the single game into the group.

Because the app is part of a group, the page that appears describes Game Center options for the group.

In the Group Leaderboards section, click “Move All Leaderboards into Leaderboard Sets.”

In the dialog that appears, enter information for the first new leaderboard set.

In the Leaderboard Set Reference Name field, enter an internal name for the leaderboard set.

In the Leaderboard Set ID field, enter an alphanumeric identifier for the leaderboard set.

The Set ID of each leaderboard and leaderboard set is automatically prefaced with the grp. prefix when the game is part of a group. You can change the leaderboard and leaderboard set Set IDs but must keep the grp. prefix in the new name. These IDs must be unique among leaderboard IDs across all apps in the organization.

Click Continue to open the Move Leaderboards into Sets page.

On this page you can do the following:

Click Add Leaderboard Set to create an additional leaderboard set for the group, as described in step 3.

Click “Add to Leaderboard Set” to add leaderboards to the set selected at the top of the page.

You’re prompted to select the leaderboard and specify the display name used for this leaderboard in the set. Specify the display name for each language or region your app supports.

Click Add Language to specify the display name for the leaderboard set selected at the top of the page.

You’re prompted to specify the display name used for this leaderboard set. Specify the display name for each language or region your app supports. You can also provide an image for the leaderboard set for each language.

When you’ve assigned all leaderboards in the group to one or more leaderboard sets, click Save.

Bulk Uploading Leaderboard Metadata to iTunes Connect

If you have many leaderboards to configure in iTunes Connect, you can deliver leaderboard and other iTunes Connect configuration metadata in batch in an App Store package using Transporter. See App Metadata Specification and Transporter Quick Start Guide. These documents are available to iTunes Connect users within Resources and Help.