Skip to main content

Leaderboards

Enabling or disable leaderboards for your games

Microsoft can provide leaderboards for your games to level up the fun and competition. To enable this functionality, we need to know some basic information about the scores your game will report via our SDK, which you will need to define as part of your PWA Manifest JSON file.

note

You may already have leaderboards enabled for certain games, prior to the release of this self-serve functionality. In this case you are not required to add PWA manifest configuration, but you may for consistency.

Process Overview​

  1. Define leaderboard configuration for a game in its PWA manifest JSON. We will create or update leaderboards for your game to match this configuration.
  2. Release the PWA manifest updates by updating your file hosting with the new version.
  3. We will periodically process changes to PWA manfiest entries and create or update leaderboards for your games. Updates should be processed within a few hours.
  4. Integrate with our Leaderboard SDK to write player scores to your leaderboards. This integration can be done ahead of time, but SDK calls will be rejected while no active leaderboards exist for your game.
caution

The ability to update already-created leaderboards is currently limited. Once a leaderboard is created changes to score_type and score_order_by fields will be ignored, so please ensure your configuration is correct before releasing them.

Configuration​

A typical leaderboard configuration within a PWA manifest will look as follows:

{
  ...
  "_msstart": {
    "leaderboards": {
      "default": {
        "score_type": "Numeric",
        "score_order_by": "Desc"
      }
    }
  }
}

All that is required for leaderboards is to define score_type and score_order_by so we know the data type of scores and how to sort those scores to generate a leaderboard! The remaining fields have defaults, and are optional.

_msstart​

The root property _msstart will contain all Microsoft internal configuration for a game (not just leaderboards).

Kind: object

leaderboards​

The leaderboards property holds all leaderboard configuration.

Kind: object

default​

The default property defines the leaderboard configuration for Microsoft-defined leaderboards. In the future we may provide support for custom-defined leaderboards (ie. "Level 1 Top Scores") as well as SDK functionality to report scores for a specific leaderboard.

note

Please note that this property applies to all Microsoft-provided leaderboards, not a single leaderboard.

At this time, we provide an "All Time" leaderboard and a "Friends" (social) leaderboard. In the future we may include "Weekly" or "Daily" leaderboards as well.

Kind: object

score_type​

The data type a score represents. Must be an enumeration of the following:

  • "Numeric" : An integer value, which may encode a decimal when used in conjunction with score_decimal_places
  • "Duration" : An amount of elapsed time, stored in milliseconds

Kind: string

score_order_by​

Defines how scores sort to generate leaderboards. Must be one of the following:

  • "Desc" : Larger scores are better
  • "Asc" : Smaller scores are better

Kind: string

score_decimal_places​

Defines the number of decimal places to include for Numeric score_type leaderboards. Scores are always reported as integers. To encode a raw value of 1.337, set score_decimal_places to 3 and report the score as 1337. See our leaderboards SDK page for more information.

Kind: number

Default: 0

show_total_players​

If you wish to hide the total player count in a leaderboard, set the value of this property to false.

Kind: boolean

Default: true

enabled​

Are default leaderboards enabled. If you wish to disable and hide default (Microsoft-defined) leaderboards for your game, set the value of this property to false.

Kind: boolean

Default: true

Common Issues​

I've defined a leaderboard in my manifest, but I don't see any leaderboard show up on the gameplay page for my game.

Leaderboard processing runs offline on a schedule. It may take an hour or more for your changes to take effect.

Even after leaderboards are created, a minimum number of reported scores are required to display them. In such cases, you can check if the response to the CasualGamesLeaderboardContentV2 XHR on the gameplay page returns a 200 with data. It should return a leaderboard response, though certain fields will be null.

Check if you have a configuration issue. Any typos in keys or values could cause processing to fail. As this processing is internal, we do not yet have an automated way of notifying game developers of issues.

If you are still having issues, reach out to us to help!

Leaderboards don't look right, or I mistakenly added/misconfigured leaderboards for a game.

We don't yet have the ability to recreate leaderboards self-serve, but you can disable (which hides) leaderboards using the enabled property.

Reach out to our team for help if you need to recreate your leaderboard with a new configuration.