Documentation

Did you find this helpful?

Using Player Statistics

This document describes how to create and use player statistics. Player statistics are stored as key value pairs where the key is a string and the value is a 32-bit integer (for compatibility with languages which do not support 64-bit). Player statistics are also used by leaderboards. This guide covers player statistics exclusively. If you wish to read about how player statistics and leaderboards work together, please read our leaderboards guide.

Clarification: In some documentation and API calls, you may find the term UserStatistics. For the purposes of this discussion, the terms "user" and "player" are identical and interchangeable. In the Game Manager, the players tab provides access to the users/players for your title, and within that, their statistics. Player statistics refers specifically to information bound to a player, not analytics information about players.

Client API: The client has access to read player statistics, but for cheat prevention the client is not able to update statistics by default.

To enable this:

  • Log into PlayFab
  • Click your title
  • Select "Settings" from the left-menu
  • Select the "API Features" tab
  • Find and activate "Allow client to post player statistics"

But please note that doing so disables a security layer for your title, allowing players to post arbitrary scores to all of their statistics. If your game has any competitive play aspect, we would recommend that you never post statistics from the client.

Statistics are Public Information

There are no private or server-only statistics. A player can always read all of their own statistics via GetPlayerStatistics, and a player can read all other players' statistics via leaderboard API calls. This is true even if you don't display a statistic in-game, or use leaderboards.

The only exception to this would be if you disable client features through our Policy API. Please refer to that link for more information on how to use the policy settings for titles, as that is an advanced topic which is not covered by this guide.

Setting Statistics

The following Unity/C# code creates (or updates if it already exists) a "strength" statistic value for a player.

PlayFabClientAPI.UpdatePlayerStatistics( new UpdatePlayerStatisticsRequest {
    // request.Statistics is a list, so multiple StatisticUpdate objects can be defined if required.
    Statistics = new List<StatisticUpdate> {
        new StatisticUpdate { StatisticName = "strength", Value = 18 },
    }
},
result => { Debug.Log("User statistics updated"); },
error => { Debug.LogError(error.GenerateErrorReport()); });

Getting Statistics

The following Unity/C# code retrieves all current statistic values for a player.

void GetStatistics()
{
    PlayFabClientAPI.GetPlayerStatistics(
        new GetPlayerStatisticsRequest(),
        OnGetStatistics,
        error => Debug.LogError(error.GenerateErrorReport())
    );
}

void OnGetStatistics(GetPlayerStatisticsResult result)
{
    Debug.Log("Received the following Statistics:");
    foreach (var eachStat in result.Statistics)
        Debug.Log("Statistic (" + eachStat.StatisticName + "): " + eachStat.Value);
}

Aggregation Method

PlayFab supports some convenience options for statistic aggregation. The 4 options include: Last, Min, Max, and Sum.

You can create a statistic definition via the CreatePlayerStatisticDefinition API call, though it's not required. Any call to update a player statistic for the title will automatically create the default statistic definition, using the Last aggregation method. To change a statistic aggregation method, you can use the Game Manager or the UpdatePlayerStatisticDefinition API call.

To edit a statistic definition in Game Manager:

  • Log into PlayFab
  • Click your title
  • Select "Leaderboards" from the left-menu (Statistics and Leaderboards are closely related)
  • Click the existing statistic you want to modify, or select the "New Leaderboard" button at the top
    • For an existing statistic, you'll have another page, with an "Edit Leaderboard" button
  • At this point you should see the following page:

Some examples of how to use statistic aggregation:

  • Max and Min can be used to save "best/worst" scores such as headshots or accuracy
    • In short, they apply the rule of "if this is higher (or lower) than the exisitng score, update the score"
    • Post the statistic for session ending, and the Min/Max aggregation takes care of whether or not to update
    • These can be very useful for resettable leaderboards, as well as a PlayStream Rule that grants achievements
  • Sum could be used to save experience points
    • You post the experience gained this battle, and it is added to the existing statistic value for the player
  • Last allows you to manage the stat yourself
    • Each time you post a statistic, the most recent value is used

Leaderboards

A leaderboard is generated for all statistics saved in PlayFab. Accessing a leaderboard for a specific stat is optional. Reset frequency and aggregation method play a major role in how dynamic the leaderboards are in your game. The tournaments feature focuses on leaderboards with automatic reset frequencies, and is described in the leaderboards guide.

It is encouraged that you use statistics in every manner relevant to your game. You can use resettable statistics to run daily tournaments, and long-term statistics like experience points side-by-side.



Did you find this helpful?