Was this article helpful?

Game Mechanics

Last modified 05:33, 13 May 2014

Gigya's Game Mechanics (GM) plugins are pre-built Web GUI elements that can be used to display GM 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. 

Note: Game Mechanics is a premium platform that requires separate activation. If Game Mechanics is not part of your site package please contact your Gigya account manager or contact us by filling in a support form on our site. You can also access the support page by clicking "Support" on the upper menu of Gigya's site.

 

Available GM Plugins

There are five GM plugins:

  • Achievements - enables users to view their currently achieved level, badge image and title per challenge.
  • Challenge Status - enables users to view all the badges, both locked and unlocked, of a specified challenge.
  • User Status - enables users to view their current status in a specific challenge, and control their privacy settings.
  • Leaderboard - displays the top ranking users in a specific challenge.
  • Notification - notifies the users of their latest achievements, and allows them to share this to their social networks.

 

gm_Plugins.gif

 

gm_notification1.gif

 

A Working Example

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

 

UI Customization

Gigya plugins are highly customizable. You can customize each plugin 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 plugins:

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

 

HTML Elements Style (CSS) Classes

Any elements on the plugin 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 plugin and assign a new style to it. Please make sure to use the plugin's container <div> ID when assigning style, so it will not affect other elements on the page.

For example:

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

In this example the Leaderboard's plugin's font has been changed to Arial. 

The GM plugins 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 plugin popups have static identifiers, that together with the plugin'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 the plugins. Add the following lines to the <head> 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 plugin will now have a pink background and a pink dotted outline:

css_points.gif

In the same manner:

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

 

Templates

A template is a layout definition for a group of related graphics elements in the plugin. The plugin 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.

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 plugins 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 plugin 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 plugin, 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.

template_leaderboard.gif

 

In the same manner:

  • The "details" popup of the Achievements plugin 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 plugin will change its default layout, as set in the 'headerTemplate' parameter of the gm.showNotifications method.
  • The "body" part of the Notification plugin will change its default layout, as set in the 'bodyTemplate' parameter of the gm.showNotifications method.

 

Dialog or Embedded

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

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

To embed a plugin 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 plugin will embed itself in the corresponding DIV - in which case the application must hide the plugin when it is no longer required. If the containerID parameter is not provided (or if it is set to 'null' value), the plugin 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 plugins filtered according to a certain attribute. For example, you can show the Leaderboard plugin 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 plugins (except for the Notifications plugin). 

If you want to filter the Leaderboard plugin 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 plugin (gm.showAchievementsUI), the Challenge Status plugin (gm.showChallengeStatusUI), and the User Status plugin (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.

Tags

This page has no custom tags set.

Comments

You must to post a comment.

Attachments