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.

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

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 selected leaderboard V2 rankings for a specific leaderboard.

URL/api/v2/leaderboards/{leaderboardId}
MethodGET
AuthenticationAccess 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
LeaderboardV2Results
  {
    "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
MethodGET
AuthenticationAccess 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
LeaderboardV2Results
[
  {
    "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}
MethodGET
AuthenticationAccess 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
LeaderboardV2MemberRanking
[
  {
    "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}
MethodGET
AuthenticationAccess 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
LeaderboardV2MemberRanking
  {
    "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}
MethodDELETE
AuthenticationAccess Token
Path Parameters

appId string REQUIRED

The application ID

leaderboardId string REQUIRED

The leaderboard ID

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.