• Promotions
• Advertising
• Leaderboards

Overview

Collective leaderboards are intended to allow players to anonymously submit score information and then provide statistics on those scores.
It allows you to give contextual information to the player regarding their score compared to the leaderboard, such as:

• How many people have submitted a score today - "You are the 4th person to score today!"
• What percentage of people are above/below them - "You are in the top 30% of worldwide players!"
• Whether they got the best/worst score today/this week/all time - "You got the best score this week!"

Create a Leaderboard

Leaderboards are created at https://wirthwhilegaming.com/developer/leaderboard/create.

Field	Description
Leaderboard Name	A reference just for you to easily find a leaderboard.
Game	The game the leaderboard is for, a game must be set up first.
Score Ordering	Whether larger scores or smaller scores are better. Allows the API to return the 'best' score for you without having to check for the largest/smallest score.
Remove Score Out of Range	Using this will not add scores outside the range you specify when the API is called.
Minimum Score Allowed	Optional - smallest score that can be recorded. Only necessary if removing scores out of range.
Minimum Score Allowed	Optional - largest score that can be recorded. Only necessary if removing scores out of range.
Initialise Leaderboard	Allows you to set an initial state if your leaderboard exists before using this service.
Current Maximum Score	Optional - largest score on your leaderboard currently.
Current Minimum Score	Optional - smallest score on your leaderboard currently.
Current Score Count	Optional - number of scores on your leaderboard currently.
Current Score Sum	Optional - the sum of the scores on your leaderboard currently.

NOTE If you cannot get all of your leaderboard data for initialising, just put in the minimum and maximum scores, a count of 2 and the sum of the minimum and maximum scores. The data should even out over time with those initial values.

How to submit scores

All scores are stored internally as integers, this is reduce any precision errors. If you need to store float values, we suggest determining the precision from within your game. For example:
If you have a maximum of 3 decimal places, then multiply all scores by 1000 when submitting, then when analysing the score data remember to divide those scores by 1000. With a precision of 3, a score of 23.679 would be submitted as 23679 and 43.2 would be submitted as 43200.

Recording a Score

Request

https://wirthwhilegaming.com/api/leaderboard/record_score?leaderboard_key=KEY&score=SCORE&test=1

Field	Description
leaderboard_key	A 6 character unique identifier for your leaderboard. Can be found at https://wirthwhilegaming.com/developer/leaderboard.
score	The player's score as an integer.
test	Either a 1 or 0. Used for sending data to the test leaderboard (1) or live leaderboard (0).

Response

{
	"success":true,
	"scores":[
		{
			"score_max":"94",
			"score_min":"54",
			"score_count":"5",
			"score_average":"83",
			"score_best":"94",
			"timeframe":"today",
			"percentile":100
		},
		{
			"score_max":"578",
			"score_min":"0",
			"score_count":"22",
			"score_average":"127",
			"score_best":"578",
			"timeframe":"last_seven_days",
			"percentile":16
		},
		{
			"score_max":"868",
			"score_min":"0",
			"score_count":"40",
			"score_average":"154",
			"score_best":"868",
			"timeframe":"all_time",
			"percentile":10
		}
	]
}

The scores are returned in array of aggregated timeframes.

Field	Description
score_max	The maximum score for the timeframe.
score_min	The minimum score for the timeframe.
score_count	The number of scores submitted in the timeframe.
score_average	The average score for the timeframe. Calculated as ceil(SUM(score_sum) / SUM(score_count))
score_best	Will be the same as score_max or score_min depending on whether you chose ascending or descending sort order for the leaderboard.
timeframe	A string representing the time the data is calculated from. These strings will not be changed, but more could be added in the future.
percentile	How the player's score compares to the existing data. 100 is the best score and 0 is the worst score. For example a value of 85 means that the player is the top 15% of players.

Score Summary

Request

Used for getting the current leaderboard stats without recording a score.

https://wirthwhilegaming.com/api/leaderboard/get_summary?leaderboard_key=KEY&test=1

Field	Description
leaderboard_key	A 6 character unique identifier for your leaderboard. Can be found at https://wirthwhilegaming.com/developer/leaderboard.
test	Either a 1 or 0. Used for sending data to the test leaderboard (1) or live leaderboard (0).

Response

Returns in the same format as record_score above, except there is no percentile field as there is nothing to compare against.

Unity

This unity package shows examples of how to use this API.

How charges are calculated

Every 24 hours your daily unpaid leaderboard entries will be charged. You will be charged credits equal to the number of submitted scores divided by 1000 rounded up to the nearest whole number.

For example if you had 1500 scores submitted on one day the charges would be ceiling(1500 / 1000) = 2 credits.