Adding Player Stats to Your Game

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 a native C++ or Objective-C application.

Player Stats basics

You can use the Player Stats APIs 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.
  • Churn probability: The prediction of whether a player will churn in the next day, given as 0 (low probability of churn) or 1 (high probability of churn). Churn is defined as 7 days of inactivity.
  • 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 and 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 and 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.

Getting Player Stats for a currently signed-in Player with C++

// Create the callback for our asynchronous fetch call.  This callback will
// log either an error or the average session length for the currently
// signed-in player.
gpg::StatsManager::FetchForPlayerCallback callback = [](gpg::StatsManager::FetchForPlayerResponse const &response) {
  if (IsError(response.status)) {
    LogE("An error occurred fetching player stats.");
  } else {
  gpg::PlayerStats const & player_stats =;
    if (player_stats.HasAverageSessionLength()) {
      LogI("Average session length: %f", player_stats.AverageSessionLength());
    } else {
      LogW("Currently signed-in player had no associated average session length stats.");
// Asynchronously fetch the Player Stats.  When the fetch is finished it
// will call our callback. game_services_ is the std::unique_ptr<GameServices>
// returned by gpg::GameServices::Builder.Create()

Getting Player Stats for a currently signed-in Player with Objective-C

// Asynchronously fetches the Player Stats and then logs either a
// description of them or an error
[GPGPlayerStats playerStatsWithCompletionHandler:^(GPGPlayerStats *playerStats, NSError *error) {
  if (error) {
    NSLog(@"Error fetching player stats: %@", error);
  } else {
    NSLog(@"Description of stats for the currently signed-in player: %@", playerStats);

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:

Player Segment Engagement Strategy
Frequent players with a high number of sessions and good spend percentile, but have not played for the last week or more.
  • Send a notification about a discount or special bonus available upon their return to play.
  • Show a welcome back message that acknowledges impressive accomplishments, and award a badge designed to encourage return play.
Highly engaged players in a low spend percentile.
  • Tailor bonuses to incentivize them to invite their friends to install and join your game. This approach builds on the player's demonstrated enjoyment of the game to recruit new players.
High spending players showing signs of having peaked and starting to play less frequently.
  • Tailor bonuses to freshen their interest, such as by offering high-value, short-duration tools, weapons, or discounts.
  • The next time the player signs in, show a video that directs them to community features, like clan attacks, that drive more frequent and longer engagement.