| **Note:** This guide is for the Play Games Services v2 SDK. For information on the previous version of this SDK, see the[Play Games Services v1 documentation](https://developer.android.com/games/pgs/v1/android/leaderboards).

This guide shows you how to use leaderboards APIs in an Android app 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 the[`com.google.android.gms.games`](https://developers.google.com/android/reference/com/google/android/gms/games/package-summary)and[`com.google.android.gms.games.leaderboards`](https://developers.google.com/android/reference/com/google/android/gms/games/leaderboard/package-summary)packages.

## Before you begin

If you haven't already done so, you might find it helpful to review the[leaderboards game concepts](https://developer.android.com/games/pgs/leaderboards).

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](https://developers.google.com/android/guides/setup)guide.

- Define the leaderboards that you want your game to display or update, by following the instructions in the[Google Play Console guide](https://developer.android.com/games/pgs/leaderboards#creating_a_leaderboard).

- Download and review the leaderboards code samples in the[Android samples page](https://github.com/playgameservices/android-basic-samples)on GiHub.

- Familiarize yourself with the recommendations described in[Quality Checklist](https://developer.android.com/games/pgs/quality).

## Get the leaderboards client

To start using the leaderboards API, your game must first obtain a[`LeaderboardsClient`](https://developers.google.com/android/reference/com/google/android/gms/games/LeaderboardsClient)object. You can do this by calling the[`PlayGames.getLeadeboardsClient()`](https://developers.google.com/android/reference/com/google/android/gms/games/PlayGames#public-static-leaderboardsclient-getleaderboardsclient-activity-activity)method and passing in the activity.
| **Note:** The[`LeaderboardsClient`](https://developers.google.com/android/reference/com/google/android/gms/games/LeaderboardsClient)class makes use of the Google Play services Task class to return results asynchronously. To learn more about using tasks to manage threaded work, see the[Tasks API developer guide](https://developers.google.com/android/guides/tasks).

## 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[`LeaderboardsClient.submitScore()`](https://developers.google.com/android/reference/com/google/android/gms/games/LeaderboardsClient#submitScore), and passing in the leaderboard ID and the raw score value.

The following code snippet shows how your app can update the player's score:  

```scdoc
PlayGames.getLeaderboardsClient(this)
    .submitScore(getString(R.string.leaderboard_id), 1337);
```

A good practice is to define the leaderboard ID in your`strings.xml`file, so your game can reference the leaderboards by resource ID. When making calls to update and load player scores, make sure to also follow these[best practices](https://developer.android.com/games/pgs/quality)to avoid exceeding your API quota.

## Display a leaderboard

To display leaderboard, call[`LeaderboardsClient.getLeaderboardIntent()`](https://developers.google.com/android/reference/com/google/android/gms/games/LeaderboardsClient#getLeaderboardIntent(java.lang.String))to get an[`Intent`](https://developer.android.com/reference/android/content/Intent)to create the default leaderboard user interface. Your game can then bring up the UI by calling[`startActivityForResult`](https://developer.android.com/reference/android/app/Activity#startActivityForResult).

The following code snippet shows how your app can update the player's score. In the code snippet,`RC_LEADERBOARD_UI`is an arbitrary integer for the request code.  

```transact-sql
private static final int RC_LEADERBOARD_UI = 9004;

private void showLeaderboard() {
  PlayGames.getLeaderboardsClient(this)
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}
```

Even though no result is returned, you have to use[`startActivityForResult`](https://developer.android.com/reference/android/app/Activity#startActivityForResult)so that the API can obtain the identity of the calling package. An example of the default leaderboard UI is shown below.
![](https://developer.android.com/static/images/games/pgs/leaderboard_android.png)