The following guide walks through the the Gigya Loyalty (GM) setup and serves as a reference document for the configuration options.

 

The following guide walks through Gigya's Loyalty (GM) setup and serves as a reference document for the configuration options.

Note: The Loyalty configuration and administration pages are visible only if Game Mechanics is part of your site package and has been activated by Gigya. 

Introduction

This guide is divided into three main sections, according to the three GM pages on Gigya's site:

  1. Setup - This section describes the general GM settings, such as a callback URL, and client-side API access. It also explains the challenges table, and how to create a new challenge.
  2. Challenge Settings - This section describes the specified challenge's configuration, i.e., the challenge title, description, status, and ID. It also explains about the challenge actions and how to add or remove actions associated with the challenge. This section also includes information about the challenge levels table, and here is where a new level is added to the challenge.
  3. Actions - This section describes the action types and the action properties. It also explains about the default Gigya actions, the custom user actions, and the referral actions. In this section you can also learn about editing actions, and adding a new action.

Setup

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

The Game Mechanics Setup page may also be accessed by clicking Settings in the upper menu and then Game Mechanics Setup in the left menu:

General Settings

Under the General Settings section, you can define settings that apply to all challenges on your site.

Export and Import

This button enables you to export your GM settings once they are defined, and import them in order to clone the settings across sites. This is explained in full at the Duplicating Your GM Settings section of this page.

Callback URL

You can define a callback URL, which is the web address through which the site will be notified for each new user achievement. This means that every time a user achieves a new level in a challenge, the site will be notified of the event with a POST method, with the following parameters:

event=newLevel&
eventData={"UID":"id_test","challengeID":"ch1","level":2,"points":80}&
nonce=b7a00b88e1b9469599e5f53049eb1b6d&
timestamp=1332079751&
signature=gCLCNiNxt8xGkzqzP7MugKLv2Ak=

  Sample Code PHP:

<?php     
     /**  
      * --- Sample Event Data ---       
      * event=newLevel&       
      * eventData={"UID":"id_test","challengeID":"ch1","level":2,"points":80}&       
      * nonce=b7a00b88e1b9469599e5f53049eb1b6d&       
      * timestamp=1332079751&       
      * signature=gCLCNiNxt8xGkzqzP7MugKLv2Ak=       
      */ 

   static function calcSignature($baseString,$key) 
   { 
       $baseString = utf8_encode($baseString); 
       $rawHmac = hash_hmac("sha1", utf8_encode($baseString), base64_decode($key), true); 
       $signature = base64_encode($rawHmac); 
       return $signature; 
   } 

   function doGMCallback() 
   { 
       $event = $_GET["event"]; 
       $eventData = $_GET["eventData"]; 
       $nonce = $_GET["nonce"]; 
       $timestamp = $_GET["timestamp"]; 
       $signature = $_GET["signature"]; 
       $signatureBase = $event . "_" . $eventData . "_" . $nonce . "_" . $timestamp; 
       $secret = "[your gigya secret key]"; 
       $expectedSignature = calcSignature($signatureBase, $secret);   
    
       // Now compare the expectedSignature value to the signature value returned in the callback 
       if ($signature === $expectedSignature) 
       { 
           // Do something interesting with the eventData here 
           $jsonEventData = json_decode($eventData); 
           $UID = $jsonEventData->{'UID'}; 
           $challengeID = $jsonEventData->{'challengeID'}; 
           $level = $jsonEventData->{'level'}; 
           $points = $jsonEventData->{'points'}; 
        } 
    } 
    
    doGMCallback(); 
?>

 

* Security Validation:
Gigya generates the nonce, timestamp, and signature in the same manner as described under Signing requests section. You may use these fields to enhance security and validate the authenticity of the callback source (make sure that the source is in fact Gigya). To do that:

  1. Generate a signature in the same manner, based on the values in the request url (i.e., timestamp, secret key, nonce and all request parameters). Note - if you are using one of our SDKs, you may use the SigUtils.calcSignature method to generate the signature.
  2. Compare the generated signature with the signature received in the callback URL. Make sure both signatures are identical.

  Sample Code (C#):

string evt = "[the value of the event parameter]";   // e.g., "newLevel"
string nonce = "[the value of the nonce parameter]"; // e.g., "b7a00b88e1b9469599e5f53049eb1b6d"
string timestamp =  "[the value of the timestamp parameter]";   // e.g., "1332079751"
string data = "[the value of the eventData parameter]";    // e.g., "{\"UID\":\"id_test\",\"challengeID\":\"ch1\",\"level\":2,\"points\":80}";
string signatureBase = String.Format("{0}_{1}_{2}_{3}", evt, data, nonce, timestamp);
string secret = "[your gigya secret key]";
string expectedSignature = Gigya.Socialize.SDK.SigUtils.CalcSignature(signatureBase, secret);  // Using Gigya's .Net SDK
// Now compare the expectedSignature value to the signature value returned in the callback

Client Side Access

You can enable client-side access to the API to allow updating of user actions. This will enable the usage of the gm.notifyAction API method from your client application. We do not encourage executing this method from your client side. It is highly advised disabling client access and executing this method from your server so as to prevent hacking. Please find the server side API in REST API > gm.notifyAction.

Challenges

The Challenges section on the Game Mechanics Setup page displays the challenges associated with the site. This includes a default challenge called Overall Rank, which is displayed in the first challenges table (expand to view), and custom challenges that you can define, which are displayed in the second table.

 

 

Note: The Gamification Challenges can be localized using the Global Configuration. Please contact your  for details.

 

Challenges Tables

The challenges tables displays the details of each challenge:

Adding a New Challenge

To add a new challenge, press the Add new Challenge button and the following popup will appear:

Fill in a unique challenge ID and a optionally a challenge title, and press save. For example, use "cooking" as the challenge ID and "Top Chef" for the challenge title.

 

Note: The challenge title is optional, but for the best practice implementation, we recommend adding a challenge title to each challenge. 

 

The new challenge is now added to the custom challenges table:

The status of the newly added challenge is disabled (see screenshot above). To complete the process of adding a new challenge, configure the settings of the new challenge by clicking the Challenge Settings button. This opens the Challenge Settings page described in the Challenge Settings section on this page.

Deleting A Challenge 

You can delete any challenge, except for the default challenge. 
Deleting a challenge removes all of it's data, including all user achievements associated with the challenge. This process may take a while, during which the challenge status will be set to 'deleting'.
While in deletion mode, the challenge status will change to "Deleting..." ( the challenge will not appear in the 'settings' page challenges drop-down while in 'deleting' state ) and the ID of the challenge will be unavailable (i.e., attempts to create a new challenge by the same ID will result in an error).
Once the deletion process is complete, the challenge will no longer appear in the console and the ID will regain availability.

Challenge Settings

You can open the Challenge Settings page on Gigya's site by clicking Settings in the upper menu and then Challenge Settings in the left menu. This opens the Challenge Settings page for the default challenge:

You can also access the Challenge Settings page by clicking the Challenge Settings button of a specific challenge.

Once on the page, you can select the challenge name from the drop-down menu, in this case "Top Chef":

The challenges are divided into enabled and disabled challenges. 

Configuration

The Configuration section includes the challenge title, description, status, and challenge ID:

Add a description (optional), and proceed to add Challenge Actions and Levels, as explained in the following sections. Once you define the actions and levels, return here to enable the challenge.

 

 

Note: Challenges created via API (gm.setChallengeConfig) can be edited from the Platform UI.

 

Advanced Settings

The Advanced Settings section includes the "Hide challenge from user until first level is achieved" checkbox, and the "Enable time window" checkbox:

Challenge Actions

Each challenge is associated with actions to be performed by the user in order to level up. 
 An action can grant the user points on the level, and also advance his progress on an action based level.

In this section you may define which actions you want to associate with your challenge.

The Actions section displays a table of actions associated with the challenge for which the user can achieve points.

At first, a new challenge has no actions associated with it, and you must add at least one action from the available actions, by clicking the Add action button:

 

You can then select the actions you want associated with the new challenge from the list of actions that are displayed:

All defined actions are listed here, including both Default Gigya Actions and Custom User Actions. You can add Custom User Actions in the Actions section of this page.

Each action has the following information:

 

For more information about the actions, their properties, and how to add a new action, refer to the Actions section of this page.  

Note: The Overall Rank challenge has all enabled Default Gigya Actions and Custom User Actions assigned to it, and you cannot remove any actions.

Group Actions

Group actions are marked with a "*". Group challenges and actions are defined in the primary site of a group and displayed on each of the site's child sites. Also in the primary site settings you can see all child site's actions/challenges. Read more about Game Mechanics in Site Groups.

Levels

This section includes a table of the levels of the challenge, and a button to add a new level.
At first, the new challenge has no defined levels, and you must add at least one level in order to activate the challenge:

Levels Table

The levels table displays the following information for each level:

Adding a New Level

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

In order to add a new level, you must fill in the following fields and press Apply:

          Notes: This field determines whether the level is action based, point based or mixedYou must add at least one action or a number of points to the level threshold in order to add a new level.
                    If both points and actions thresholds are specified, achieving both of them are needed in order to level up. In this case, in order to level up, the user must perform 2 shares and earn 10 points.

 

Note: The level title and badge URL are optional, but for the best practice implementation, we recommend adding a level title and badge URL to each level. 

 

Action Based vs. Point Based Levels  

When adding a new level, the thresholds that you set up define whether the level is action based, point based or mixed (level has both a points threshold and an actions threshold).

A point-based level means that the user has to accumulate the number of points defined in the threshold in order to level up, regardless of the type of actions that he performed in order to receive the points.
For an action-based level, the user has to perform certain actions that are defined in the actions threshold, regardless of the points he has accumulated.
Defining both a points threshold and an actions threshold creates a mixed-based level, where the user must complete the actions defined in the actions threshold as well as accumulate the points threshold in order to level up.  

The levels you add to the challenge are displayed in the levels table. In this example, we added three levels to the Top Chef challenge:

 

You can remove a level by pressing the "X" icon, and edit a level by pressing the "Edit" icon. You can also reorder the levels by using the handles on the left side of each row.

Note: Now that your new challenge has at least one action and at least one level, you can return to the Configuration section of the page and enable the challenge.

Once a Challenge is enabled, you should not add additional Levels. Adding levels to an existing Challenge will result in a user's points not translating across levels correctly and may also result in negative points for some levels.

Actions

You can open the Actions page on Gigya's site by clicking Settings in the upper menu and then Actions in the left menu:

A user can earn points by performing actions on your site, such as logging in or sharing content.

Action Properties

Each action has the following information:

 

Note: Actions created or updated via API (gm.setActionConfig) can be edited from the Platform UI.

 

Action Types

There are three types of actions:

All enabled actions are assigned to the Overall  Rank challenge. This means that every time a user on your site performs an action, default or custom, he will earn points towards the Overall Rank challenge. You may assign any of these default Gigya actions and custom user actions to new challenges, and then when a user performs one of the actions, he will earn points towards all challenges that include this action.

Assign actions to challenges in the Challenge Settings page on Gigya's site, and read about it in the Challenge Actions section of this page.

Default Gigya Actions

Default Gigya actions are actions that are initiated by Gigya plugins or APIs. Gigya tracks these actions, and the site does not need to report them.

A few examples of default Gigya actions are:

 

The Actions page on Gigya's site displays the full list of the default Gigya actions:

 

Edit an action by pressing the action's Settings icon in the table. This opens the Edit Actions popup, described in the next paragraph.

When using the Share Bar with Gamification to award points via _clickbacks, for certain providers that do not support appending additional tracking parameters to the share URL (twitter-tweet, googleplus-share, Facebook Share dialog), it is necessary to use a work around to count _clickbacks. In order to award _clickback points to the user using the above providers, please call socialize.shortenURL prior to including the URL in the User Action object that is passed to the socialize.showShareBarUI method.

Note: This solution is not effective with Facebook's Share dialog.

 

Edit Actions

Edit an action by pressing the settings icon of the action in the Actions table. For example, press the settings icon of the Share action. This opens the following Edit Actions popup:

Refer to the Action Properties section of this page to understand the Share action's information.

 

Custom User Actions

Custom actions are actions that you have defined. These custom actions must be reported to Gigya by the site, through the gm.notifyAction API method with a unique action identifier.

A few examples of possible custom user actions are:

 

The Actions page on Gigya's site displays the full list of the custom user actions if defined:

 

Adding a New Action

You can add custom user actions by pressing the Add new Action button, and filling in the Action Properties:

 

Notes:

  • The Action ID cannot begin with the "_" sign for Custom User Actions, because actions that begin with "_" are reserved for Gigya default Action IDs.
  • The action name is optional, but for the best practice implementation, we recommend adding an action name to each action. 

The actions you add are displayed in Custom User Actions table. In this example, we added the Poll action:

 
All custom user actions that you define are automatically assigned to the Overall Rank challenge, Gigya's default challenge. You can also assign them to new challenges that you define.

Note: In order to make a full use of the action, your site must report to Gigya each time a user performs this action in your site. Reporting the action is done by executing the gm.notifyAction method and passing the action's ID (as defined in the above table).

Negative Points

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. 

Referral Actions

Users may refer other users to your site, and actions performed by a referred user may grant the original user (referrer) additional points. For example, a logged-in user shares a link, and as a result a second user clicks the link and reaches the site. The new referred user then decides to register to the site and perform an action, such as commenting. The new user will be granted points for commenting, while the referrer will be granted points for referring the user for this specific action (comment).

The actions the referred user performs can be either Default Gigya Actions or Custom User Actions, and are called triggering actions since the action triggers allocation of points to the original user.

In this section you can see, add, edit, and delete the list of actions that reward original users with points.

The Actions page on Gigya's site displays the full list of the actions that reward the referring user with points:

 

Adding a New Referral Rewarding Action

You can add actions that will reward original referring users with points by pressing the Add new Action button, and filling in the Action Properties:

In addition to the general Action Properties, please select the triggering action from the drop-down menu. The triggering action is an action that the user who was referred to the site performs. This can be any one of the listed default Gigya actions or the custom user actions.

The actions you add are displayed in Referral Actions Rewarding table. In this example, we added the Example action:

 

 

Note: In order for the referral actions to work, you must set the Redirect Method in Gigya's Site Setup to "Server redirect, append to existing URL fragment". 

 

Using Referral Action Triggers Across Challenges

There is a use case for referral actions that deserves its own explanation - using referral action triggers that aren't themselves part of a challenge. This is a special case because ordinarily, any action used as a trigger for a referral action must also be assigned to any challenge awarding points to the referrer. But what if you don't want the referred user to be awarded any points for performing said action?

The rest of this section will use a purchase scenario as an example.

Assume that purchase actions award points equal to the purchase amount to the user (by calling gm.notifyAction and overriding the point value). But let's say that you only want to use the purchase as a trigger, and award a pre-defined number of points to the referring user regardless of the purchase amount, and zero points to the referred user.

To make this possible, first, you need to set up two new actions:

  1. Create a new custom user action with an ID of "purchase_for_referral" and a point value = 0.
  2. Create a new referrer-rewarding action called "friend_purchased" with a point value equal to the number of points awarded to the referring user once the referred user makes a purchase. The triggering action for this should be the action defined in step 1 - "purchase_for_referral". 
     

Now, when a user makes a purchase on your site, call gm.notifyAction twice - passing the purchase action the first time, and the referrer-rewarding action the second time.

This will award zero additional points to the referred user while awarding five points to the referring user for the purchase.

Duplicating Your GM Settings

After configuring GM settings for your site, you might want to duplicate these settings for other sites you have, without having to define all the GM settings again.

In the Game Mechanics Setup section of Gigya's website, under the General Settings section, there is an Export and Import button. This button enables you to export your GM settings once they are defined, and import them in order to clone the settings across sites.

The import and export process is done by generating a JSON file with all the source site GM settings, including all challenges, the actions and levels associated with each challenge, and the rest of the GM settings.

Exporting GM Settings

If you wish to export the GM settings you defined for your site, click the Export and Import button. The following dialog will open:

Click the Export button to generate a JSON file with current site's GM settings. When the file is ready, save it to your desktop.

Importing GM Settings

If you wish to import GM settings that you have defined earlier to another site, click the Export and Import button, then click the Import tab. The following dialog will open:

Choose whether you want to import the settings directly from one of your sites, or from the file that you saved when you exported the settings.

Make sure you are importing the settings to the correct site, by selecting the site from the drop-down menu at the top of the page:

When Importing GM settings to this site, settings with the same name as existing settings will be deleted, and the rest of the imported settings will be added.

Now that you understand that importing the settings will override the site's current GM settings by the same name (if defined), check the checkbox to verify that you understand the implications, and click the Import button.

Note: In order to properly import a GM settings JSON file, it is extremely important that you do not make any changes to the JSON file you exported.

After you successfully import the GM settings, for each challenge, go to the Challenge Settings and change the challenge status to Enabled.

Game Mechanics in Site Groups

When you have multiple sites using a single database and a site group has been configured by a Gigya admin, you can create Challenges and Actions at the Parent site level. 

GM Group Behavior Summary

  1. Challenges that are created in the master (father) site are available to his children too.
  2. Actions that are created in one of the children, are available to the master too as virtual actions (he cannot edit it, but can use to link it in his challenges).
  3. A brother cannot see the other brother actions. When a challenge is defined at the master then its points are accumulated there, so all the children see the same points and levels, even if they were generated by another brother. Shared actions should be defined at the master level and then all children can call notifyAction on them.
  4. If a child has an action with the same name as the master, it will override it.
  5. The third table in the actions page (Group Custom User Actions) will not appear on children sites.

Group Custom User Actions

Go to the GM Actions page of Gigya's website. The page may also be accessed by clicking Settings in the upper menu and then Actions in the side menu:

Scroll to the bottom of the page, and you will see the Group Custom User Actions table. The table lists all custom user actions from sites that belong to the group, not including custom actions of the primary site, which are listed in the previous table named Custom User Actions.

Each group custom user action has the following details:

These group custom user actions cannot be deleted or edited from here (the primary group site view); you can delete or edit a group custom user action only by going to its origin site.

Group Challenges

Go to the Game Mechanics Setup page of Gigya's website. The page may also be accessed by clicking Settings in the upper menu and then Game Mechanics Setup in the side menu:

 

 

The challenges that are associated with the primary challenge are listed under the default challenge (Overall Rank), and can be used in any of the sub-sites of the group. When you define a new challenge for the group, you can assign any action to it, including actions from sub-sites. You cannot edit these actions that were defined in the sub-sites, you have to go to its origin site to edit or delete a group custom user action.