Table of contents
Introduction
The Game Mechanics (GM) Leaderboard plugin displays the top ranking users in a specific challenge. Note: 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 plugin displays a predefined number of users, each with their photo, name, and rank. 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 plugin just displays the highest ranking users.
In addition to the initial plugin display, you can click on any of the users to open an info popup:
The info popup displays the user's:
- Name
- Photo
- 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
Implementation Overview
Adding the Leaderboard plugin is simple, and involves only adding a few lines of code:
- Step 1: Define the section (div) where the Leaderboard plugin should be embedded
- Step 2: Define the Leaderboard plugin's parameters.
- Step 3: Call the gm.showLeaderboardUI API to activate the Leaderboard plugin.
Code Example
Add the following code snip to the <body> of your page to activate the Leaderboard plugin:
<div id="divLeaderboard"></div>
<script>
var leaderboardParams = {
containerID: 'divLeaderboard'
}
gigya.gm.showLeaderboardUI(leaderboardParams);
</script>
Code Explanation
Step 1: Define the Leaderboard plugin's div
<div id="divLeaderboard"></div>
Step 2: Define the Leaderboard plugin parameters
var leaderboardParams = {
containerID: 'divLeaderboard'
} The Leaderboard plugin has one required parameter:
- containerID - the identifier of the DIV element, where the Leaderboard plugin 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 plugin
Call the gm.showLeaderboardUI API method:
gigya.gm.showLeaderboardUI(leaderboardParams);
Like every Gigya API method, the gm.showLeaderboardUI API method receives one parameter - parameters object, which is the object we have defined in Step 2 (learn more about Gigya's basics here).
A Working Example
In the GM Plugins demo you will find a complete working example of a web-page that uses all GM plugins, including the Leaderboard plugin. You may view the code, run it and view the outcome.
Comments