The Game Mechanics (GM) Achievement add-on 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 add-on 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:
When the users hover with their mouse over a badge, a tooltip popup window opens:
When showing achievements for a points based challenge, 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
For an action/mixed based challenge, the footer will display a link to the action URL (see more details below).
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 Based Levels
When defining a new action or mixed based level in a challenge, you can add an Action URL to which a user can be directed to invoke certain actions. When showing achievements for an action/mixed based challenge, the footer of the tooltip does not display the number of points needed to unlock the next level. Instead, the footer presents a title and grayed out badge of the next level. By clicking either of them, the user will be redirected to the given URL. For more information on the Action URL, refer to the action URL definition on the Game Mechanics Settings section.
Logged Out State
For users who are not logged in, the add-on displays all first level badges as grayed out:
Quick Start Implementation
Adding the Achievements add-on is simple, and involves only adding a few lines of code:
- Step 1: Define the section (div) where the Achievement add-on should be embedded
- Step 2: Define the Achievements add-on's parameters.
- Step 3: Call the gm.showAchievementsUI API to activate the Achievements add-on.
Add the following code snip to the of your page to activate the Achievements add-on:
Step 1: Define the Achievement add-on's div
Step 2: Define the Achievements add-on parameters
The Achievement add-on has one required parameter:
- containerID - the identifier of the DIV element, where the Achievements 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 Achievements add-on
Call the gm.showAchievementsUI API method:
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 Achievements add-on. 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 add-on, 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:
The default challenge, whose first level badge is 'Beginner', is now included: