Leaderboards V2
Leaderboards are a standard gamification element that nearly every game needs to have to drive user retention. Our solution is tightly integrated into the SCILL ecosystem and can be easily added to any app or game that already has SCILL events implemented.
Leverage SCILL’s easy-to-use backends to send event data, build leaderboards visually with our leaderboards creator in the Admin Panel and implement them in a couple of hours into your existing application or game.
Leaderboard object
Leaderboard
objects are comprehensive objects that contain all data that is required to render leaderboards.
Parameters
leaderboard_id string
The id of the leaderboard
name string
The name of the leaderboard
grouped_by_users array
An array of LeaderboardRanking Items for individual users
grouped_by_teams array
An array of LeaderboardRanking Items for teams. Provide a team_id in the event payload to also create leaderboards for teams
num_teams number
The total number of team rankings available in the leaderboard
num_users number
The total number of user rankings available in the leaderboard
{
"leaderboard_id": "641184035742547979",
"name": "Hall of Fame",
"grouped_by_users": [
{
"member_id": "1234567",
"member_type": "user",
"score": 3843,
"rank": 3,
"additional_info": {
"username": "NoName",
"avatarImage": "https://www.example.com/avatars/unknown.png"
}
}
],
"grouped_by_teams": [
{
"member_id": "1234567",
"member_type": "user",
"score": 3843,
"rank": 3,
"additional_info": {
"username": "NoName",
"avatarImage": "https://www.example.com/avatars/unknown.png"
}
}
],
"num_teams": 20482,
"num_users": 137299
}
The LeaderboardRanking object
LeaderboardRanking
objects contain data for one row in the leaderboard table. As leaderboards are flexible data
structure they contain a member_id
which can be either a user or a team id and a member_type
that indicates what
it to expect in the member_id
.
Possible values for member_type
:
user
team
Parameters
member_id string
The id of the user - its the same user id you used to create the access token and the same user id you used to send the events
member_type string
Indicates what type this entry is, it’s either user or team
score integer
The score achieved as an integer value. If you want to store floats, for example laptimes you need to convert them into an int before (i.e. multiply by 100 to get hundreds of seconds and format back to float in UI)
rank integer
The position within the leaderboard
additional_info UserInfo
Can be any object that is attached to the user. You can set these values in the user service. For example you can provide a user name and an avatar image url.
{
"member_id": "1234567",
"member_type": "user",
"score": 3843,
"rank": 3,
"additional_info": {
"username": "NoName",
"avatarImage": "https://www.example.com/avatars/unknown.png"
}
}
The LeaderboardMemberRanking object
SCILL Leaderboards feature REST-APIs that only deliver the users position within the leaderboard. These routes return
this object, which is basically the same as the Leaderboard
object but just does have one LeaderboardRanking
object
instead of an array with all users.
Parameters
leaderboard_id string
The id of the leaderboard
name string
The name of the leaderboard
member LeaderboardRanking
The ranking for the user or team in the leaderboard
{
"leaderboard_id": "641184035742547979",
"name": "Hall of Fame",
"member": {
"member_id": "1234567",
"member_type": "user",
"score": 3843,
"rank": 3,
"additional_info": {
"username": "NoName",
"avatarImage": "https://www.example.com/avatars/unknown.png"
}
}
}
The UserInfo object
SCILL does not know anything about your users, as your are in charge of authentication. In the events, only user_id
is provided, which typically is just hash or numeric value like a primary key pointing to your own user database. In
leaderboards users must identify themselves by their names they have in the apps or games community. Therefore, we
provide REST-APIs to set user data that are then returned as part of the LeaderboardRanking
object.
Setting user info is provided in the AuthApi.
Parameters
username string
The user name of the user
avatarImage string
The name or URL of an avatar image for a user.
{
"username": "NoName",
"avatarImage": "https://www.example.com/avatars/unknown.png"
}
Retrieve Leaderboard
Provides the selected leaderboard V2 rankings for a specific leaderboard.
URL | /api/v2/leaderboards/{leaderboardId} |
Method | GET |
Authentication | Access Token |
Path Parameters
leaderboardId string REQUIRED
The id of the leaderboard
Query Parameters
startDate string OPTIONAL
The starting date for fetching results.
endDate string OPTIONAL
The ending date for fetching results.
aggregate string OPTIONAL
The aggregate function for the calculation of the results - can be BEST (returns a single score - either the lowest if ASC sorting is used, or the highest if DESC is used) or SUM (default value - increments (sums up) the scores).
currentPage number OPTIONAL
The page index starting at 1. The number of pageSize elements are returned for each page. Default value is 1
currentPosition number OPTIONAL
The starting leaderboard position from which the results should be loaded. The number of results is controlled via the pageSize variable. This parameter overrides the currentPage parameter.
pageSize number OPTIONAL
The number of elements per page. Default is 25.
language string OPTIONAL
Set the language. Content can be translated in the Admin Panel. Values can be international language codes like de, en, fr, it, …
Response
{
"leaderboard_id": "641184035742547979",
"leaderboard_name": "Hall of Fame",
"leaderboard_sort_order_ascending": true,
"leaderboard_results_by_member_type": {
"team": {
"count": 123,
"members": [
{
"member_id": "1234567",
"member_type": "user",
"score": 3843,
"rank": 3,
"metadata_results": [
{
"key": "required_time",
"ranked": false,
"score": 3843,
"rank": 3
},
],
"additional_info": {
"username": "NoName",
"avatarImage": "https://www.example.com/avatars/unknown.png"
}
},
]
},
"user": {
"count": 123,
"members": [
{
"member_id": "1234567",
"member_type": "user",
"score": 3843,
"rank": 3,
"metadata_results": [
{
"key": "required_time",
"ranked": false,
"score": 3843,
"rank": 3
}
],
"additional_info": {
"username": "NoName",
"avatarImage": "https://www.example.com/avatars/unknown.png"
}
}
]
}
}
}
Retrieve Leaderboards
Returns an array of LeaderboardV2Results items defined for the application.
URL | /api/v2/leaderboards |
Method | GET |
Authentication | Access Token |
Query Parameters
startDate string OPTIONAL
The starting date for fetching results.
endDate string OPTIONAL
The ending date for fetching results.
aggregate string OPTIONAL
The aggregate function for the calculation of the results - can be BEST (returns a single score - either the lowest if ASC sorting is used, or the highest if DESC is used) or SUM (default value - increments (sums up) the scores).
currentPage number OPTIONAL
The page index starting at 1. The number of pageSize elements are returned for each page. Default value is 1
currentPosition number OPTIONAL
The starting leaderboard position from which the results should be loaded. The number of results is controlled via the pageSize variable. This parameter overrides the currentPage parameter.
pageSize number OPTIONAL
The number of elements per page. Default is 25.
language string OPTIONAL
Set the language. Content can be translated in the Admin Panel. Values can be international language codes like de, en, fr, it, …
Response
[
{
"leaderboard_id": "641184035742547979",
"leaderboard_name": "Hall of Fame",
"leaderboard_sort_order_ascending": true,
"leaderboard_results_by_member_type": {
"team": {
"count": 123,
"members": [
{
"member_id": "1234567",
"member_type": "user",
"score": 3843,
"rank": 3,
"metadata_results": [
{
"key": "required_time",
"ranked": false,
"score": 3843,
"rank": 3
},
],
"additional_info": {
"username": "NoName",
"avatarImage": "https://www.example.com/avatars/unknown.png"
}
},
]
},
"user": {
"count": 123,
"members": [
{
"member_id": "1234567",
"member_type": "user",
"score": 3843,
"rank": 3,
"metadata_results": [
{
"key": "required_time",
"ranked": false,
"score": 3843,
"rank": 3
}
],
"additional_info": {
"username": "NoName",
"avatarImage": "https://www.example.com/avatars/unknown.png"
}
}
]
}
}
}
]
Retrieve user rankings across all leaderboards
Returns an array of LeaderboardV2MemberRanking items defined for all leaderboards in the application specified for the user. If the member is not in the leaderboard, the rank will be -1 in the LeaderboardRanking object.
URL | /api/v2/leaderboards-members/{memberType}/{memberId} |
Method | GET |
Authentication | Access Token |
Path Parameters
memberType string REQUIRED
The member type, can be user or team (right now) and sets which leaderboards should be selected.
memberId string REQUIRED
Either the user_id or team_id you used when sending the events. The memberType flag identifies which one is used.
Query Parameters
startDate string OPTIONAL
The starting date for fetching results.
endDate string OPTIONAL
The ending date for fetching results.
aggregate string OPTIONAL
The aggregate function for the calculation of the results - can be BEST (returns a single score - either the lowest if ASC sorting is used, or the highest if DESC is used) or SUM (default value - increments (sums up) the scores).
language string OPTIONAL
Set the language. Content can be translated in the Admin Panel. Values can be international language codes like de, en, fr, it, …
Response
[
{
"leaderboard_id": "641184035742547979",
"leaderboard_name": "Hall of Fame",
"leaderboard_sort_order_ascending": true,
"leaderboard_member": [
{
"member_id": "1234567",
"member_type": "user",
"score": 3843,
"rank": 3,
"metadata_results": [
{
"key": "required_time",
"ranked": false,
"score": 3843,
"rank": 3
}
],
"additional_info": {
"username": "NoName",
"avatarImage": "https://www.example.com/avatars/unknown.png"
}
}
]
}
]
Retrieve user ranking for a single leaderboard V2
Returns a LeaderboardV2MemberRanking item for the specified leaderboard. Use this route to get the position of a user of team in a specified leaderboard.
URL | /api/v2/leaderboards-members/{memberType}/{memberId}/{leaderboardId} |
Method | GET |
Authentication | Access Token |
Path Parameters
memberType string REQUIRED
The member type, can be user or team (right now) and sets which leaderboards should be selected.
memberId string REQUIRED
Either the user_id or team_id you used when sending the events. The memberType flag identifies which one is used.
leaderboardId string REQUIRED
The id of the leaderboard
Query Parameters
startDate string OPTIONAL
The starting date for fetching results.
endDate string OPTIONAL
The ending date for fetching results.
aggregate string OPTIONAL
The aggregate function for the calculation of the results - can be BEST (returns a single score - either the lowest if ASC sorting is used, or the highest if DESC is used) or SUM (default value - increments (sums up) the scores).
language string OPTIONAL
Set the language. Content can be translated in the Admin Panel. Values can be international language codes like de, en, fr, it, …
Response
{
"leaderboard_id": "641184035742547979",
"leaderboard_name": "Hall of Fame",
"leaderboard_sort_order_ascending": true,
"leaderboard_member": [
{
"member_id": "1234567",
"member_type": "user",
"score": 3843,
"rank": 3,
"metadata_results": [
{
"key": "required_time",
"ranked": false,
"score": 3843,
"rank": 3
}
],
"additional_info": {
"username": "NoName",
"avatarImage": "https://www.example.com/avatars/unknown.png"
}
}
]
}
Deletes all leaderboard V2 data, i.e. reset the leaderboard V2.
Deletes all leaderboard V2 data, i.e. reset the leaderboard V2.
URL | /api/v2/leaderboards-reset/{appId}/{leaderboardId} |
Method | DELETE |
Authentication | Access Token |
Path Parameters
appId string REQUIRED
The application ID
leaderboardId string REQUIRED
The leaderboard ID
Response
{
"status": 200,
"message": "OK",
"challenge": {
"challenge_id": "505538946732425217",
"challenge_name": "Survive 3 battles",
"challenge_description": "Get a great reward by managing this challenge. You can try as long as you like",
"challenge_duration_time": 500,
"live_date": "2020-10-12T00:00:00Z",
"challenge_goal": 5,
"user_challenge_current_score": 0,
"challenge_icon": "black-arrow",
"challenge_icon_hd": "black-arrow-hd",
"challenge_price": 0,
"challenge_reward": "weapon_a",
"challenge_reward_type": "item",
"challenge_goal_condition": 0,
"challenge_xp": 0,
"repeatable": false,
"type": "unlock",
"challenge_auto_activated": true,
"is_claimed": false,
"user_challenge_unlocked_at": null,
"user_challenge_activated_at": null,
"user_challenge_is_claimed": false,
"user_challenge_status": 0
}
}
Webhooks
In the Admin Panel, you can setup a Webhooks that is called by our backend whenever the leaderboard is updated. This way, you can quickly add business logic on your side.
The SCILL backend will request your Webhook whenever a leaderboard changes
- Webhook is called via
POST
- Your Webhook URL must be served via HTTPS and needs to have a valid certificate
- Data is sent as
application/json
- Secret key is added to your URL via GET parameter
secret_key
- Your Webhook must return a response with HTTP status code 200.
- If your Webhook does not return a response or with an error code (4xx, 5xx) the SCILL backend will retry sending the Webhook.
Please note: In the Admin Panel you set up a shared secret that is sent with every webhook request as GET-Parameter
secret_key
.
- Check the shared secret in your web hook and return a 403 error if its not ok, otherwise return a response with HTTP code 200.
- Keep this secret secure. It allows everyone to trigger your webhooks without permission
leaderboard-updated
Use this Webhook if you want your backend to be triggered whenever a leaderboard is updated/changed.