Leaderboard

This guide shows you how to use the Play Games Services c++ SDK Leaderboards APIs to create visual leaderboards, record a player's score, and compare the score against the player's score from previous game sessions. The APIs can be found in LeaderboardsClient.

Before you begin

If you haven't already done so, you might find it helpful to review the leaderboards game concepts.

Before you start to code using the leaderboards APIs:

Follow the instructions for installing and setting up your app to use Google Play Games Services in the Set Up Google Play services SDK guide.
Define the leaderboards that you want your game to display or update, by following the instructions in the Google Play Console guide.
Familiarize yourself with the recommendations described in Quality Checklist.

Get the leaderboards client

To start using the leaderboards API, your game must first obtain a LeaderboardsClient object. You can do this by calling the PgsLeaderboardsClient_create() method and passing in the activity.

Update the player's score

When the player's score changes (for example, when the player finishes the game), your game can update their score on the leaderboard by calling PgsLeaderboardsClient_submitScoreImmediate. You need to pass the leaderboard ID, the raw score value, an optional score tag, and a callback function.

// Callback function to handle the result of submitting the score
void OnScoreSubmitted(PgsStatusCode status_code,
                      PgsScoreSubmissionData* score_submission_data,
                      void* user_data) {
  if (status_code == PGS_STATUS_SUCCESS) {
    // Score submitted successfully
    // You can inspect score_submission_data for details
    // Remember to release the data when done:
    PgsScoreSubmissionData_Release(score_submission_data);
  } else {
    // Handle error
  }
}

// Function to submit the score
void SubmitScore(PgsLeaderboardsClient* client, const char* leaderboard_id, int64_t score) {
  const char* score_tag = NULL; // Optional tag

  PgsLeaderboardsClient_submitScoreImmediate(
      client,
      leaderboard_id,
      score,
      score_tag,
      OnScoreSubmitted,
      NULL // user_data - optional context pointer
  );
}

// Example usage:
// Assuming 'my_leaderboard_id' is defined elsewhere, e.g., fetched from resources
// SubmitScore(leaderboards_client, my_leaderboard_id, 1337);

A good practice is to manage your leaderboard IDs as constants or resources within your c++ code.

Display a leaderboard

To display the default leaderboard user interface for a specific leaderboard, call PgsLeaderboardsClient_showLeaderboardUI. This function requires the client handle, the activity, the leaderboard ID, the time span and collection, and a callback.

// Callback function to handle the result of showing the UI
void OnShowLeaderboardUI(PgsStatusCode status_code, bool success, void* user_data) {
  if (status_code == PGS_STATUS_SUCCESS && success) {
    // UI was shown successfully
  } else {
    // Handle error or failure to show UI
  }
}

// Function to show a specific leaderboard UI
void ShowLeaderboard(PgsLeaderboardsClient* client, jobject activity, const char* leaderboard_id) {
  PgsLeaderboardsClient_showLeaderboardUI(
      client,
      activity,
      leaderboard_id,
      PGS_LEADERBOARD_TIME_SPAN_ALL_TIME, // Or PGS_LEADERBOARD_TIME_SPAN_DAILY, PGS_LEADERBOARD_TIME_SPAN_WEEKLY
      PGS_LEADERBOARD_COLLECTION_PUBLIC,  // Or PGS_LEADERBOARD_COLLECTION_FRIENDS
      OnShowLeaderboardUI,
      NULL // user_data - optional context pointer
  );
}

// Example usage:
// ShowLeaderboard(leaderboards_client, android_activity, my_leaderboard_id);

This function displays the UI. The activity object provides the context for displaying the UI.