The Game Mechanics (GM) Leaderboard add-on displays the top ranking users in a specific challenge.
The leaderboard will only display users who have a name, email or provider.
Each site may have one or more challenges, and each challenge has defined levels. Each level has a badge associated with it, and a level title. A user may achieve a level in a certain challenge by performing actions and accumulating points for these actions. The user's points can then be used to calculate the user's rank compared to the rest of the challenge's users. To learn more about Gigya's Game Mechanics, refer to our Game Mechanics Guide.
The Leaderboard add-on displays a predefined number of users, each with their photo, name, and rank. Users with the same number of points are ranked the same.
The top three users also have a medal icon:
In a logged-in state, the Leaderboard display is made up of three kinds of users:
- The current logged-in user, regardless of his rank. If his rank is insufficient to make the leaderboard, he replaces the last user to make the leaderboard.
- Up to a specified number of friends of the current user, regardless of their rank.
- The rest are the top ranking users for the specified challenge who have public profiles.
In a logged-out state the leaderboard add-on just displays the highest ranking users.
In addition to the initial add-on display, you can click on any of the users to open an info popup:
The info popup displays the user's:
- Points - either the total points, or the points accumulated over the past seven days for the specific challenge (as defined in gm.showLeaderboardUI)
- The specified challenge's level badge and title
- Achievements in other challenges, represented by the achieved level's badge and title
Quick Start Implementation
Adding the Leaderboard add-on is simple, and involves only adding a few lines of code:
- Step 1: Define the section (div) where the Leaderboard add-on should be embedded.
- Step 2: Define the Leaderboard add-on's parameters.
- Step 3: Call the gm.showLeaderboardUI API to activate the Leaderboard add-on.
Add the following code snip to the of your page to activate the Leaderboard add-on:
Step 1: Define the Leaderboard add-on's div
Step 2: Define the Leaderboard add-on parameters
The Leaderboard add-on has one required parameter:
- containerID - the identifier of the DIV element, where the Leaderboard add-on should be embedded.
In addition there are a few optional parameters. Please refer to the method's parameters table for the entire list of optional parameters.
Step 3: Invoke the Leaderboard add-on
Call the gm.showLeaderboardUI API method:
Leaderboard ties are resolved according to who achieved the points first; if player A and player B both have 60 points, and player A reached 60 points before player B, then player A will be before player B on the leaderboard.
A Working Example
In the GM add-ons demo you will find a complete working example of a web-page that uses all GM add-ons, including the Leaderboard add-on. You may view the code, run it and view the outcome.