Last modified 10:38, 15 Sep 2014

Gigya's Game Mechanics (GM) is a social loyalty and rewards platform that can be easily embedded in your website, increasing site engagement and making your users' experience more enjoyable.



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.


Once you integrate the Gigya GM platform, your site will have one or more challenges in which your users can participate. The challenges have defined levels, and each level has a badge associated with it. Users on your site will be able to perform predefined actions or simply-defined new actions, and receive virtual rewards such as points for these actions. 

This guide takes you through the steps of integrating GM into your site:

1. Get familiar with GM terminology

2. Learn about Overall Rank, Gigya's default challenge

3. Set up and configure your GM platform

4. Incorporate GM plugins

5. Reference the JavaScript and REST APIs

6. Go through our best practice checklist

7. Get statistics through GM reports

8. Understand GM points, and how to redeem them



Gigya's Game Mechanics (GM) platform uses specific terminology throughout the documentation, site administration, and user interfaces. In order to implement Gigya's GM more easily, familiarize yourself with these commonly used terms:

  • Action - An action that a user performs on your site, such as login, share, etc. The actions can be default Gigya actions or custom user actions, and each action has a point value. Users are also able to refer other users to your site, and actions performed by a referred user may grant the original user additional points. These actions are called referral actions.
  • Point - A unit that is appointed to users when they perform an action on your site. A user can accumulate points to earn virtual rewards, such as levels and badges.
  • Challenge - A set of actions and levels of the same theme. Users participate in site challenges by performing actions associated with the challenges.
  • Level - A milestone within a challenge. A level is achieved by a user who earns a specified number of points, and / or performs a specified action or a set of specified actions. The level is represented by a badge and a level title.
  • Badge - A visual representation of a level of a challenge. Each level has two badges, an unlocked version if the user has reached the level, and a locked version if the user has not yet reached the level.
  • Leaderboard - A display of the top users. It is a way for users to know where they rank within the challenge's community.


Overall Rank

Overall Rank is a powerful socially engaging challenge, which is provided as Gigya's default challenge. Overall Rank encourages site engagement through rewards and increases user activity and loyalty. 

The Overall Rank challenge has all enabled actions associated with it, including newly defined actions and default Gigya actions, which are actions predefined by Gigya. Gigya's predefined actions are social actions, such as sharing content to social networks, participating in a chat, posting comments, etc. These actions are all initiated by Gigya's Plugins or APIs; Gigya tracks the enabled actions and rewards users with points, the site does not need to report them. To view all predefined Gigya actions, all of which belong to this challenge, refer to the Default Gigya Actions section in Gigya's site.

You may define new actions, and any new actions you define are automatically associated with the Overall Rank challenge. These custom user actions are not tracked by Gigya, and your site must report them to Gigya.

Overall Rank has four defined levels; the titles of the levels are Beginner, Enthusiast, Expert, and Master. Each level can be reached by users who perform social actions and accumulate the specified number of points that the level requires. Each level of the challenge also has a badge to represent it.

To view all levels that belong to this challenge, refer to the Levels section of the Challenge Settings page on Gigya's site.

Many of the Overall Rank challenge properties are customizable; you can add or remove levels, and redefine each level's title, description, badges, and threshold. The default Gigya actions cannot be removed, but the following properties of each action can be changed: name, description, points value, daily cap, minimal Interval, and status.

When you integrate Gigya's GM, we recommend you use the Overall Rank challenge, as well as defining new challenges that are suited to your site needs.

Setting up Your GM Console

Your GM console can include just the Overall Rank challenge, which is configured and ready to use, but we recommend adding more challenges to your site, specific to your users' needs.

This section takes you through the steps of adding a new challenge:

1. Go to the Game Mechanics Setup section of Gigya's website. Please make sure you are signed in.

2. Press the Add new Challenge button and a popup will appear. Fill in a unique challenge ID and a challenge title, and press Save. The new challenge is now added to the challenges table.

3. Press the Challenge Settings button to open the Challenge Settings page, which is divided into three sections: 'Configuration', 'Actions', and 'Levels'.

4. In the 'Configuration' section: Add a description of the new challenge (optional).

5. In the 'Actions' section: Select the actions you want to associate with your challenge. You must select at least one.

6. In the 'Levels' section: Add at least one level to your new challenge:

a. Press the Add new Level button in the Levels table in order to open a blank new level form.

b. Fill in the following fields: Title, Description (optional), Badge URL, Locked Badge URL (optional), Points threshold (optional), Actions threshold (optional), Points bonus (optional), Action URL (optional), and press Apply

7. Return to the 'Configuration' section on the page and change the Status to Enabled.


The actions you added to your new challenge were selected from the predefined default Gigya actions, but you can define new custom user actions and add them to your new challenge. 

You can learn more about the Game Mechanics Setup in our Configuration and Administration guide, which explains in detail all the Game Mechanics settings and options.


Incorporating GM Plugins

Gigya's Game Mechanics (GM) plugins are customizable 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.

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 the 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.
  • Notifications - notifies the user of his latest achievement, and allows him to share this to his social networks.

The plugins are easy to implement, and the process involves only adding a few lines of code. On each of the plugins' pages, you can find full explanations and code implementation steps.

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


JavaScript and REST APIs

In addition to the GM plugins, there are supporting APIs, together providing a full Game Mechanics GM package.

There GS API methods are supported both for client side (JavaScript API) and server side (REST API). We encourage you to work server to server whenever applicable, using Gigya's REST API, or a suitable Server Side SDK that provides a wrap around the REST API.

GM API methods that should be noted:

  • gm.notifyAction - notifies the GM engine about an action that a user has taken in the site. This method should be used to notify about site custom actions. You may read about setting up site custom actions in the Custom User Actions section of the Game Mechanics guide.
  • gm.redeemPoints - deducts a specified number of points from a user in a specific challenge. You can use this method to redeem points in exchange for benefits such as coupons, gifts, etc.

On the client side, Gigya's JavaScript API is your access to the GM plugins. The JavaScript API calls for displaying the GM plugins are gm.showAchievementsUI, gm.showChallengeStatusUIgm.showUserStatusUI, gm.showLeaderboardUI, and gm.showNotifications. Please refer to the JS Game Mechanics API Reference for the list of methods and parameters, and for additional client-side methods.

Best Practice Checklist

The following checklist summarizes the best practices for implementing Gigya's Game Mechanics platform:

  • We recommend working server-to-server whenever applicable, which is more secure than client-side access.

GM Reports

Gigya’s cross-platform analytics deliver interaction and traffic data, including details by challenge and activities. Gigya’s graphic reports are available on Gigya's website under the Reports tab (please make sure you are logged in).

The available GM reports are:

  • Top users
  • Daily activity
  • New daily users by challenge
  • Users by challenge
  • New daily users by level

For detailed explanations and screenshots, please refer to the Game Mechanics section in the Reports guide.


GM Points

GM points are appointed to users when they perform an action on your site. These actions for which your users earn points can be either Default Gigya Actions or Custom user actions. A user can accumulate points to earn virtual rewards, such as levels and badges.

In addition, you are allowed to give Custom user actions negative point values, and every time a user performs an action that has a negative point value, the points will be deducted from the user's points. The only limitation is that the user cannot have accumulated points that are less than zero. 

The GM engine accumulates points in three different manners:

  • Total Points - Overall earned points that have been accumulated up to date. The 'total points' value can only increase, you can't subtract from it. The idea behind this is that once a user achieves a certain level on a challenge, it's for lifetime, levels (badges) achieved will not be taken from him even if he redeems points.
  • Current Points - The current points a user has. When a user redeems points he is left with the current points. Current point are accumulated and can be redeemed using the gm.redeemPoints method for benefits such as coupons, gifts, etc.
  • 7 Days Points - Points earned during the past 7 days. Similar to the 'Total Points', 7 Day Points are only accumulated and can not be redeemed.

Redeeming Points

You can redeem points by using the gm.redeemPoints method. This method deducts a specified number of points from a specified user in a specified challenge. The points are redeemed only if the number of points to redeem isn't higher than the number of current available points, in which case the operation will fail.

Another way to redeem points is by using the Game Mechanics Achievements section of the Identity Access tool.


Manually Granting Points to Challenges

You can manually grant points to specified challenges by using the gm.notifyAction API method. Call the method with an action called _points, then in the points parameter specify the number of points you want to award the challenges, and in the challengeIDs enter the challenge IDs of all the challenges to which you want to grant these points. You can also use this method to reduce points, by awarding negative points to the challenge.

Another way to manually add or reduce points to challenges is by using the Game Mechanics Achievements section of the Identity Access tool.

Page statistics
23064 view(s) and 20 edit(s)
Social share
Share this page?


This page has no custom tags.
This page has no classifications.


You must to post a comment.