Statistics

Overview

AccelByte Cloud’s Statistics service gives game developers persistent statistics tracking for their games. Tracked statistics include gameplay-related stats such as kill, die, and assist, and internal game data such as map played and game modes played. Statistics are tied to players and can be easily integrated or displayed as game profile attributes through the Cloud Profile (opens new window) service.

AccelByte Cloud’s Statistics service also acts as the reference point for consistent value tracking across other services such as Progression, Achievements, and Leaderboards. We use messaging to update statistics values asynchronously to other related services in real-time. You only need to define the statistics you want to measure once, and they’ll be applied to all related services.

Permissions

Permissions (opens new window) are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage achievements in the Admin Portal. For a full list of permissions that impact achievements management, see the Social tab of the permissions reference (opens new window).

Usage	Permission Tag	Action
Create a new statistic configuration	ADMIN:NAMESPACE:{namespace}:STAT	CREATE
Create a single statistic for a player	ADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEM	CREATE
Create multiple statistics for a player	ADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEM	CREATE
Retrieve all of a player’s statistics	ADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEM	READ
Update a single statistic for a player	ADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEM	UPDATE
Update multiple statistics for multiple players	ADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEM	UPDATE
Retrieve global statistics	ADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEM	READ

Permissions work slightly differently depending on whether they are assigned to IAM Clients (opens new window) or are Roles (opens new window) assigned to users. For more information, see our Cloud Authentication and Authorization (opens new window) documentation.

Manage Statistics in the Admin Portal

Create a new Statistic configuration

Follow the steps below to add a new configuration:

1. In the Admin Portal, go to the Game Management section, expand the Statistics section, and select the Configurations menu.

   

2. In the Statistic Configurations window, click the Add Configuration button.

   

   The Add New Configuration form will appear.

3. Fill in the required fields:

   

   • Input the statistic code or StatCode in the Code field, following the formatting rules given.

     NOTE

     StatCode is used when you create an Incremental Achievement (opens new window) or Leaderboard (opens new window). These Cloud services use player statistics to determine achievement conditions and generate leaderboards.

• Input the Name of the configuration.
• Input a Description of the configuration. This field is optional.
• Define the minimum value of the statistic in the Min. Value field.
• Define the maximum value of the statistic in Max. Value field.
• Input the Default Value of the statistic.
• Choose the Increment value. If set to True, the stat value can only be increased. If you set it to False, the stat value can be increased or decreased.
• Choose the Set as Global value. If set to True, every time the stat is updated, the global stat value will also be updated.
• Select the Set By value. You can choose game client or game server. This determines which client will update the stat value.
• Input the Tag field with any information related to the statistic. This field is optional.

Edit a Statistics Configuration

Follow the steps below to edit a statistics configuration:

1. In the Admin Portal, go to the Game Management section, expand the Statistics section, and select the Configurations menu.

   

2. In the Statistic Configurations page, click More Options (...) under the Action column, then click View.

   

3. On the Statistic Configuration page, you can edit the Name, Description, and Default Value of the selected statistic by clicking the pencil button.

   

Retrieve a Player’s Statistics

1. In the Admin Portal, go to the Game Management section, expand the Statistics section, and select the Statistics Value menu.

   

2. Use the drop down to search for a player by Email, Display Name, User Name, or User ID.

   

3. Click View next to the player whose statistics you want to see.

   

4. On the Statistics Values page, you can see detailed information about the player’s statistics.

   

Edit a Player’s Statistics

1. Navigate to the detail of the player’s statistics, as shown in the previous steps.

2. Choose the statistic you want to edit and click the pencil icon under the Current Value column.

3. Make any changes.

4. When you’re finished, click the blue tick button to save your changes.

   

Retrieve Global Statistics

1. In the Admin Portal, go to the Game Management section, expand the Statistics section, and select the Statistics Value menu.

   

2. Switch to the Global tab. Here you’ll see the global statistics.

   

Manage Statistics Using the Client SDKs

In this section, you will learn how to use the Client SDKs to manage the statistics for a player.

Create Statistics for a Player

Use the following code to create a new statistic item for a player.

Increment User Stat Items

Use the following code to increment the user statistic items. You can increment multiple statistic codes with certain values simultaneously.

Retrieve a Player’s Statistic by StatCodes or Tags

Use the following code to retrieve a player’s statistic by a specific StatCodes or Tags. This call return will only contain stat items specified by statCodes and tags.

Retrieve All Players’ Statistics

Use the following code to retrieve all stat items.

Reset Multiple Statistics

Use the following code to reset a player's statistics to the default values in your game namespace. You can specify which statistics to reset.

NOTE

Resetting multiple statistics is not supported yet in the Unreal Engine AccelByte plugin.

Update Multiple Statistics

Use the following code to update multiple statistics. There are four update strategies that you can use.

Update Strategy	Usage
OVERRIDE	Update a player’s StatItem value.
INCREMENT	Add to or subtract from a player’s StatItem value.
MAX	Update a player’s StatItem with a specified value greater than the current value.
MIN	Update a player’s StatItem with a specified value lower than the current existing value.

EXAMPLE

Suppose you want to implement a ranking system for your game. Whenever your players lose a match, their stats value decreases, meaning they go down a rank. To do this, you can use the INCREMENT strategy with a negative value to subtract the value and set the Increment field to False.

You also can use additionalKey to add more additional information about the player. The additionalKey parameter is added as a suffix to userId and is used to support multi-level players' stat items such as character stat items. If provided, the user's stat items will be saved with the key userId_additionalKey.

Manage Statistics Using the Server SDKs

You can manage your statistics using the Client or Game Server. In this section, you will learn how to set up your statistics using the Game Server.

Create Statistics for a Player

Use the following code to create a new statistic for a player from your game server.

Increment User Stat Items

Use the following code to increment the user statistic items from the server. You can increment multiple statistic codes with certain values simultaneously.

Increment Multiple Users Stat Items

Use the following code to create multiple statistics for multiple players simultaneously.

Retrieve a Player’s Statistic by StatCodes or Tags

Use the following code to retrieve a player’s statistic from the server by a specific StatCodes or Tags. This call return will only contain stat items specified by statCodes and tags.

Retrieve All Players’ Statistics

Use the following code to retrieve all stat items from the server.

Reset Multiple Statistics for a Player

Use the following code to reset multiple statistics for a player to the default values as specified in your game namespace.

Reset Multiple Statistics

Use the following code to reset multiple players’ statistics to the default values as specified in your game namespace.

NOTE

Resetting multiple statistics for multiple players from the server is not supported yet in the Unreal Engine AccelByte plugin.

Update Multiple Statistics for a Player

Use the following code to update multiple statistics for a player using the updating strategy options.

Update Multiple Statistics for Multiple Players

Use the following code to update multiple statistics for multiple players using the updating the strategy options.

Connect Custom Services to Statistics using Server-side SDKs

Initialize the SDK

Before you can use the Statistics service from one of the server-side SDKs, you will need to initialize the server-side SDK to ensure you are authorized and able to perform create, read, update, and delete actions.

Golang

Before you can use the Statistics service from the Golang SDK, you will need to initialize the SDK by following the steps below:

• Create your OAuth Client (opens new window) and assign the necessary permissions to access the IAM service.
• Log in as a Client using the SDK (opens new window).
• Initialize the Statistics service using the following function (opens new window):

Once you have completed these steps, you can use the Golang SDK to create, read, update, or delete Statistics (opens new window) from your serverless app.

To use the Cloud Statistics Service, make sure you have the necessary permissions (opens new window).

Python

Before you can use the Statistics service from the Python SDK, you will need to initialize the SDK by following the steps below:

• Create your OAuth Client (opens new window) and assign the necessary permissions to access the Statistics service.
• Log in as a Client using the SDK (opens new window).

Once you have completed those steps, you can use the Python SDK to manage statistics from your serverless app.

.NET (C#)

Before you can use the Social service, you will need to set some permissions (opens new window). Use the following .NET namespaces to do this:

using AccelByte.Sdk.Api.Social.Model;
using AccelByte.Sdk.Api.Social.Operation;
using AccelByte.Sdk.Api.Social.Wrapper;

Java

Before you can use the Social service, you will need to set some permissions (opens new window). To do this, initialize the StatConfiguration wrapper from the Social service using the following code:

StatConfiguration wStatConfig = new StatConfiguration(sdk);

Once you have completed this step, you can use the SDK to manage a player’s statistics from your game client.

Create a Statistic Configuration

Use the following function to create a statistic configuration (opens new window):

Delete a Statistic Configuration

Use the following function to delete a statistic configuration (opens new window):

Retrieve a Statistic Configuration by Stat Code

Use the following function to retrieve a statistic configuration (opens new window):

Retrieve All Statistic Configurations

Use the following function to retrieve all statistic configurations (opens new window).

Search for a Statistic Configuration by Keyword

Use the following function to search for a configuration (opens new window) based on a keyword:

Update a Statistic Configuration

Use the following function to update a statistic configuration (opens new window):