Last Updated: 7/14/2021, 11:21:36 AM

# Statistics

# Overview

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

# 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 statistics in the Admin Portal:

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 a 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

# Managing Statistics in the Admin Portal

# Create a New Statistic Configuration

  1. In the Statistics section of the Admin Portal, open the Configurations menu.

cloud-save

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

cloud-save

  1. Fill in the required fields.

cloud-save

  • Input the statistic code in the Code field, following the formatting rules given.
  • 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 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 select either the game client or game server. This determines which client will update the stat value.
  • Input the Tag field with contextual information related to the statistic. This field is optional.

# Retrieve Global Statistics

  1. In the Admin Portal, click the Statistics Value menu.

cloud-save

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

cloud-save

# Managing Statistics Using the SDK

# Create a Single Statistic for a Player

You can use SDK to create a statistic for a player from your game server by following the example below.

# Create Multiple Statistics for a Player

To create statistics for a player in bulk, follow the example below.

# Retrieve a Player’s Statistic by StatCode

This example will only retrieve a player's statistic for the specified statCode in a game namespace.

# Retrieving a Player’s Statistic by Tag

This example will only retrieve a player's statistic for the specified tag in a game namespace.

# Update Multiple Statistics for a Player

This example is used to update multiple statistics for a player simultaneously.

# Update Multiple Statistics for Multiple Players

This example is used to update multiple statistics for multiple players simultaneously. This update must be authorized by a user with higher privileges, such as an admin.

# Managing Statistics Using the API

# Create a New Statistic Configuration

  1. Use the Create Stat: POST - /v1/admin/namespaces/{namespace}/stats (opens new window) endpoint.

  2. Input the Namespace field with the game namespace.

  3. Fill out the Request Body:

    • Input the statistic code in the statCode field, following the formatting rules below.

      Statistic Code Formatting Rules
      • Only lowercase alphanumeric (a-z and 0-9) characters are allowed
      • Spaces a not allowed
      • The code must start and end in a lowercase letter
      • Hyphens (-) are the only separator allowed
      • Separators cannot appear twice or more in a row
    • Input the Name of the configuration.

    • Input a Description of the configuration. This field is optional.

    • Define the maximum value of the statistic in Max. Value field.

    • Define the minimum value of the statistic in the Min. Value field.

    • Input the Default Value of the statistic.

    • Input the Increment value. If set to true, the stat value can only be increased. If false, the stat value can be increased or decreased.

    • Input the Set As Global value. If set to true, every time the stat is updated the global stat value will also be updated.

    • Input the Set By value. You can input either the game client or game server. This determines which client will update the stat value.

    • Input the Tag field with contextual information related to the statistic. This field is optional.

Upon successful request, a new statistic configuration will be created. Here is an example of a response to a successful request:

# Create Statistics for Players

To create a statistic for a player, follow the steps below.

  1. Use the Create User’s Stat Item: POST - /v1/admin/namespaces/{namespace}/users/{userId}/stats/{statCode}/statitems (opens new window) endpoint.
  2. Input the Namespace field with the game namespace.
  3. Input the User ID you want to tie to the statistic.
  4. Input the Stat Code to be tied to the user.

Upon successful request, the statistic configuration will be tied to the specified user. Upon successful request, the statistic configuration will be tied to the specified user. A successful request returns Code 201 Created (opens new window), which indicates that the request was successful.

# Create a Multiple Statistics for a Player

To create multiple statistics for a player, follow the steps below.

  1. Use the Bulk Create Users Stat Items: POST - /v1/admin/namespaces/{namespace}/users/{userId}/statitems/bulk (opens new window) endpoint.
  2. Input the Namespace field with the game namespace.
  3. Input the User ID you want to tie to the statistic.
  4. Input the statCode to be tied to the user in the bulkStatItemCreateList. Here you can input several stat codes to be tied to the user.

Upon successful request, the statistic configurations will be tied to the specified user. Here is an example of a response to a successful request:

# Retrieve All of a Player’s Statistics

To list all of a player’s statistics, follow these steps:

  1. Use the List User’s StatItems: GET - /v1/admin/namespaces/{namespace}/users/{userId}/statitems (opens new window) endpoint.
  2. Input the Namespace where the configuration belongs. This field is required.
  3. Input the player’s User ID. This field is required.
  4. Input the statCode of the statistic you want to retrieve.

The following fields are optional. You can fill them in if you want to paginate the results.

  1. Input the tags of the statistics to query player statistics attributes based on the specified tag.
  2. Input the offset of items you want to skip for the query.
  3. Input the limit with the maximum number of items you want to display.

Upon successful request, you will be able to retrieve all of a player’s statistics, based on the specified query parameters. Here is an example of a response to a successful request:

# Update a Player’s Statistics

To update a player’s statistic, follow these steps:

  1. Use the Update User’s Statitem Value: PATCH - /v1/admin/namespaces/{namespace}/users/{userId}/stats/{statCode}/statitems/value (opens new window) endpoint.
  2. Input the Namespace where the configuration belongs.
  3. Input the player’s User ID.
  4. Input the statCode of the statistic you want to update.
  5. Define the statItemInc. If set to true, the stat value can only be increased. If false, the stat value can be increased or decreased.

Upon successful request, you will be able to update the player's statistic. Here is an example of a response to a successful request:

# Update Multiple Statistics for Multiple Players

To update multiple statistics for multiple players, follow these steps.

  1. Use the Bulk Update Multiple User’s StatItem Value: PATCH - /v1/admin/namespaces/{namespace}/statitems/value/bulk (opens new window) endpoint.
  2. Input the Namespace where the configuration belongs.
  3. Define the statItemInc.
    • Input the inc value. If set to true, the stat value can only be increased. If false, the stat value can be increased or decreased.
    • Input the statCodes of the statistics you want to update.
    • Input the User IDs of the players whose statistics you want to update.

Upon successful request, you will be able to update the specified statistics. Here is an example of a response to a successful request:

# Retrieve Global Statistics

To list all global statistics, follow the steps below.

  1. Use the List All Global Statistic Items: POST - ​/v1​/admin​/namespaces​/{namespace}​/globalstatitems (opens new window) endpoint.
  2. Input the Namespace where the configuration belongs. This field is required.

The following fields are optional. They can be filled in if you want to paginate your results.

  1. Input the offset of items you want to skip for the query.
  2. Input the limit with the maximum number of items you want to display.

Upon successful request, the global statistics will be retrieved. Here is an example of a response to a successful request: