Stats-based Leaderboards

Game developers typically submit multiple score attributes (stats) per player in a match. The Leaderboards and Tournaments Stats-based Leaderboards feature enables you to define a set of stats for the game (known as the game stats) and then select a stat to use for each tournament leaderboard (this stat is known as the leaderboard stat).

You can use stats-based leaderboards to host competitions with more variety of leaderboards.

• Workflow overview
• Game API Workflow
  • Submit score
  • (Optional) Display leaderboard stat
  • (Optional) Get tournaments
  • (Optional) Enter Tournament and Enter Match
• FAQ
• Create Stats Requirements

Workflow overview

Note the following steps to implement stats-based leaderboards in a game. These steps are described in further detail in the sections below:

1. Use the Leaderboards and Tournaments Console to add game stats to a new game or an existing game. You can also use the Admin API.

2. When you create a tournament with the Leaderboards and Tournaments Console, select a leaderboard stat for the tournament. You can also use the Admin API.

   The following tasks refer to Game API requests in your game software:

3. Submit Score: where the game submits the player score, include values for each game stat.
4. (optional) Display Leaderboard Stat: display the leaderboard stat for the current tournament.
5. (optional) Get Tournaments: Filter the list of tournaments that you display to the player to include only tournaments that the player's game client supports.
6. (optional) Enter Tournament and Enter Match: Add entry requirements, so that players can enter only the tournaments that their game client supports.

Game API Workflow

Changes to the game API are described in the sections below.

Submit score

The minimum requirement for a successful score submission is to include the tournament leaderboardStat or the score (when "leaderboardStat" is null) in the Submit Score request from your game. However, Leaderboards and Tournaments recommends that you submit a value for score and values for all game stats in each score submission.

Example Submit Score entry:

{  
    "score": 100,
    "stats":[
      {  
         "name":"kills",
         "value":100
      },
      {  
         "name":"assists",
         "value":45
      },
      {  
         "name":"survivalTime",
         "value":15
      }
   ]
}

For additional information, see the Submit Score API reference.

(Optional) Display leaderboard stat

As a best practice, your game should display the stat that is being tracked for each tournament. The APIs noted below will provide the leaderboardStat field in the response, so that you can surface the information in the game:

GET /tournaments
GET /tournaments/{tournamentId}
GET /player-tournaments
GET /player-tournaments/{tournamentId}
GET /matches
GET /matches/{matchId}
GET /matches/{matchId}/leaderboard

For additional information, see the Game API reference.

(Optional) Get tournaments

To ensure a positive player experience, you should display only the tournaments whose leaderboard stats are supported by the player's version of the game client. You can add playerAttributes in the Get Tournaments request to filter the list of tournaments based on stat. For details, see the Create Stats Requirements section below.

(Optional) Enter Tournament and Enter Match

You can add playerAttributes in the Enter Tournament and Enter Match requests, so that players can enter only tournaments that their game client supports. For details, see the Create Stats Requirements section below.

FAQ

Q: Should I submit “score” or “stats” in SubmitScore request?

After you add game stats to your game, you can create some competitions based on a game stat and other competitions based on score. Competitions based on your game can use any of the game stats as the leaderboard stat, so we recommend that you submit values for all game stats in every Submit Score request.

We also recommend that you include a value for score in your Submit Score request, because someone could create a competition for your game based on score. The following roles can create competitions:

• Anyone who has admin access for your game
• Game players, if your game integrates with Player Tournaments.

Adding the score field and stat fields in the request body does not cause an API error. However, the Submit Score request will fail if the leaderboard stat value is missing for a tournament that is based on stat, or if the score value is missing for a tournament that is based on score.

Q: How do I introduce additional stats to a game?

If you update your game to support new stats, your players need to update to the new game version to successfully participate in any tournament that is based on a newly-added stat.

If your game may introduce new game stats in a future release and you are not able to force a client update or inform players to update the game, we recommend that you implement the following additional mechanisms in your game to handle any potential future errors:

1. Display a message dialog if a Submit Score validation error occurs.

   When Submit Score fails with status code 400 (Bad Request) or Error Code 3 (Validation Errors), display a message dialog in the game to inform the player that they need to update their game to participate in this tournament.

2. Use Leaderboards and Tournaments Stats Requirements to stop players from entering a tournament with a leaderboard stat that the game client does not support. You can also display a message dialog to notify players that their client is not supported by the newer tournaments, to motivate the players to update their game.

Q: My game has already integrated with Leaderboards and Tournaments (without the best practices recommended above), and I want to start to use stats or add more stats in a new game version. What will happen to players with old clients?

Your players need to update to the new game version to successfully participate in the tournaments that are based on newly-added stats. If players do not update to the new game version, their score submission for those new tournaments will fail, and their score will not be reflected in the leaderboard.

If you cannot force a game update (or inform players to update the game), we recommend that you use Leaderboards and Tournaments Stat Requirements to hide the new tournaments from older game clients, to prevent negative user experiences.

Q: How do I delete stats?

Currently, the API does not support the ability to delete stats. Please contact us if you want to delete specific stats.

Create Stats Requirements

To create and use tournament entry and visibility requirements for game stats:

• Define the stat requirements.
• Set the entry and visibility requirements for the tournament.
• In the Game API, include player attributes in the Enter Tournament and Enter Match requests.
• Include player attributes in the Get Tournaments request to filter out tournaments that the player cannot enter.

1. Define the stat requirements.

   Use the Admin API to add a requirement list for each game stat. In the request body, the "key" must be "stats" which is a reserved word, the "type" must be "contains" which is a reserved type, and the values field is a list. Enter the new stat name that you want to add as a requirement.

   For additional details, see Add Requirement List.

   In the following example, we add a requirements for kills:

   {
     "requirements": [
       {
         "name": "Kills supported",
         "description": "Anything you want to describe",
         "type": "contains",
         "key": "stats",
         "values": ["kills"]
       }
     ]
   }
   

   The response includes the requirement Id, which you will need in the next step.

   {
     "addedRequirements": [
       {
         "name": "Kills supported",
         "description": "Anything you want to describe",
         "type": "contains",
         "key": "stats",
         "values": ["kills"]
         "requirementId": "f17abf7f-df0a-4b78-b28a-ddad30f9abf7"
       }
     ]
   }
   

2. Set entry and visibility requirements for the tournament.

   You can use the Leaderboards and Tournaments Console to set the requirements.

   You can also use the Admin API Add Tournament request.

   In the following example, we set the kills requirement as the entry requirement and visibility requirement for the tournament. Note that the requirement name and the leaderboard stat name must match:

   {  
      "title":"TournamentWithStats",
      "description":"test",
      "subtitle":"test",
      "matchesMax":10,
      "playerAttemptsPerMatch":3,
      "playersPerMatch":50,
      "matchesPerPlayer":1,
      "dateStart":1548748800000,
      "dateEnd":1548921600000,
      "participantType":"individual",
      "releaseType":"auto",
      "leaderboardStat":"kills",  
      "entryRequirements": [
          ["f17abf7f-df0a-4b78-b28a-ddad30f9abf7"]
       ],
       "visibilityRequirements": [
           ["f17abf7f-df0a-4b78-b28a-ddad30f9abf7"]
       ]
   }
   

3. In the Game API, include player attributes in the Enter Tournament and Enter Match requests.

   Note that the key must be "stats", which is a reserved word. The value must be a formatted string that includes all of the game stat names delimited with the pipe character. In this example, all players using this game version are qualified to enter tournaments whose leaderboardStat is either "kills" or "assists" (assuming that there is a stat entry requirement that matches the leaderboardStat).

    {
        "playerAttributes" : {
            "stats" : "kills|assists"
        }
    }
   

   If a later version of your game includes a new stat ("survivalTime"), you can create a new Stat Requirement for survivalTime and attach it as a stat entry requirement to all tournaments that use survivalTime as the leaderboard stat. In this version of the game, you should add survivalTime to the playerAttributes as shown below. Only the players with the new game version can enter tournaments with survivalTime as the leaderboardStat.

    {
        "playerAttributes" : {
            "stats" : "kills|assists|survivalTime"
        }
    }
   

4. In the Game API, include player attributes in the Get Tournaments request. Add all of the current game stats values to the player attributes. All players with this game client version will see the tournaments whose stat visibility requirement matches an entry in the playerAttributes list.

   Players with older clients will only see tournaments that do not have visibility requirements.

   GET /tournaments?playerAttributes={"stats": "kills|assists"}