Amazon GameOn recently added stats-based leaderboard APIs so developers can create even more dynamic competitions to keep players engaged. We know people love connecting through competition, and leaderboards keep players excited to keep competing to beat the top scores. According to Newzoo's 2018 Global Esports Market Report, 70% of frequent tournament participants spend money in mobile games (vs. 26% who don't compete in tournaments).

Now, with the new APIs, developers using GameOn can create competitions and leaderboards for a variety of player stats for any title—from core to hyper casual. Your endless runner can now add a leaderboard stat for number of coins/gems/bananas collected on a run. Your battle royale title can now add number of items crafted or number of headshots. Your racing game can track clean driving, lap times, or power slide length. With so many options for leaderboards, developers have endless ways to keep their community engaged with unique tournaments.

Stats-based leaderboard APIs allow GameOn developers to submit multiple stat attributes and corresponding values instead of just one score. Community managers, product managers, etc. can then select a stat to be the ranking for the leaderboard for the competition. This creates a variety of competitions to keep players engaged and coming back for more. Games that have integrated with the GameOn Tournament Organizer can also extend this feature to Twitch streamers, who can then select stats for their leaderboard competitions.

To support stats-based leaderboards, you must declare the stats [gameStats] at a game-level setting using the admin API or GameOn console. When you create a new competition using the APIs, you must specify which stat to use for the leaderboard [leaderboardStat]. If your game is already integrated with GameOn, there are only minimal changes required in submitScore and getTournaments to integrate with the new APIs.

If you do not wish to take advantage of the multi-stat feature in your game, no updates are required. Your current integration will remain compatible with existing and new tournaments.

Getting started

To add stats-based leaderboards to your game, the first step is to declare stats. This can be done through the Game Settings page on GameOn console or using the updateGame admin API:
 

Next, the game will need to be updated to submit your newly-named game stats. It is recommended that, once implemented, the game include all stats declared in “gameStats” for each score submission. However, requests where the game submits a single stat based on the tournament's details will not fail as long as the tournament's “leaderboardStat” is included in “stats” array.

SubmitScoreRequest sample WITHOUT multi-stat:

{
    “score”: 100
}

SubmitScoreRequest sample WITH multi-stat:

{
    “score”: 100,
    “stats”:[
    {
        “name”:”kills”,
        “value”:”20”
    },
    {
        “name”:”head shots”,
        “value”:”30”
    },
    {
        “name”:”coins”,
        “value”:”40”
    }
}

Once you've implemented your new game stats, you will need to update the way your game makes GetTournament requests. In order to access these new stat-based leaderboards, your game is required to pass in stats values in “playerAttributes” query parameter to retrieve stats-based tournaments. Once this query parameter is added to your request, the request will include both score-based and stat-based tournaments. If a player has not updated their app once your new stats-based leaderboard build is deployed, they will successfully be able to participate in any score-based tournaments; however, they will not have any visibility into stats-based tournaments to avoid a broken experience.

As a best practice, the GameOn team recommends filtering tournaments in-game to distinguish between stat-based and score-based tournaments. It is also recommended that you indicate to players which stat is being tracked for each tournament. See full stats-based leaderboard documentation for a list of all APIs that will provide “leaderboardStat” field in the response.

After your stats-based leaderboard implementation has been tested (see documentation for recommended handling scenarios), your new stats-based tournaments are ready for set up using the GameOn console or admin APIs.

In the GameOn console, your preset game stats will be available for selection under leaderboard rules:
 

If setting up tournaments via admin APIs, you will need to add “leaderboardStat” as a new field to your AddTournamentRequest body. Be sure that the value you enter for “leaderboardStat” is a previously declared “gameStats." If creating score-based tournaments for players using older clients, no additions need to be made to the AddTournamentRequest.

For full documentation on enabling stats-based leaderboards or getting started with any GameOn features, visit the GameOn Guide - Getting Started for Developers. The GameOn team looks forward to seeing all the different types of game stats and stat-based leaderboards you can now surface in your game by using stats-based leaderboard APIs!