Admin API Workflows
The Admin API enables you to automate tasks or sequences of tasks that you perform frequently using the Leaderboards and Tournaments Console.
Admin API Overview
The admin API provides methods to add tournaments, create prize lists, create Requirements Groups, and close down tournaments.
We recommend that you use the Leaderboards and Tournaments Console to create and manage tournaments. However, some advanced features are currently not available in the Leaderboards and Tournaments Console. For example, you need to use the Admin API to define Requirement Groups.
Match, player and attempt limits
A number of inter-related parameters determine the maximum number of players, matches and player attempts in a tournament. Note the following definitions:
matchesMax: Maximum number of matches per tournament. Each match replicates its parent tournament for start dates, end dates, and prizes to be awarded. A tournament that has 10 matches also has 10 leaderboards, 10 first prize winners and so on. For the simplest scenario of a single match per tournament, set matchesMax = 1. Range: 1 - 50.
matchesPerPlayer: A single player is able to join in multiple matches in a tournament (for a tournament that offers multiple matches). Range: 1 - 50 or matchesMax (the lower value).
playerAttemptsPerMatch: Maximum number of times a player can attempt to play in a match, also the number of times the player can submit score in that match. Range: 1 - 1,000,000,000
playerAttempts: Maximum number of times a player submit score to their team in a team format tournament.
playersPerMatch: Maximum number of players in a match and its leaderboard. Max limit: 1,000,000,000
Admin API workflows
To use the Admin API, you need to provide the Admin API Key in the request header. You can find the game API key in the game settings panel of the Leaderboards and Tournaments Console. See the following figure:
Register Player
Similar to the Game API, Register Player adds a player (and their device) to Amazon Leaderboards and Tournaments, conducts a key exchange, and returns an encryted token. However, with the Admin API version, you can also provide a vendorPlayerId to allow multi device account registration.
Tournaments
Add a tournament for entities like players to join and compete against one another. A tournament created with this endpoint currently has two different participant types: individual and team.
Create Prizes
You can create digital prizes for competitions. Digital prizes are fulfilled by the developer and can be created as described below.
{
"prizes": [
{
"description": "This chest contains better loot than the Silver Chest.",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
"title": "Golden Chest",
"prizeInfo": "GOLDEN_CHEST_0124"
},
{
"description": "Live forever with this bundle of health potions.",
"imageUrl": "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
"title": "100 Health Potions",
"prizeInfo": "HEALTH_POTIONS_100"
}
]
}
Create a Requirement Group
Use the Add Requirement List method to create a Requirement Group. Define the fields in the request body. There are four different types of Requirements. For details, see Requirement Types. You can mix the different types in the same list, as shown in the following example:
{
"requirements": [
{
"name": "Player is VIP",
"description": "The player has VIP status.",
"type": "value",
"key": "status",
"value": "VIP"
},
{
"name": "Player is a beginner",
"description": "The player has a skill between 0 and 10.",
"type": "range",
"key": "League",
"high": 10,
"low": 0
},
{
"name": "Greater Seattle Area",
"description": "The GPS coordinates of the player is located in the Greater Seattle Area",
"type": "gps",
"key": "gpsCoordinates",
"permittedAreas": [
{
"gpsCoordinates": {
"latitude": 47.60604,
"longitude": -122.3328
},
"radius": 10,
"radiusUnits": "KILOMETERS"
}
]
}
]
}
Add game stats
Add stats to the Update Game request to create the game stats for a game.
Example UpdateGameRequest Body:
{
"gameStats":[
"kills", "assists", "survivalTime"
]
}
The gameStats array needs to include all of the existing stats (if any) and the new stats that you want to add.
Note the following restrictions for Stat names:
- maximum of 35 characters
- the name can contain spaces, but not special characters (such as brackets, quotes, =, +, or |)
- names are not case sensitive. For example, "coins" and "COINS" will be treated as identical.
For additional information, see the Update Game API reference.
Select a leaderboard stat
When you create a new competition using the API, you must specify which stat to use for the leaderboard (“leaderboardStat”).
Example AddTournamentRequest Body:
{
"title":"TournamentWithStats",
"description":"test",
"subtitle":"test",
"matchesMax":10,
"playerAttemptsPerMatch":3,
"playersPerMatch":50,
"matchesPerPlayer":1,
"dateStart":1548748800000,
"dateEnd":1548921600000,
"participantType":"individual",
"releaseType":"auto",
"leaderboardStat":"kills"
}
For additional information, see the AddTournament API reference.