Player stats in Android games

The player stats API let you tailor game experiences to specific segments of players and different stages of the player lifecycle. You can build tailored experiences for each player segment based on how players are progressing, spending, and engaging. For example, you can use this API to take proactive actions to encourage a less active player to re-engage with your game, such as by displaying and promoting new in-game items when the player signs in.

This guide shows you how to use the player stats API in games using the Google Play Games Services. The APIs can be found in the com.google.android.gms.games.stats and com.google.android.gms.games packages.

Before you begin

Before you start to use the player stats API:

• Download and review the code sample.
• Familiarize yourself with the recommendations described in the Quality Checklist.

Get the player stats client

To start using the player stats API, your game must first obtain a PlayerStatsClient object. You can do this by calling the Games.getPlayerStatsClient() method and passing in the activity and the GoogleSignInAccount for the current player. To learn how to retrieve the player account information, see Sign-in in Android Games.

Player stats basics

You can use the player stats API to retrieve data about a player’s in-game activity. The types of player data you can retrieve include:

• Average session length: The average session length of the player in minutes. Session length is determined by the time that a player is signed in to Google Play Games services.

• Days since last played: The approximate number of days since the player last played.

• Number of purchases: The approximate number of in-app purchases for the player.

• Number of sessions: The approximate number of sessions of the player. Sessions are determined by the number of times that a player signs in to Google Play Games services.

• Session percentile: The approximation of sessions percentile for the player, given as a decimal value between 0 to 1 inclusive. This value indicates how many sessions the current player has played in comparison to the rest of this game's player base. Higher numbers indicate that this player has played more sessions.

• Spend percentile: The approximate spend percentile of the player, given as a decimal value between 0 to 1 inclusive. This value indicates how much the current player has spent in comparison to the rest of this game's player base. Higher numbers indicate that this player has spent more.

The following types of player data are deprecated and always return an unset value constant:

Retrieve player stats data

To retrieve player stats data for the currently signed-in player, follow these steps:

1. Call the PlayerStatsClient.loadPlayerStats() method.
2. If the call is successful, Google Play games services returns a Task object which asynchronously loads a PlayerStats object. Use the methods of this object to retrieve data about the signed-in player’s activities in your app.

Here's an example:

public void checkPlayerStats() {
  Games.getPlayerStatsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .loadPlayerStats(true)
      .addOnCompleteListener(new OnCompleteListener<AnnotatedData<PlayerStats>>() {
        @Override
        public void onComplete(@NonNull Task<AnnotatedData<PlayerStats>> task) {
          if (task.isSuccessful()) {
            // Check for cached data.
            if (task.getResult().isStale()) {
              Log.d(TAG, "using cached data");
            }
            PlayerStats stats = task.getResult().get();
            if (stats != null) {
              Log.d(TAG, "Player stats loaded");
              if (stats.getDaysSinceLastPlayed() > 7) {
                Log.d(TAG, "It's been longer than a week");
              }
              if (stats.getNumberOfSessions() > 1000) {
                Log.d(TAG, "Veteran player");
              }
              if (stats.getChurnProbability() == 1) {
                Log.d(TAG, "Player is at high risk of churn");
              }
            }
          } else {
            int status = CommonStatusCodes.DEVELOPER_ERROR;
            if (task.getException() instanceof ApiException) {
              status = ((ApiException) task.getException()).getStatusCode();
            }
            Log.d(TAG, "Failed to fetch Stats Data status: "
                + status + ": " + task.getException());
          }
        }
      });
}

Tips for using player stats data

The Play Stats API lets you easily identify various types of players, based on their engagement and spending behavior, and apply appropriate strategies to enhance their game experience.

The following table lists some example player segments and recommended engagement strategies: