The User Status Loyalty add-on enables users to view their current status in a specific challenge and control their privacy settings.
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 User Status add-on displays information regarding the status of the user in the current challenge, such as the level the user is currently on, and what he has accumulated so far.
The User Status Layout
The user status add-on displays the user's photo, name, and a Settings button.
In addition the add-on shows, for the specified challenge, the badge and title of the achieved level and, depending on the level type, the status of the user in the challenge. This includes:
- For a point based level - Total accumulated points.
- For levels with an actions threshold (action based, or mixed levels), the add-on will display the progress of the user in terms of percentage of actions completed. For example, if there are three actions to complete a level and the user has performed one of these actions, the progress bar will show 33%.
- The default setting is to show both total points and progress. This setting can be overridden by adding the "hidePoints" and the "hideActions" attributes to the object parameter in the gm.showUserStatusUI method parameters object.
In addition to the initial add-on display, there are also three clickable buttons in the add-on, each opens a popup:
- Settings - opens the Privacy Settings popup
- Points - opens the My Points popup
- Badge icon (image & title) - opens the level achievement popup
Privacy Settings Popup
Open the Privacy Settings popup by pressing Settings:
The privacy settings allows the user to define:
- Whether the a notification is displayed on-page when an achievement is reached (enabled by default)
- Whether to show the user's profile and rankings to all users (enabled by default)
- Whether to automatically share the user's achievements (disabled by default)
If the user decides not to show his profile and rankings to other users, it may take up to an hour until the new privacy settings are applied.
My Points Popup
Open the My Points popup by pressing the points:
The My Points popup displays the user's points for the specified challenge:
- Points accumulated over the last seven days
- Overall accumulated points
Level Achievement Popup
Open the level achievement popup by pressing the badge image or title:
The popup displays:
- The title of the challenge level
- The name of the challenge
- 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 a grayed out badge of the next level
- A Share button
The Share Button
Pressing the Share button in the level achievement popup opens the Share add-on with the challenge information:
The Share add-on allows the users to publish their achievements to various social networks. Learn about the Share add-on here.
When defining a new level in a challenge, you can add an Action URL to which a user can be directed. The level achievement 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 are clickable. By clicking either of them, the user is redirected to the given URL. For more information on the Action URL, refer to the Adding a New Level section of the Game Mechanics Guide
Quick Start Implementation
Adding the User Status add-on is simple, and involves only adding a few lines of code:
- Step 1: Define the section (div) where the User Status add-on should be embedded
- Step 2: Define the User Status add-on's parameters.
- Step 3: Call the gm.showUserStatusUI API to activate the User Status add-on.
Add the following code snip to the of your page to activate the User Status add-on:
Step 1: Define the User Status add-on's div
Step 2: Define the User Status add-on parameters
The User Status add-on has one required parameter:
- containerID - the identifier of the DIV element, where the User Status add-on should be embedded.
There are additional optional parameters. Please refer to the method's parameters table for the entire list of optional parameters.
Step 3: Invoke the User Status add-on
Call the gm.showUserStatusUI 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 User Status add-on. You may view the code, run it and view the outcome.
When the user is logged out, by default the add-on is not displayed. If you want the User Status add-on to appear when the user logs in, register an event handler to the global onLogin event.
Registering a handler for a global event is done using the socialize.addEventHandlers API method. For example:
Calling the addEventHandler method should be done on page load (before the add-ons are loaded). The onLoginHandler method in the example, handles the onLogin event. You can now call the gm.showUserStatusUI API method from within the onLoginHandler method. To learn more about how to handle events generated by Gigya, please refer to Events page.
Customizing the User Action
The userAction object to be used for sharing the user's achievement, and it is comprised of several optional elements, such as title, description, etc. The newsfeed that is published to the social networks is constructed from the fields of this object.
If a UserAction object is not defined, the add-on uses a default userAction object, the content of which is suited to sharing the user's achievement. You can customize the user action by constructing a new UserAction object, filling it with data, and adding it to the add-on's parameters.
Construct a new UserAction object using the UserAction object constructor:
Change the default user action, by using the various UserAction member methods to set the object's properties. For example:
Add the userAction object to the add-on's parameters:
Pressing the Share button in the level achievement popup will now open the Share add-on with the new user action properties:
You can refer to the Advanced Sharing guide to learn more about the UserAction object and how to implement the full richness of newsfeed reports, including adding various media items (Images/ a Flash file/ Mp3 file/ a Video).