[ Web Proxy ]
URL:
Viewing: https://developer.android.com/games/pgs/cpp/leaderboards [Back]  [Original]
Leaderboard  |  Android game development  |  Android Developers Skip to main content
Android Developers [Android Developers]
Essentials Design & Plan Develop Google Play Blog
Search:
Android Studio
Overview Downloads Samples Guides Reference Community
Android Developers [Android Developers]
Send feedback

Leaderboard Stay organized with collections Save and categorize content based on your preferences.

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:

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.

Note: The c++ SDK functions often return results asynchronously using callbacks. You'll provide function pointers to handle the results of operations.

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.

Send feedback

Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.

Last updated 2026-06-16 UTC.

Need to tell us more? [[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2026-06-16 UTC."],[],[]]
Web Proxy Viewer  |  New URL  |  Original Page