Leaderboard Sets

Leaderboard sets offer developers the ability to combine several leaderboards into a single group. iOS developers are able to create leaderboard sets starting with iOS 7. Leaderboard sets are not supported in OS X v10.9.

The following example shows why you would want to incorporate leaderboard sets in your game.

  • The created game has several different worlds with each world containing several leaderboards—for example, a leaderboard for most coins collected, highest score obtained, and most enemies captured.

  • The developer combines the different leaderboards into a single leaderboard set for each world.

  • Users can see a displayed list of world leaderboard sets. Opening a set shows the leaderboards contained in the set.

Important: After you decide to use leaderboard sets, every leaderboard must be placed into a leaderboard set. You can not have a leaderboard outside of a leaderboard set in games that support leaderboard sets.

 Leaderboards which are combined into a leaderboard set

 

Checklist for Supporting Leaderboard Sets

To add leaderboard sets to your game, you need to take the following steps:

  1. Before you add achievements, add code to authenticate the local player. See Initializing Game Center.
  2. Ensure that your game contains at least one leaderboard. See Adding Leaderboard Support to Your Game for information on creating leaderboards.
  3. Go to iTunes Connect and configure leaderboard sets for your game. For each leaderboard set add the desired leaderboards to the leaderboard set. See Working with Leaderboard Sets in iTunes Connect.
  4. Add code to load the leaderboard sets associated with the current game. See Loading Leaderboard Sets to Your Game.
  5. Add code to load the leaderboards contained within a leaderboard set. See Loading Leaderboards Within a Set.

A Game Can Have Multiple Leaderboard Sets

You can define up to 100 different leaderboard sets for your game. Each leaderboard set can contain up to 100 leaderboards with a maximum of 500 leaderboards for your game. You choose which leaderboards are placed inside of each leaderboard set. Games that don’t use leaderboard sets are limited to 100 leaderboards.

Here are a few possible ways to use different leaderboard sets in your game:

  • A game with multiple scoring mechanisms for each world (score, enemies captured, coins collected) can combine the leaderboards for each world into a leaderboard set.
  • A game with multiple scoring mechanisms for each world (score, enemies captured, coins collected) can combine all of the leaderboards for a single scoring mechanism into a leaderboard set.
  • A game with multiple playable characters (warrior, archer) can combine all of the leaderboards for a particular character into a single leaderboard set.

You can combine the number of leaderboards and leaderboard sets in any format as long as the individual maximums are not exceeded. The following are all allowable combinations:

  • 5 leaderboard sets, each containing 100 leaderboards
  • 100 leaderboard sets, each containing 5 leaderboards
  • 3 leaderboards sets, each containing 50 leaderboards; 2 leaderboard sets, each containing 100 leaderboards; 1 leaderboard set containing 1 leaderboard

Game Group Leaderboard and Leaderboard Set Limits

The number of leaderboards and leaderboard sets within a group is limited only by the number of apps within the group. Each game within a group can have a number of leaderboard sets and leaderboards as stated in A Game Can Have Multiple Leaderboard Sets. For example, if a group has three apps inside of it, then the group can have a total of 300 leaderboard sets and 1500 leaderboards. However, an individual app is still limited to 100 leaderboard sets and 500 leaderboards.

Working with Leaderboard Sets in iTunes Connect

After you have decided to use leaderboard sets in your game, you must configure the leaderboard sets in iTunes Connect. In iTunes Connect you can create new leaderboard sets and move your leaderboards into them. For complete details on managing leaderboards of your game and leaderboard sets see Leaderboards and Leaderboard Sets in Game Center Configuration Guide for iTunes Connect.

 

Before you can load the leaderboards contained within a set, you must load the set itself. Retrieve the list of leaderboard sets for your game from Game Center and display their titles.

Loading Leaderboard Sets to Your Game

The code snippet bellow shows the preferred mechanism for loading information about the available leaderboard sets. It returns an array of leaderboard set objects, one for each leaderboard set is defined for your game on Game Center.

GameCenterManager.OnLeaderboardSetsInfoLoaded += OnLeaderboardSetsInfoLoaded;
GameCenterManager.LoadLeaderboardSetInfo();


void OnLeaderboardSetsInfoLoaded (ISN_Result res) {
    GameCenterManager.OnLeaderboardSetsInfoLoaded -= OnLeaderboardSetsInfoLoaded;
    if(res.IsSucceeded) {
        foreach(GCLeaderboardSet s in GameCenterManager.LeaderboardSets) {
            Debug.Log(s.Title);
            Debug.Log(s.Identifier);
            Debug.Log(s.GroupIdentifier);
        }
    }
}

The set is represented as GCLeaderboardSet object.

Loading Leaderboards Within a Set

 The code shows the preferred mechanism for loading information about the available leaderboards. It returns an array of GCLeaderBoardInfo objects.

GCLeaderboardSet LeaderboardSet = GameCenterManager.LeaderboardSets[0];
LeaderboardSet.OnLoaderboardsInfoLoaded += OnLoaderboardsInfoLoaded;
LeaderboardSet.LoadLeaderBoardsInfo();


void OnLoaderboardsInfoLoaded (ISN_LoadSetLeaderboardsInfoResult res) {
    res.LeaderBoardsSet.OnLoaderboardsInfoLoaded -= OnLoaderboardsInfoLoaded;

    if(res.IsSucceeded) {
        foreach(GCLeaderBoardInfo l in res.LeaderBoardsSet.BoardsInfo) {
            Debug.Log(l.Title);
            Debug.Log(l.Description);
            Debug.Log(l.Identifier);
        }
    }
}

 

GCLeaderboardSet

public class GCLeaderboardSet  {
	public string title {get;}
	public string identifier {get;}
	public string groupIdentifier {get;}
    public List<GCLeaderBoardInfo> BoardsInfo {get;}
    public event Action<ISN_LoadSetLeaderboardsInfoResult> OnLoaderboardsInfoLoaded;
}

GCLeaderBoardInfo

public class GCLeaderBoardInfo  {
	public string Title {get;}
	public string Description {get;}
	public string Identifier {get;}
}