Introduction

New Gamification Service

The former version of Leaderboards is no longer maintained and supported and has been replaced by a new Gamification service. Please check back for further documentation or contact support.

What to expect from the new Gamification Service

The new Monterosa Gamification Service provides:

  • point scoring with anti-hack mechanisms

  • points at round level

  • leaderboard functionality

M/IC Leaderboard

Please read Developing with Leaderboards guide first.

We recommend using the Leaderboard JavaScript lib wherever possible, but the Leaderboard service can also be accessed directly via the REST API.

Endpoints

Read and write endpoints

There are two types of endpoints: read and write. Read endpoint must be used for all read-only GET requests. Write endpoint must be used for modifying POST, PUT, PATCH and DELETE requests.

Base URL

There are two types of leaderboards: project-level and event-level.

Base URL for project-level leaderboard endpoints:

{host}/api/projects/{project_id}/leaderboards/{leaderboard_id}

Base URL for event-level leaderboard endpoints:

{host}/api/projects/{project_id}/events/{event_id}/leaderboards/{leaderboard_id}

URL parts:

  • host (string) - read or write leaderboard service endpoint, depending on the request type.

  • project_id (string) - LViS Project UUID

  • leaderboard_id (string) - Leaderboard ID. It is assigned by the app and is also used as a leaderboard name within LViS Studio.

  • event_id (string) - LViS Event UUID

Request Format

  • Payload format: JSON

  • Content type: application/json

User Identification

Each record has a mandatory private ID and an optional public ID. Both IDs must be unique - private within all private IDs, public within all public IDs within the leaderboard.

The private ID is used to access, including write access, all fields of the leaderboard record. The public ID is used by other users to access public fields of other user's leaderboard record. For example if a Facebook ID is used as a public ID then the app can display rank and other data of user's Facebook friends, because it can access their Facebook IDs and fetch their public leaderboard data by these IDs.

The app can can use LViS user ID as a private ID or generate a UUID to be used as a private ID. It can be recorded in client cookie, local storage or in a user data within the registration/sign-in system, etc.

Do not use publicly available IDs, such as user Facebook ID for private IDs as then anyone can get write access to user's record.

Do not use the same value for private and public ID for the same reason.

Leaderboard Record Fields

Please read Create/Update Record API request description to learn about record fields and restrictions.

Error response

In case of an error a non 2XX response code is returned along with a body of the following format:

{
"error": "error text"
}