Admin Panel

Leaderboards

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.

Base URL

https://ls.scill.4players.io

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

leaderboard_name string

The name of the leaderboard

leaderboard_sort_order_ascending boolean

Determines the results sort order. If true, the order is ascending, otherwise, it’s descending.

leaderboard_results_by_member_type object

An object containing two keys - “team” and “user”, both of which are an object containing array of LeaderboardRanking items for teams or individual users, respectively.

Leaderboard Object
{
  "leaderboard_id": "641184035742547979",
  "leaderboard_name": "Hall of Fame",
  "leaderboard_sort_order_ascending": false,
  "leaderboard_results_by_member_type": {
    "team": {
      "type": "team",
      "count": 0,
      "members": [
        {
          "member_id": "1234567",
          "member_type": "user",
          "score": 3843,
          "rank": 3,
          "metadata_results": [
            {
              "key": "required_time",
              "ranked": true,
              "score": 35,
              "rank": 2
            }
          ],
          "additional_info": {
            "username": "NoName",
            "avatarImage": "https://www.example.com/avatars/unknown.png"
          }
        }
      ]
    },
    "user": {
      "type": "user",
      "count": 0,
      "members": [
        {
          "member_id": "1234567",
          "member_type": "user",
          "score": 3843,
          "rank": 3,
          "metadata_results": [
            {
              "key": "required_time",
              "ranked": true,
              "score": 35,
              "rank": 2
            }
          ],
          "additional_info": {
            "username": "NoName",
            "avatarImage": "https://www.example.com/avatars/unknown.png"
          }
        }
      ]
    }
  }
}

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

metadata_results array

An array of objects containing secondary ranking parameters, used in cases of ties, i.e. same amount of points on the primary ranking event type. The key property is the tracked property, and the ranked boolean states if the user has a rank with that property. If so, a rank and score property will be provided as well.

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.

LeaderboardRanking Object
{
  "member_id": "1234567",
  "member_type": "user",
  "score": 3843,
  "rank": 3,
  "metadata_results": [
    {
      "key": "required_time",
      "ranked": true,
      "score": 35,
      "rank": 2
    }
  ],
  "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

leaderboard_name string

The name of the leaderboard

leaderboard_sort_order_ascending boolean

Determines the sort order. If true, the order is ascending, otherwise, it’s descending.

leaderboard_member LeaderboardRanking

The ranking for the user or team in the leaderboard

Leaderboard single member ranking object
{
  "leaderboard_id": "641184035742547979",
  "leaderboard_name": "Hall of Fame",
  "leaderboard_sort_order_ascending": false,
  "leaderboard_member":   {
    "member_id": "1234567",
    "member_type": "user",
    "score": 3843,
    "rank": 3,
    "metadata_results": [
      {
        "key": "required_time",
        "ranked": true,
        "score": 35,
        "rank": 2
      }
    ],
    "additional_info":     {
      "username": "NoName",
      "avatarImage": "https://www.example.com/avatars/unknown.png"
    }
  }
}

The UserInfo object

SCILL does not know anything about your users, as you 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.

BattlePassLevelChallenge object
{
  "username": "NoName",
  "avatarImage": "https://www.example.com/avatars/unknown.png"
}

Retrieve Leaderboard

Provides the current leaderboard rankings for a specific leaderboard.

URL /api/v2/leaderboards/{leaderboardId}?startDate={startDate}&endDate={endDate}&aggregate={aggregate}&currentPosition={currentPosition}
Method GET
Authentication User-specific bearer authentication token
Path Parameters

leaderboardId string REQUIRED

The id of the leaderboard

Query Parameters

startDate string OPTIONAL

The starting date limit (included) in RFC3339 format for the calculation of the results, counted in the previously set timezone, e.g. 2022-10-30

endDate string OPTIONAL

The ending date limit (included) in RFC3339 format for the calculation of the results, counted in the previously set timezone, e.g. 2022-10-30

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 shown 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, …

Example
No example code available for JavaScript
No example code available for C#
Response
Leaderboard
{
  "leaderboard_id": "641184035742547979",
  "leaderboard_name": "Hall of Fame",
  "leaderboard_sort_order_ascending": false,
  "leaderboard_results_by_member_type": {
    "team": {
      "type": "team",
      "count": 0,
      "members": [
        {
          "member_id": "1234567",
          "member_type": "user",
          "score": 3843,
          "rank": 3,
          "metadata_results": [
            {
              "key": "required_time",
              "ranked": true,
              "score": 35,
              "rank": 2
            }
          ],
          "additional_info": {
            "username": "NoName",
            "avatarImage": "https://www.example.com/avatars/unknown.png"
          }
        }
      ]
    },
    "user": {
      "type": "user",
      "count": 0,
      "members": [
        {
          "member_id": "1234567",
          "member_type": "user",
          "score": 3843,
          "rank": 3,
          "metadata_results": [
            {
              "key": "required_time",
              "ranked": true,
              "score": 45,
              "rank": 3
            }
          ],
          "additional_info": {
            "username": "NoName",
            "avatarImage": "https://www.example.com/avatars/unknown.png"
          }
        }
      ]
    }
  }
}
  

Retrieve Leaderboards

Returns an array of Leaderboard items defined for the application.

URL /api/v2/leaderboards?startDate={startDate}&endDate={endDate}&aggregate={aggregate}&currentPosition={currentPosition}
Method GET
Authentication User-specific bearer authentication token
Query Parameters

startDate string OPTIONAL

The starting date limit (included) in RFC3339 format for the calculation of the results, counted in the previously set timezone, e.g. 2022-10-30

endDate string OPTIONAL

The ending date limit (included) in RFC3339 format for the calculation of the results, counted in the previously set timezone, e.g. 2022-10-30

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, …

Example
No example code available for JavaScript
No example code available for C#
Response
Leaderboard
[
  {
    "leaderboard_id": "641184035742547979",
    "leaderboard_name": "Hall of Fame",
    "leaderboard_sort_order_ascending": false,
    "leaderboard_results_by_member_type": {
      "team": {
        "type": "team",
        "count": 0,
        "members": [
          {
            "member_id": "1234567",
            "member_type": "user",
            "score": 3843,
            "rank": 3,
            "metadata_results": [
              {
                "key": "required_time",
                "ranked": true,
                "score": 25,
                "rank": 2
              }
            ],
            "additional_info": {
              "username": "NoName",
              "avatarImage": "https://www.example.com/avatars/unknown.png"
            }
          }
        ]
      },
      "user": {
        "type": "user",
        "count": 0,
        "members": [
          {
            "member_id": "1234567",
            "member_type": "user",
            "score": 3843,
            "rank": 3,
            "metadata_results": [
              {
                "key": "required_time",
                "ranked": true,
                "score": 45,
                "rank": 3
              }
            ],
            "additional_info": {
              "username": "NoName",
              "avatarImage": "https://www.example.com/avatars/unknown.png"
            }
          }
        ]
      }
    }
  }
]

Retrieve User Rankings

Returns an array of LeaderboardRanking 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}?startDate={startDate}&endDate={endDate}&aggregate={aggregate}
Method GET
Authentication User-specific bearer authentication 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 limit (included) in RFC3339 format for the calculation of the results, counted in the previously set timezone, e.g. 2022-10-30

endDate string OPTIONAL

The ending date limit (included) in RFC3339 format for the calculation of the results, counted in the previously set timezone, e.g. 2022-10-30

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, …

Example
No example code available for JavaScript
No example code available for C#
Response
LeaderboardMemberRanking
[
  {
    "leaderboard_id": "641184035742547979",
    "leaderboard_name": "Hall of Fame",
    "leaderboard_sort_order_ascending": false,
    "leaderboard_member":     {
      "member_id": "1234567",
      "member_type": "user",
      "score": 3843,
      "rank": 3,
      "metadata_results": [
        {
          "key": "required_time",
          "ranked": true,
          "score": 25,
          "rank": 2
        }
      ],
      "additional_info":       {
        "username": "NoName",
        "avatarImage": "https://www.example.com/avatars/unknown.png"
      }
    }
  }
]

Retrieve User Ranking

Returns a LeaderboardMemberRanking 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}?startDate={startDate}&endDate={endDate}&aggregate={aggregate}
Method GET
Authentication User-specific bearer authentication 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 for which you are querying the results

Query Parameters

startDate string OPTIONAL

The starting date limit (included) in RFC3339 format for the calculation of the results, counted in the previously set timezone, e.g. 2022-10-30

endDate string OPTIONAL

The ending date limit (included) in RFC3339 format for the calculation of the results, counted in the previously set timezone, e.g. 2022-10-30

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, …

Example
No example code available for JavaScript
No example code available for C#
Response
LeaderboardMemberRanking
  {
    "leaderboard_id": "641184035742547979",
    "leaderboard_name": "Hall of Fame",
    "leaderboard_member":     {
      "member_id": "1234567",
      "member_type": "user",
      "score": 3843,
      "rank": 3,
      "metadata_results": [
        {
          "key": "required_time",
          "ranked": true,
          "score": 25,
          "rank": 2
        }
      ],
      "additional_info":       {
        "username": "NoName",
        "avatarImage": "https://www.example.com/avatars/unknown.png"
      }
    }
  }

Reset leaderboard data

Calling this route will reset (delete) all the leaderboard’s ranking data

URL /api/v2/leaderboards-reset/{appId}/{leaderboardId}
Method DELETE
Authentication Your application API key
Path Parameters

appId string REQUIRED

The id of the app tha the leaderboard belongs to

leaderboardId string REQUIRED

The id of the leaderboard

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

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.