Adding Leaderboards to Your iOS Games

This guide shows you how to use leaderboards APIs in an iOS application to create visual leaderboards, record a player's score, and compare the score against the player's score from previous game sessions.

Creating Leaderboards

If you haven't already done so, review the Leaderboards guide, and then create one or more leaderboards in the Google Play Console.

Important classes

Here are some important classes you should know about when implementing leaderboards:

  • GPGScore is used to submit a score to a specific leaderboard.
  • GPGScoreReport stores information about a score after it's been submitted. (For instance, if this is a new high score for the day.)

In addition, if you choose to implement your own leaderboard controller or do more advanced work with leaderboard data, these classes will come in useful:

  • GPGLeaderboardMetadata contains information about a particular leaderboard, such as its name or icon.
  • GPGLeaderboard directly queries batches of scores for a specific leaderboard from the service.

Displaying the leaderboards

The iOS Games SDK supports the ability to display a list of leaderboards to the player. You can use the GPGLauncherController to display a list of all leaderboards, or display a single leaderboard. You can also select which type of leaderboard (Daily, Weekly, or All-Time) is displayed by default.

  • To present a single leaderboard, call presentLeaderboardWithLeaderboardId:targetLeaderboardId.

    NSString *targetLeaderboardId = @"ABCDEFG";
    [[GPGLauncherController sharedInstance] presentLeaderboardWithLeaderboardId:targetLeaderboardId];
  • To display a list of all leaderboards for a player, call presentLeaderboardList.

    [[GPGLauncherController sharedInstance] presentLeaderboardList];

Submitting a high score

You should always submit a high score at the appropriate moment in your game. The library will take care of detecting if the score is better than the player's current score, caching results, and dealing with network issues. No extra logic is required on your part.

To submit a score for the user:

  1. Create a GPGScore object by calling [[GPGScore alloc] initWithLeaderboardId].

    // You get this string from the Developer Console
    NSString *highScoreLead = @"abcdefg1234567";
    GPGScore *myScore = [[GPGScore alloc] initWithLeaderboardId:highScoreLead];
  2. Assign that score's value property.

    myScore.value = 100;
  3. Call that score's submitScoreWithCompletionHandler method.

    [score submitScoreWithCompletionHandler: ^(GPGScoreReport *report, NSError *error) {
      if (error) {
        // Handle the error
      } else {
        // Analyze the report, if you'd like
  4. (Optional) Take a look at the GPGScoreReport object that's returned to see if the player got a new high score this time around.

Understanding the results

When you submit a score to a leaderboard, a GPGScoreReport is returned in the completion handler. This is a simple object that contains a few interesting read-only properties.

isHighScoreForLocalPlayerToday, isHighScoreForLocalPlayerThisWeek, and isHighScoreForLocalPlayerAllTime are booleans that determine if the score you submitted is a new daily, weekly, or all-time high score.

highScoreForLocalPlayerToday, highScoreForLocalPlayerThisWeek, and highScoreForLocalPlayerAllTime are GPGScore objects that contain the player's current daily, weekly, or all-time high score.

reportedScoreValue is an unsigned long long (a 64-bit number) that contains the high score you originally reported to the Games Service.

You can use this report to display interesting information to the user if you so choose.

[score submitScoreWithCompletionHandler: ^(GPGScoreReport *report, NSError *error) {
    if (error) {
        // Handle the error
    } else {
        if (![report isHighScoreForLocalPlayerAllTime]) {
            NSLog(@"%lld is a good score, but it's not enough to beat your all-time score of %@!",

Retrieving raw leaderboard data

If you don't want to use the library-provided controller, you can generate your own by accessing leaderboard data directly from the library.

To retrieve data for all leaderboards, use the GPGLeaderboardMetadata class.

[GPGLeaderboardMetadata allMetadataWithCompletionHandler:^(NSArray *metadata, NSError *error) {
    if (error) {
        // Something went wrong.
    } else {
        // Metadata contains an array of GPGLeaderboardMetadata objects.

To load score from a specific leaderboard, use the GPGLeaderboard class.

GPGLeaderboard *myLeaderboard = [GPGLeaderboard leaderboardWithId:@"abcdefg1234567"]; = YES;
myLeaderboard.timeScope = GPGLeaderboardTimeScopeThisWeek;
[myLeaderboard loadScoresWithCompletionHandler:^(NSArray *scores, NSError *error) {
    for (GPGScore *nextScore in scores) {
        NSLog(@"Player %@ has a score of %@", nextScore.displayName, nextScore.formattedScore);

Send feedback about...

Play Games Services for Android
Play Games Services for Android