Statistics

Overview

The Statistics service provides game developers with persistent statistic tracking for their game. 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 game profile service.

The 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.

Statistic Configuration

Statistics configuration can be configured easily through admin portal. You can also call the API directly based on the reference here.

Creating Player Statistics Attributes from Admin Portal

  1. To create player statistic configuration, select Statistics dropdown menu in the Admin Portal Game and Social section, and click Configurations to open Statistics Configurations page.
  2. Click the Create Configuration button to create a new player statistic config. Statistics service can store both int or float value to suit most of use cases. Statistic configuration has the following attributes:
  • Stat Code. Unique human readable identifier to be used for API Calling or Function calling from the code
  • Name. Name of the statistic item.
  • Description. Description of the statistic item.
  • Namespace. Namespace of the game.
  • Default Value. The initial value assigned as default
  • Minimum. The minimum value allowed to be assigned.
  • Maximum. The maximum value allowed to be assigned.
  • Set As Global. Boolean, if set as true, everytime the stat is updated it will also update the global stat value.
  • Increment Only. Boolean, if set as true, the stat value can only be increased and not decreased
  • Set By. Can be set to game client or game server, depends on which client will call the update stat value API.
  • Status. The default value will be init, and will be changed to tied if the statistic configuration is tied to user. (User’s stats created).
  1. Once completed, click the Add button to add the new statistic configuration.

How It Works

User Statistics

Creating User’s Statistics

After creating the statistics configuration, the statistics need to be tied to a user. This can happens during the first game initialization or during game updates. The configuration has “INIT” status that means that the configuration has not been tied to any user, and also “TIED” status that means that the configuration has already been created for a user. You can tie the statistic configuration to a user by selectively choose the statistics configurations with “INIT” status. There are two ways of doing it, by creating one statistic item at a time or process it in bulk by using multiple stat codes. These API call can be considered sensitive and prone to cheat, thus we suggest you to integrate the call with external game services. The calls can be authorized using both user credentials and client credentials. To implement the API call using your own game service, please follow the client authorization method. You can also use user credentials to authorize the following actions from your game client directly. For more information, please see AccelByte Statistic Service.

Create User’s Statistics Item

Use the admin endpoint to create a statistic item for a single user using your own game service. We suggest you to authorize this API call using your game service’s client credentials. In doing so, you need to have the following permission:

Required permission: resource="ADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEM", action=1 (CREATE)

To create single user’s statistic item, please follow these steps:

  1. Use the UserStatistic: Create User StatItem - POST /v1/admin/namespaces/{namespace}/users/{userId}/stats/{statCode}/statitems endpoint. Here, you need to fill out these fields in order to perform a request:

    Path Parameters:

    • namespace. Namespace of the game where the player statistic attribute is going to be created.
    • userID. User ID / User Alias of the specified namespace.
    • statCode. The statistic code you want to create for the specified player.
  2. On a successful request, the statistic configuration will be tied to the specified user.

Bulk Create User’s Statistics Item

Use the admin endpoint to create bulk statistic items for a single user using your own game service. We suggest you to authorize this API call using your game service’s client credentials. In doing so, you need to have the following permission:

Required permission: resource="ADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEM", action=1 (CREATE)

To create bulk user’s statistic item, please follow these steps:

  1. Use the UserStatistic: Bulk Create StatItems - POST /v1/admin/namespaces/{namespace}/users/{userId}/statitems/bulk endpoint. Here, you need to fill out these fields in order to perform a request:

Path Parameters: namespace. Namespace of the game where the player statistic attributes are going to be created. userId. User ID / User Alias of the specified namespace Request Body Example:

[
{
"statCode": "TOTAL_KILLS"
},
{
"statCode": "TOTAL_DIES"
}
]

Request Body Parameters:

  • statCode. The statistic codes you want to create for the specified player
  1. On a successful request, the statistic configurations will be tied to the specified user.

Retrieving User’s Statistics

Once you have tied the statistics configuration to a player, you can then retrieve the statistics attributes that is tied to a specific player. You can do this using direct API calls or using our SDK's from your game client. Please also refer to the complete Statistics API reference.

Admin - List All User’s Statistics Item

Use the admin endpoint to implement list all user’s statistics item from your own back office application. In doing so, you need to have the following permission:

Required permission: resource="ADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEM", action=2 (READ)

To list all user’s statistic item, please follow these steps: 1. Use the UserStatistic: List All User’s StatItems - GET /v1/admin/namespaces/{namespace}/users/{userId}/statitems endpoint. Here, you need to fill out these fields in order to perform a request:

Path Parameters:

  • namespace. Namespace of the game where the player statistic attributes are going to be retrieved.

  • userId. User ID / User Alias of the specified namespace.

    Query Parameters:

  • statCodes. Specific stat codes you want to query.

  • tags. To query player statistics attributes based on the specified tag.

  • offset. Number of items you wish to skip for the query.

  • limit. Maximum number of items returned in the query

  1. On a successful request, you will be able to retrieve all player statistics attributes or based on the specified query parameters.
Public - List All User’s Statistics Item

Use the public endpoint to implement list all user’s statistics item from your game client. In doing so, you need to have the following permission:

Required permission: resource="NAMESPACE:{namespace}:USER:{userId}:STATITEM", action=2 (READ)

To list all user’s statistic item, please follow these steps:

  1. Use the UserStatistic: List All User’s StatItems - GET /v1/public/namespaces/{namespace}/users/{userId}/statitems endpoint. Here, you need to fill out these fields in order to perform a request:

    Path Parameters:

  • namespace. Namespace of the game where the player statistic attributes are going to be retrieved.

  • userId. User ID / User Alias of the specified namespace.

    Query Parameters:

  • statCodes. Specific stat codes you want to query.

  • tags. To query player statistics attributes based on the specified tag

  • offset. Number of items you wish to skip for the query.

  • limit. Maximum number of items returned in the query

  1. On a successful request, you will be able to retrieve all player statistics attributes or based on the specified query parameters.

Retrieving User’s Statistics from the Client SDKs

There are three ways to retrieve user’s statistic item from SDK: by retrieve all the statistic, filter it by statCodes, or filter it by it’s tags.

Retrieving All User’s Statistic Item

This example will retrieve all of user’s statistic items in a game namespace.

Statistic statistic = AccelBytePlugin.GetStatistic();
Result<StatItemPagingSlicedResult> getAllStatItemsResult = null;
statistic.GetAllUserStatItems(result => { getAllStatItemsResult = result; });
Retrieving User’s Statistic Item by StatCode(s)

This example will only retrieve user’s statistic item for the specified statCode(s) in a game namespace.

Result<StatItemPagingSlicedResult> getStatItemsResult = null;
string[] statCodes = new string[] { "TOTAL_KILLS", "TOTAL_ASSISTS" };
statistic.GetUserStatItemsByStatCodes(statCodes, result => { getStatItemsResult = result; });
Retrieving User’s Statistic Item by Tag(s)

This example will only retrieve user’s statistic item for the specified tag(s) in a game namespace.

Result<StatItemPagingSlicedResult> getStatItemsResult = null;
string[] Tags = new string[] { "INCREMENT", "INGAME" };
statistic.GetUserStatItemsByTags(Tags, result =>
{ getStatItemsResult = result; });
Updating User’s Statistics

Player statistics attributes value can be updated throughout the game. You can update a specific player statistic attribute, or update player statistic attributes in a bulk. These API call can be considered sensitive and prone to cheat, thus we suggest you to integrate the call with external game services. However, we also provide client SDK's functionalities to update user stats. This can be used for cases that do not require less secure API calls. The calls can be authorized using both user credentials and client credentials. To implement the API call using your own game service, please follow the client authorization method. You can also use user credentials to authorize the following actions from your game client directly. For more information, please see AccelByte Statistic Service.

Admin - Update User’s Statistics Item Value

Use the admin endpoint to update a user statistic item using your own game service. We suggest you to authorize this API call using your game service’s client credentials. In doing so, you need to have the following permission:

Required permission: resource="ADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEM", action=4 (UPDATE)

To update a user statistic item, please follow these steps:

  1. Use the UserStatistic: Increase user’s statItem value - PATCH /v1/admin/namespaces/{namespace}/users/{userId}/stats/{statCode}/statitems/value endpoint. Here, you need to fill out these fields in order to perform a request:

    Path Parameters:

  • Namespace. Namespace of the game where the player statistic item will be updated.
  • userId. User ID / User Alias of the specified namespace.
  • statCode. Specific stat codes that you want to update.

Request Body Example:

{
"inc": 5
}

Request Body Parameter:

  • Inc. If you set the increment value as True in the Statistic configuration, you cannot input a negative value. If you set the increment value as False in the Statistic configuration, you can both input a positive or negative value such as 5 or -5.
  1. On a successful request, the user’s statistic item value will be updated.
Public - Update User’s Statistics Item Value

Use the public endpoint to update a user statistic item from your game client. In doing so, you need to have the following permission:

Required permission: resource="NAMESPACE:{namespace}:USER:{userId}:STATITEM", action=4 (UPDATE)

To update a user statistic item, please follow these steps:

  1. Use the UserStatistic: Increase user’s statItem value - PATCH /v1/public/namespaces/{namespace}/users/{userId}/stats/{statCode}/statitems/value endpoint. Here, you need to fill out these fields in order to perform a request:

    Path Parameters:

  • Namespace. Namespace of the game where the player statistic item will be updated.
  • userId. User ID / User Alias of the specified namespace.
  • statCode. Specific stat codes that you want to update.

Request Body Example:

{
"inc": 5
}

Request Body Parameter:

  • Inc. If you set the increment value as True in the Statistic configuration, you cannot input a negative value. If you set the increment value as False in the Statistic configuration, you can both input a positive or negative value such as 5 or -5.
  1. On a successful request, the user’s statistic item value will be updated.
Admin - Update User’s Multiple Stat Items Value

Use the admin endpoint to update a bulk of statistic items for a user using your own game service. We suggest you to authorize this API call using your game service’s client credentials.. In doing so, you need to have the following permission:

Required permission: resource="ADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEM", action=4 (UPDATE)

To update a bulk of user statistic item, please follow these steps:

  1. Use the UserStatistic: Bulk increase user’s statItem value - PATCH /v1/admin/namespaces/{namespace}/users/{userId}/statitems/value/bulk endpoint. Here, you need to fill out these fields in order to perform a request:

    Path Parameters:

  • Namespace. Namespace of the game where the player statistic item will be updated.
  • userId. User ID / User Alias of the specified namespace.

Request Body Example:

[
{
"inc": 3,
"statCode": "TOTAL_KILLS"
}
]

Request Body Parameter:

  • Inc. If you set the increment value as True in the Statistic configuration, you cannot input a negative value. If you set the increment value as False in the Statistic configuration, you can both input a positive or negative value such as 5 or -5.
  • statCode. The statistic code you want to update for the specified player.
  1. On a successful request, the user’s statistic items values will be updated.
Public - Update User’s Multiple Stat Items Value

Use the public endpoint to update a bulk of statistic items for a user from your game client. In doing so, you need to have the following permission:

Required permission: resource="NAMESPACE:{namespace}:USER:{userId}:STATITEM", action=4 (UPDATE)

To update a bulk of user statistic item, please follow these steps:

  1. Use the UserStatistic: Bulk increase user’s statItem value - PATCH PATCH /v1/public/namespaces/{namespace}/users/{userId}/statitems/value/bulk endpoint. Here, you need to fill out these fields in order to perform a request:

    Path Parameters:

  • Namespace. Namespace of the game where the player statistic item will be updated.
  • userId. User ID / User Alias of the specified namespace.

Request Body Example:

[
{
"inc": 3,
"statCode": "TOTAL_KILLS"
}
]

Request Body Parameter:

  • Inc. If you set the increment value as True in the Statistic configuration, you cannot input a negative value. If you set the increment value as False in the Statistic configuration, you can both input a positive or negative value such as 5 or -5.
  • statCode. The statistic code you want to update for the specified player.
  1. On a successful request, the user’s statistic item values will be updated.
Admin - Update Multiple Stat Items of Multiple Users

Use the admin endpoint to update multiple stat items of multiple users using your own game service. We suggest you to authorize this API call using your game service’s client credentials. In doing so, you need to have the following permission:

Required permission: resource="ADMIN:NAMESPACE:{namespace}:STATITEM", action=4 (UPDATE)

To update multiple stat items of multiple users, please follow these steps:

  1. Use the UserStatistic: Bulk increase user’s statItem value - PATCH /v1/admin/namespaces/{namespace}/statitems/value/bulk endpoint. Here, you need to fill out these fields in order to perform a request:

    Path Parameters:

  • Namespace. Namespace of the game where the players’ statistic items will be updated.

Request Body Example:

[
{
"inc": 5,
"userId": "ea6c7dc2fbb311e98f0b362b9e155667",
"statCode": "TOTAL_KILLS"
}
]

Request Body Parameter:

  • Inc. If you set the increment value as True in the Statistic configuration, you cannot input a negative value. If you set the increment value as False in the Statistic configuration, you can both input a positive or negative value such as 5 or -5.
  • userId. User ID / User Alias of the specified namespace.
  • statCode. The statistic code you want to update for the specified player.
  1. On a successful request, the users’ statistic item values will be updated.
Public - Update Multiple Stat Items of Multiple Users

Use the public endpoint to update multiple stat items of multiple users from your game client. In doing so, you need to have the following permission:

Required permission: resource="NAMESPACE:{namespace}:STATITEM", action=4 (UPDATE)

To update multiple stat items of multiple users, please follow these steps:

  1. Use the UserStatistic: Bulk increase user’s statItem value - PATCH /v1/public/namespaces/{namespace}/statitems/value/bulk endpoint. Here, you need to fill out these fields in order to perform a request:

    Path Parameters:

  • Namespace. Namespace of the game where the players’ statistic item will be updated.

Request Body Example:

[
{
"inc": 5,
"userId": "ea6c7dc2fbb311e98f0b362b9e155667",
"statCode": "TOTAL_KILLS"
}
]

Request Body Parameter:

  • Inc. If you set the increment value as True in the Statistic configuration, you cannot input a negative value. If you set the increment value as False in the Statistic configuration, you can both input a positive or negative value such as 5 or -5.
  • userId. User ID / User Alias of the specified namespace.
  • statCode. The statistic code you want to update for the specified player.
  1. On a successful request, the users’ statistic item values will be updated.

Updating User’s Statistics from the Client SDKs

Updating Single User’s Statistic Item

This example is used to update single statistic item of a user.

string statCode = "TOTAL_KILLS";
Result<StatItemIncResult> statItemIncResult = null;
float increasedValue = 1;
statistic.AddUserStatItemValue(statCode, increasedValue,
result => { statItemIncResult = result; });
Updating Multiple User’s Statistic Items

This example is used to update multiple statistic items of a user simultaneously.

Result<BulkStatItemOperationResult[]> BulkAddStatItemValueResult = null;
BulkStatItemInc TOTAL_KILLS = new BulkStatItemInc
{
inc = 1,
statCode = "TOTAL_KILLS"
};
BulkStatItemInc[] data = new BulkStatItemInc[] { TOTAL_KILLS };
statistic.BulkAddUserStatItemValue(data,
result => { BulkAddStatItemValueResult = result; });
Updating Multiple Statistic Items of Multiple Users

This example is used to update multiple statistic items of multiple users simultaneously. This can be authorized by a user with higher privileges such as admin.

Result<BulkStatItemOperationResult[]> BulkAddStatItemValueResult = null;
BulkUserStatItemInc TOTAL_KILLS= new BulkUserStatItemInc
{
inc = 1,
profileId = "a user’s id",
statCode = "TOTAL_KILLS"
};
BulkUserStatItemInc[] data = new BulkUserStatItemInc[] { TOTAL_KILLS};
statistic.BulkAddStatItemValue(data,
result => { BulkAddStatItemValueResult = result; });

Global Statistics

Global statistics accumulate users’ statistics globally. It can be used for tracking purposes, so it is easier for you to track important game wide statistics in real-time. Global statistics also can be used to trigger further actions such as events, or announcements. You can query global statistics based on a specific namespace.

List of All Global Statistic Items

You can get a list of all the statistic items that you set globally. In doing so, you need to have the following permission:

Required permission: resource="ADMIN:NAMESPACE:{namespace}:STATITEM", action=2 (READ)

To list all global statistic items, please follow these steps:

  1. Use the GlobalStatistic:List All Global Statistic Items - POST ​/v1​/admin​/namespaces​/{namespace}​/globalstatitems endpoint. Here, you need to fill out these fields in order to perform a request:

    Path Parameters:

  • namespace. Namespace of the game where you want to query the global statistics item from.

    Query Parameters:

  • offset. Number of items you wish to skip for the query.

  • limit. Maximum number of items returned in the query.

  1. On a successful request, you will be able to retrieve all global statistics items in that specified namespace.

What’s Next?