Developing with Leaderboards
Leaderboards is a Service. It is a persistent, open data store for easy setting and getting of scores, achievements and other user performance data. It provides convenience functions for retrieving rankings, adding and retrieving arbitrary data.
The Leaderboards Service optimised for high volume reads, making it a fast and convenient way to deliver scoring to high volume games. It is not optimised for high volume writes, meaning you should be careful how you utilise it. You should carefully consider and adopt Best Practices below in creating your application.
Leaderboards is designed to make it easy for TV Graphics to retrieve data via the REST API. However, if you're making a JavaScript app, the Javascript library is more convenient and avoids versioning issues when the API is updated.
API Reference Leaderboard Javascript library Leaderboard REST API
Leaderboard is a service which allows an application to:
Store and fetch user score
Store and fetch arbitrary user data
Store and fetch user achievements level
Fetch level statistics
Fetch top N entries
Fetch ranks for specified list of users
Fetch neighbours' ranks - X entries above, own rank, Y entries below
Fetch top selected entries
A leaderboard can be linked to a Project or Event.
Project-level leaderboard will always show up within main navigation, no matter what Event is currently selected, as it applies to the Project rather than a specific Event. An example would be a leaderboard storing user score and rank for the whole series of a game show.
Event-level leaderboard will only appear in the main navigation if corresponding Event is currently selected within Studio as it contains Event-specific data, for example user performance data within a specific Event.
In order to create Event-level leaderboard you need to pass eventId parameter to leaderboard constructor when you initialise Leaderboard JavaScript API.
A leaderboard can be added to your app within the Services section of the App Spec.
Scaling Up
Leaderboards is a dedicated service that must be scaled up for big events, please ensure that we're aware of any expected spikes.
Leaderboards is relatively insecure at present, using plain text and no particular obfuscation or authentication, you use at your own risk. It is not intended as an alternative to secure identity storage. Do not use Leaderboards to store passwords or any sensitive data.
Leaderboards is designed to make it easy for TV Graphics to retrieve data via the REST API. However, if you're making a JavaScript app, the JavaScript library is more convenient and avoids versioning issues when the API is updated.
Design your app so that it does not create unnecessary spikes of leaderboard requests. For example if the app submits user score as soon as it receives a trigger from the server and most clients receive the trigger at the same time then this will create a sharp spike. Instead you can have a random delay inserted between receiving the trigger and submitting the score into the leaderboard. Generally don't trigger a leaderboard action for all users at the same time.
The Leaderboard service provides an eventual consistency rather than transactional type of operation. This means that if the app is retrieving user ranking right after submitting a new score then the ranking might or might not reflect the score which was just submitted. Same applies to all other data changes. To maximise the probability of retrieving an up-to-date rank the app can first fetch the user score and check that it matches the one submitted.
As the data could be changing all the time different clients can retrieve different leaderboards even if they make the request at the same time. This could result in the app showing different leaderboards to different users at the same time. In order to guarantee that everyone sees exactly the same data the leaderboard should be published via an M/IC Element instead of pulled by each client app separately.
If leaderboard data is used for TV graphics or in any other context where pre-moderation is required you can use "selection" feature of the leaderboard. This allows the Producer to vet leaderboard records and then guarantees that they won't be changed through end user actions. An example would be when user profile pictures are displayed on TV and you want to avoid the risk of end user changing the picture to something inappropriate after you've vetted their record.
