Leaderboards V1

Important Notice

There’s a newer version of this API available. Please click here for version 2 of the Leaderboards API.

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 Object
{
  "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.

LeaderboardRanking Object
{
  "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

BattlePassLevelChallenge object
{
  "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.

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/v1/leaderboards/{leaderboardId}
MethodGET
Authentication
Path Parameters

leaderboardId string REQUIRED

The id of the leaderboard

Query Parameters

currentPage number OPTIONAL

The page index starting at 1. The number of pageSize elements are returned for each page. Default value is 1

pageSize number OPTIONAL

The number of elements per page. Default is 25.

startDate string OPTIONAL

The starting date for fetching results.

endDate string OPTIONAL

The ending date for fetching results.

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
  {
    "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
  }

Retrieve Leaderboards

Returns an array of Leaderboard items defined for the application.

URL/api/v1/leaderboards
MethodGET
Authentication
Query Parameters

currentPage number OPTIONAL

The page index starting at 1. The number of pageSize elements are returned for each page. Default value is 1

pageSize number OPTIONAL

The number of elements per page. Default is 25.

startDate string OPTIONAL

The starting date for fetching results.

endDate string OPTIONAL

The ending date for fetching results.

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
[
  {
    "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
  }
]

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/v1/leaderboards-members/{memberType}/{memberId}
MethodGET
Authentication
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.

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
LeaderboardMemberRanking
[
  {
    "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"
      }
    }
  }
]

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/v1/leaderboards-members/{memberType}/{memberId}/{leaderboardId}
MethodGET
Authentication
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.

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
LeaderboardMemberRanking
  {
    "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"
      }
    }
  }

Delete all leaderboard data, i.e. reset the leaderboard for the specified member.

Delete all leaderboard data, i.e. reset the leaderboard for the specified member.

URL/api/v1/reset-leaderboard/{memberType}/{appId}/{memberId}
MethodDELETE
Authentication
Path Parameters

memberType string REQUIRED

The member type, can be user or team (right now) and sets which leaderboards should be selected.

appId string REQUIRED

The application ID

memberId string REQUIRED

Either the user_id or team_id you used when sending the events. The memberType flag identifies which one is used.

Response
ActionResponse
  {
    "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

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.