Latest news and updates from the PlayFab developers

byBrendanVanous 2016-04-16

New Aggregation Methods for Statistics

We have made some very cool changes to how player statistics can get set. Until now, when a statistic update call occurred, it simply overwrote the value. So a title that wanted to only write a value if it was higher, for example, had to first read the statistic, check if the new score was higher, and then write it.

Now, in addition to configuring the frequency with which a statistic resets, you can also define the logic it uses for accepting new values, by defining its aggregation method. The methods you can use are:

  • Last - This is the old behavior, where the new value reported overwrites the old value. This is a frequently used aggregation method for statistics which aren’t intended as leaderboards, but rather as tracked values that are updated due to in-game actions. Things like character attributes and hit points would be good examples of this.
  • Min - Update the statistic only if the new value is lower than the current value. Racing games, where the amount of time a player took to complete the race, commonly need this aggregation form, as players continually push to run their tracks faster and with greater precision.
  • Max - Update the statistic only if the new value is higher than the current value. The high score called out above is probably the most common use case for Max aggregation, so that a player’s score can only ever increase.
  • Sum - Add the reported value to the current value, as a running total. An example here would be experience points for a player, where each gameplay session provides some experience which is to be added to the total.

How to use it

The aggregation method used is specified in the statistic definition, the same way that you can define a reset period for it. We’ll have the option to update this in the Game Manager shortly, but if you want to get started with this right away, you can still set it up via the Admin API (and you can use our Postman collection to make this easy).

There are two Admin API calls for this - one to create a new statistic and set up its reset period and aggregation method (CreatePlayerStatisticDefinition), and another to update that definition (UpdatePlayerStatisticDefinition). The call to each uses the exact same parameters, so we’ll show it here using the Update call, since that’s the one you’ll likely be using more often.

For example, if you wanted to track on the total number of monsters killed by a player in an individual session, you could make a call like this:

<span style="font-weight: 400;">POST https</span><span style="font-weight: 400;">:</span><span style="font-weight: 400;">//</span><span style="font-weight: 400;">aaa</span><span style="font-weight: 400;">.</span><span style="font-weight: 400;">playfabapi</span><span style="font-weight: 400;">.</span><span style="font-weight: 400;">com</span><span style="font-weight: 400;">/</span><span style="font-weight: 400;">Admin</span><span style="font-weight: 400;">/</span><span style="font-weight: 400;">UpdatePlayerStatisticDefinition</span>
<span style="font-weight: 400;">Content</span><span style="font-weight: 400;">-</span><span style="font-weight: 400;">Type</span><span style="font-weight: 400;">:</span><span style="font-weight: 400;"> application</span><span style="font-weight: 400;">/</span><span style="font-weight: 400;">json</span><span style="font-weight: 400;">;</span>
<span style="font-weight: 400;">X</span><span style="font-weight: 400;">-</span><span style="font-weight: 400;">SecretKey</span><span style="font-weight: 400;">: </span><span style="font-weight: 400;">1234567890ABDCDEF</span><span style="font-weight: 400;"> {</span>
<span style="font-weight: 400;">  </span><span style="font-weight: 400;">"StatisticName"</span><span style="font-weight: 400;">:</span> <span style="font-weight: 400;">"MonstersKilled"</span><span style="font-weight: 400;">,</span>
<span style="font-weight: 400;">  </span><span style="font-weight: 400;">"AggregationMethod"</span><span style="font-weight: 400;">:</span> <span style="font-weight: 400;">"Max"</span>
<span style="font-weight: 400;">}</span>

Obviously, you’ll want to swap the Title ID and Secret Key (“aaa” and “1234567890ABCDEF”, respectively) for the correct ones for your title, but otherwise the call is as you would make it for your own game. This would update the statistic (and so, leaderboard) with the ID “MonstersKilled” with an aggregation type of "Max", so that only the highest value submitted for a player is kept. If instead, you wanted to track on the total number of monsters the player killed across all game sessions, you could set it to “Sum” so that it adds the reported value each time. You'll notice that we didn't set a reset period for the statistic in this case, but you could also set that to anything you wanted to as well, in the same call.