Loyalty

Skip to end of metadata
Go to start of metadata

 

 

Gigya's Loyalty add-ons (formerly Game Mechanics) are pre-built Web GUI elements that can be used to display loyalty information, such as the user's current points, the current achieved level, the number of points needed to achieve the next level, the highest ranking users, etc. 

For more details, please refer to Gigya's documentation on Loyalty.

Note: If you plan on integrating the Loyalty platform, we highly recommend reading the Gamification Guide. Loyalty is a premium Gigya platform that requires separate activation. If it is not yet a part of your existing site package, please contact Gigya Support via the Support link in the top menu of your Console Dashboard or email support@gigya.com.

Available Loyalty Add-Ons and Javascript API

Gigya's GM add-ons are accessed through the Javascript API on the client side.

 

There are five GM plugins:

PluginCorresponding JavaScript API callDescription

Achievements

gm.showAchievementsUI

Enables users to view their currently achieved level, badge image and title per challenge.

Challenge Status

gm.showChallengeStatusUI  

Enables users to view all the badges, both locked and unlocked, of a specified challenge.

User Status

gm.showUserStatusUI  

Enables users to view their current status in a specific challenge, and control their privacy settings.

Leaderboard

gm.showLeaderboardUI  

Displays the top ranking users in a specific challenge.

Notificationsgm.showNotificationsNotifies the users of their latest achievements, and allows them to share this to their social networks.

Please refer to the JS Game Mechanics API Reference for the full list of methods and parameters.

 

 

A Working Example

In the Loyalty add-ons demo you will find a complete working example of a web-page that uses all Loyalty add-ons. You may view the code, run it and view the outcome.

UI Customization

Gigya add-ons are highly customizable. You can customize each add-on through the use of:

  • The API method parameters
  • HTML Elements Style (CSS) Classes
  • Templates

Changing UI using Method Parameters

The following API methods can be used to customize the add-ons:

For example, you can change the size of the Leaderboard add-on by giving the totalCount parameter a value higher than the default 12.

HTML Elements Style (CSS) Classes

Any elements on the add-on that has an ID can be overridden with supported style attributes.

All CSS rules are comprised of a selector, which is the HTML element you want to style, and one or more declarations, which are the style changes to apply. 

You may use Firebug to identify an HTML element on the add-on and assign a new style to it. Please make sure to use the add-on's container <div> ID when assigning style, so it will not affect other elements on the page.

 

For example:

<style>
/* Change leaderboard font */
#divLeaderboard {font-family:Arial;} 

/* Change achievments badge size */
#achievementsDiv  .gig-achievements-badge {width: 100px; height: 100px;}
div.gig-achievements-badge-container {max-width: 120px; height: 130px;}
</style>

In this example the Leaderboard's add-on's font has been changed to Arial and the Achievements badge size has been increased to 100x100. 

The GM add-ons are embedded in the sections (divs) that you name, e.g. containerID= 'divLeaderboard'. Any element that is not in the container has a different ID. The add-on popups have static identifiers, that together with the add-on's containerID comprise the HTML element to which a new style is assigned:

  • The Achievements' popup identifier: <ID_container>_levelInfo
  • The Challenge Status' popup identifier: <ID_container> _levelInfo
  • The Leaderboard's popup identifier: <ID_container>_details
  • The UserStatus' points popup identifier: <ID_container>_points
  • The UserStatus' info popup identifier: <ID_container>_levelInfo

CSS Example

The following example applies style changes to each of theadd-ons. Add the following lines to the section of your code: 

<style>
	#divUserStatus_points .gig-GMBalloon-frame {background-color: pink; outline:pink dotted thick;}
    #divUserStatus_levelInfo .gig-GMBalloon-frame {background-color:mediumpurple; font-style:italic; }
    #divLeaderboard_details .gig-GMBalloon-frame {background-color: #00aaaa;}
    #divChallengeStatus_levelInfo .gig-GMBalloon-frame {background-color: red; }
    #divAchievements_levelInfo .gig-GMBalloon-frame {background-color: lightblue; }
    #gigNotifications .gig-notifications-body  {background-color: tomato;}
</style>

The "points" popup of the User Status add-on will now have a pink background and a pink dotted outline:

In the same manner:

  • The "level info" popup of the User Status add-on will now have a medium purple background and an italic font style.
  • The "details" popup of the Leaderboard add-on will now have a different background color (#00aaaa).
  • The "level info" popup of the Challenge Status add-on will have a red background color.
  • The "level info" popup of the Achievements add-on will have a light blue background color.
  • The body section of the Notification add-on will have a tomato background color.

Templates

A template is a layout definition for a group of related graphics elements in the add-on. The add-on includes customizable templates, and you may assign each template with an HTML string that overrides its default graphic layout.

Achievement

The 'detailsPopupTemplate' parameter of the gm.showAchievementsUI method is an HTML template representing the design of the body of the tooltip pop-up, supporting the following placeholders: $levelTitle, $levelDescription, $challengeTitle, $challengeDescription, $pointsCurrent, $requiredAchievement, $achievementsToNextLevel, $nextLevelTitle, $nextLevelDescription, $nextLevelLockedBadgeURL and $nextLevelActionURL. You may override the default design by placing new values in these placeholders.

Challenge Status

The 'detailsPopupTemplate' parameter of the gm.showChallengeStatusUI method is an HTML template representing the design of the body of the tooltip pop-up, supporting the following placeholders: $levelTitle and $levelDescription. You may override the default design by placing new values in these placeholders.

Leaderboard

The 'userTemplate' parameter of the gm.showLeaderboardUI method is an HTML template representing the design of the leaderboard display, supporting the following placeholders: $UID, $name, $rank, $points, $photo, $top3Icon, and $friendIcon. You may override the default design by placing new values in these placeholders.

The 'detailsTemplate' parameter of the gm.showLeaderboardUI method is an HTML template representing the body of the details popup, supporting the following placeholders: $UID, $name, $rank, $points, $photo, $top3Icon, $friendIcon, $challengeBadge, and $otherChallengesBadges. You may override the default design by placing new values in these placeholders.

The $name placeholder is populated as follows:

Profile object containsPlaceholder displays
firstNamefirstName
lastNamelastName
firstName & lastNamefirstName&nbsp;lastName (i.e., "firstName lastName")
nicknamenickname
ANY NAME & nicknamenickname

 

Notification

The 'headerTemplateparameter of the gm.showNotifications method is an HTML template representing the title of the notification dialog, supporting the following placeholders: $levelTitle, $levelDescription, $challengeTitle, $challengeDescription, $pointsCurrent, $requiredAchievement, $achievementsToNextLevel, $nextLevelTitle, $nextLevelDescription, $nextLevelLockedBadgeURL and $nextLevelActionURL.You may override the default design by placing new values in these placeholders.

The 'bodyTemplate' parameter of the gm.showNotifications method is an HTML template representing the body of the notification dialog, supporting the following placeholders:$levelTitle, $levelDescription, $challengeTitle, $challengeDescription, $pointsCurrent, $requiredAchievement, $achievementsToNextLevel, $nextLevelTitle, $nextLevelDescription, $nextLevelLockedBadgeURL and $nextLevelActionURL. You may override the default design by placing new values in these placeholders.

The 'footerTemplate' parameter of the gm.showNotifications method is an HTML template representing the footer of the notification dialog, supporting the following placeholders: $levelTitle, $levelDescription, $challengeTitle, $challengeDescription, $pointsCurrent, $requiredAchievement, $achievementsToNextLevel, $nextLevelTitle, $nextLevelDescription, $nextLevelLockedBadgeURL and $nextLevelActionURL. You may override the default design by placing new values in these placeholders.

The 'dialogTemplate' parameter of the gm.showNotifications method is an HTML template representing the full template of the notification dialog, composed of the first three templates, and also a frame, margins, and the following placeholders: $shareButton, and $closeButton. You may override the default design by placing new values in these placeholders.

Templates Example

In the following example the contents of the GM add-ons are changed using their template parameters:

var leaderboardParams = {
    containerID: 'divLeaderboard'
	detailsTemplate: 'Name: $name <br>Rank: $rank <br>Points: $points<br>Photo: $photo'
};

var achievmentsParams = {
    containerID: 'divAchievements'
	detailsPopupTemplate:'Level title: $levelTitle <br>Challenge: $challengeTitle <br>Current points:  $pointsCurrent'
};

var notificationParams = {
	debugMode:true // The Notifications add-on will appear even if no new level has been reached
	headerTemplate: 'You reached the $levelTitle level',
	bodyTemplate: 'Challenge Title: $challengeTitle <br>Challenge Description: $challengeDescription <br>'
};

In this example the "details" popup of Leaderboard add-on, will change its default layout, and instead will display the name, rank, points, and photo, as set in the 'detailsTemplate' parameter of the gm.showLeaderboardUI method.

 

In the same manner:

  • The "details" popup of the Achievements add-on will change its default layout, and instead will display the level title, the challenge title, and the current points, as set in the 'detailsPopupTemplate' parameter of the gm.showAchievementsUI method.
  • The "header" part of the Notification add-on will change its default layout, as set in the 'headerTemplate' parameter of the gm.showNotifications method.
  • The "body" part of the Notification add-on will change its default layout, as set in the 'bodyTemplate' parameter of the gm.showNotifications method.

Dialog or Embedded

The Notification add-on is displayed as a dialog (pop-up) on the right hand corner of the browser screen.

The Achievements, Challenge StatusUser Status, and Leaderboard add-ons should be embedded inside the application. This behavior is controlled by the presence of the containerID, which is passed to the add-on's method calls (as part of the 'params' object).

To embed a add-on in a certain DIV?, set the containerID parameter with the specific DIV ID:

<div id="divPlugin"></div>
<script>
    var pluginParams = {  
            containerID: 'divPlugin'  
    };

    gigya.gm.showPluginUI(pluginParams);  
</script>

If the containerID parameter is provided, the add-on will embed itself in the corresponding DIV - in which case the application must hide the add-on when it is no longer required. If the containerID parameter is not provided (or if it is set to 'null' value), the add-on will be displayed as a dialog and will disappear when the relevant user interaction is completed.

Variants and Action Attributes

 

Note: The variants / action attributes will work only if the Enable Challenge Variants setting is checked in the Advanced Settings section of the Challenge Settings in Gigya's site.

You can choose to display the Gamification add-ons filtered according to a certain attribute. For example, you can show the Leaderboard add-on only for top users in a certain section of the site, instead of the top users for the specific challenge in the entire site. This instance of the challenge, which is filtered according to the section of the site, is called a Challenge Variant

Dividing the site into sections may be useful for an entertainment website, for example, which may want to allow users to build reputation by content expertise, such as Glee and 30 Rock in TV or Pop and other music genres. 

When a user enters the section of the site for which we want to display the top users (for example), all the actions that he does on this section need to be tagged as belonging to this section. In order to add this option you must add an attribute (or attributes) to the actions that can be done on this section. 

First select all the actions to which you want to add an attribute (or attributes), and find their corresponding APIs, e.g. socialize.showShareUI, socialize.logincomments.flagComment, or gm.notifyAction for custom user actions.

Add the actionAttributes parameter to each action. The actionAttributes parameter receives a JSON object, comprised of a set or sets of a key (category) and a value or values, i.e.:

    {
        "<attribute1 name>": ["<attribute1 value1>", "<attribute1 value2>", ...],
        "<attribute2 name>": "<attribute2 value>",
        ...
    }
For example:
    {
        "tv-show": ["glee", "30rock"],
        "music": "pop"
    }

The challenge variant is in fact a hash function performed on a pair of key and value, producing a string that represents the pair. Challenge Variants will automatically be created for each attribute that is reported for a relevant action when the setting is enabled.

In this example the action receives three attributes: {"tv-show":"glee"}, {"tv-show":"30rock"}, and {"music":"pop"}. This parameter may receive a list of up to three sets of key and value entries per call. If more values are entered, only the first three will count and the rest will be ignored. The three sets of key and value can be one key with three values, or three keys with one value each, or two keys, one with two values and the other with one value. 

You can also choose to input attributes using a generic "Tags" key, with no category name, for example: {"tags": ["glee", "house", "pop"]}. In this case the action receives these three attributes: {"tags":"glee"}, {"tags":"house"}, and {"tags":"pop"}.

Once all the actions you want have the actionAttributes you can use any one action attribute (a set of key and value) to filter any one of the GM add-ons (except for the Notifications add-on). 

If you want to filter the Leaderboard add-on only for top users in the "Glee" page of the site, tag all the actions that you want by calling their APIs with actionAttributes : {"tv-show":"glee"}. Then call gm.showLeaderboardUI with actionAttributes: {"tv-show":"glee"}.

You can apply the action attributes in the same manner to the Achievements add-on (gm.showAchievementsUI), the Challenge Status add-on (gm.showChallengeStatusUI), and the User Status add-on (gm.showUserStatusUI).

In the gm.getChallengeStatus method you can retrieve the current status of the user in a specified challenge according to a specific attribute. In the gm.getTopUsers method you can retrieve the top ranked users for a specified challenge according to a specific attribute.

Here is an example that may further clarify the variants subject:

  • Challenge Variants are enabled on a Share challenge.
  • A user shares and the action attribute "TV show - Glee" is passed.
  • The site filters the Share challenge leaderboard for the "TV show - Glee" attribute.
  • The leaderboard shows only users who have accrued points to the "TV show- Glee" challenge variant, with only the points and rank associated with that challenge variant. For example, if the user has 100 points and is Rank 1 for the Share challenge, but has 50 points and is Rank 2 for the Glee challenge, then the Glee leaderboard will show him as having 50 points and Rank 2.