Table of contents
Introduction
The Game Mechanics (GM) Achievement plugin enables users to view their currently achieved level, badge image and title per challenge.
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. To learn more about Gigya's Game Mechanics, refer to our Game Mechanics Guide.
The Achievements plugin is built of one or more badges with their titles, arranged horizontally. If the user has yet to unlock the first level of a challenge, the first level badge is displayed as grayed out:
Tooltip Popup
When the users hover with their mouse over a badge, a tooltip popup window opens:
The tooltip popup displays:
- The title of the challenge level, i.e. Reader
- The name of the challenge, i.e. Book Worm
- The description of the challenge as defined in the Challenge Settings page at Gigya's site
- The number of points needed to achieve (unlock) the next level of the challenge
- The title of the next level to be unlocked in the challenge
- The grayed out badge of the next level
When the UID parameter of gm.showAchievementsUI is defined and it's not the UID of the current logged-in user, the tooltip displays only the achievement description and title, without the next level details and needed actions/points.
Action URL
When defining a new level in a challenge, you can add an Action URL to which a user can be directed. The tooltip popup displays the title and grayed out badge of the next level, and if the level has an Action URL defined, the badge and title will be clickable. By clicking either of them, the user will be redirected to the given URL. For more information on the Action URL, refer to the Game Mechanics Settings section.
Logged Out State
For users who are not logged in, the plugin displays all first level badges as grayed out:
Quick Start Implementation
Implementation Overview
Adding the Achievements plugin is simple, and involves only adding a few lines of code:
- Step 1: Define the section (div) where the Achievement plugin should be embedded
- Step 2: Define the Achievements plugin's parameters.
- Step 3: Call the gm.showAchievementsUI API to activate the Achievements plugin.
Code Example
Add the following code snip to the <body> of your page to activate the Achievements plugin:
<div id="divAchievements"></div>
<script>
var achievementsParams = {
containerID: 'divAchievements'
}
gigya.gm.showAchievementsUI(achievementsParams);
</script>
Code Explanation
Step 1: Define the Achievement plugin's div
<div id="divAchievements"></div>
Step 2: Define the Achievements plugin parameters
var achievementsParams = {
containerID: 'divAchievements',
}
The Achievement plugin has one required parameter:
- containerID - the identifier of the DIV element, where the Achievements 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 Achievements plugin
Call the gm.showAchievementsUI API method:
gigya.gm.showAchievementsUI(achievementsParams);
Like every Gigya API method, the gm.showAchievementsUI 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 Achievements plugin. You may view the code, run it and view the outcome.
Including the Default Challenge
By default, the default challenge is not displayed in this plugin, but it can be easily included. The default value of the excludeChallenges parameter in gm.showAchievementsUI is '_default ', but by using an empty string instead, the default challenge will not be excluded:
var achievementsParams = {
containerID: 'divAchievements',
excludeChallenges:''
}
The default challenge, whose first level badge is 'Beginner', is now included:
Comments