Challenge leaderboards

Opigno Enterprise API provides queries to build different types of the leaderboards. All these queries return a list of ChallengeParticipant objects:

Parameter	Type	Description
`completedOn`	`Int`	Required. A timestamp when the attempt has been completed. Will be empty if the attempt is still in progress.
`id`	`ID`	Required. ID of the related attempt.
`isAnonymized`	`Boolean`	Required. A marker that shows that the challenge results returned anonymized.
`name`	`String`	Required. A label of the related user context. Only first letters of name and surname will be returned if anonymization is enabled in the challenge.
`rank`	`Int`	Required. The attempt rank in the related challenge.
`score`	`Float`	Required. The total number of points that is earned by the related API user for the challenge.
`timeSpent`	`Int`	Required. The time (in seconds) that the user spent answering the related challenge questions.
`uuid`	`ID`	Required. UUID of the related user context.

Important: results for these queries can be retrieved only if the ranking and leaderboard displaying is enabled for the challenge in the backoffice.

Classic leaderboard

Use the getChallengeParticipants query to get the full list of challenge participants or users with the same specific rank. Results will be returned with the pagination and possibility to change the order and sorting key (default sorting is by the rank, ascending). The following arguments can be used in the query:

Argument	Type	Description	Default
`after`	`Cursor`	Returns results that come after the specified cursor. Should be used together with `first` parameter. Cannot be used if `before` is set.	—
`before`	`Cursor`	Returns results that come before the specified cursor. Should be used together with `last` parameter. Cannot be used if `after` is set.	—
`challengeId`	`ID`	ID of the challenge to retrieve the participants.	—
`first`	`Int`	Returns up to the first N elements from the list. Required if `after` parameter is set. Cannot be used together with `last`.	—
`last`	`Int`	Returns up to the first N elements from the list. Required if `before` parameter is set. Cannot be used together with `first`.	—
`rank`	`Int`	Optional filter by the rank. If the ranking displaying is disabled for the challenge, this filter will be omitted and all results will be returned (taking into account all other filters).	—
`reverse`	`Boolean`	Allows to reverse the order of the underlying list (default order is ascending).	`false`
`sortKey`	`ChallengeParticipantsSortKey`	Allows to change the results sorting. Available options: `RANK` (default), `NAME` (sorting by the user context name; it makes sense to use it only if the real user name is sent to the API during the user context synchronization), `COMPLETED_ON` (sorting by the challenge completion date).	`RANK`

Here is an example of the query execution:

query getChallengeParticipants {
  getChallengeParticipants(challengeId: 1, first: 4, rank: 3, sortKey: "NAME") {
    edges {
      node {
        name
        score
        rank
        timeSpent
      }
    }
    totalItems
  }
}

{
  "data": {
    "getChallengeParticipants": {
      "edges": {
        [
          "node": {
            "name": "David Hawk",
            "score": 80,
            "rank": 3,
            "timeSpent": 95
          }
        ],
        [
          "node": {
            "name": "John Doe",
            "score": 80,
            "rank": 3,
            "timeSpent": 93
          }
        ]
      },
      "totalItems": 2
    }
  }
}

Relative leaderboard

The relative leaderboard shows competitors closest in ranking to the current API user. The logic of displaying is the following:

itemsNumberBefore of users with the higher score than the current API user has earned;
the current API user;
itemsNumberAfter of users with the lower than or the same score as the current API user has earned. Results will be returned without pagination and possibility to change the order.

Parameters itemsNumberBefore and itemsNumberAfter are limited to 10. If the value is greater than 10, it will be automatically reduced.

To retrieve the data for a relative leaderboard, execute the getChallengeRelativeLeaderboard query:

query getChallengeRelativeLeaderboard {
  getChallengeRelativeLeaderboard(challengeId: 1, itemsNumberBefore: 2, itemsNumberAfter: 1) {
    name
    score
    rank
    timeSpent
  }
}

{
  "data": {
    "getChallengeRelativeLeaderboard": {
      {
        "name": "Malcolm Raynolds",
        "score": 100,
        "rank": 1,
        "timeSpent": 77
      },
      {
        "name": "Jane Tailor",
        "score": 90,
        "rank": 2,
        "timeSpent": 75
      },
      {
        "name": "John Doe",
        "score": 80,
        "rank": 3,
        "timeSpent": 93
      },
      {
        "name": "David Hawk",
        "score": 80,
        "rank": 3,
        "timeSpent": 95
      }
    }
  }
}

The getChallengeParticipants query supports the same advanced features as other catalog queries:

Pagination

Learn how to efficiently navigate through large sets of items using cursor-based pagination.

Authentication

Understand the authentication requirements and how to properly authenticate your requests.

Getting started

Integration & Concepts

Use cases

Hierarchy Management

Zapier Integration

Mobile application

Challenge leaderboards

Classic leaderboard

Relative leaderboard

Pagination

Authentication

​Classic leaderboard

​Relative leaderboard

​Related Features

Pagination

Authentication

Classic leaderboard

Relative leaderboard

Related Features