User Status

Skip to end of metadata
Go to start of metadata

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.

Introduction

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.

                    

Pop-ups

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.

Action URL

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

Implementation Overview

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.

Code Example

Add the following code snip to the of your page to activate the User Status add-on:

<div id="divUserStatus"></div>

<script>
    var userStatusParams = {
            containerID: 'divUserStatus'
    };

    gigya.gm.showUserStatusUI(userStatusParams);
</script>

Code Explanation

Step 1: Define the User Status add-on's div

<div id="divUserStatus"></div>

Step 2: Define the User Status add-on parameters

var userStatusParams = {
        containerID: 'divUserStatus'
};

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:

gigya.gm.showUserStatusUI(userStatusParams);

Like every Gigya API method, the gm.showUserStatusUI API method receives one parameter - parameters object, which is the object we have defined in Step 2 (learn more about Gigya's basics here). 

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.

Logged-out State

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: 

// This method is activated when page is loaded
function onLoad() {
    // register for login event
    gigya.socialize.addEventHandlers({
            onLogin: onLoginHandler
    });
 }
// onLogin Event handler  
function onLoginHandler(eventObj) {
	gigya.gm.showUserStatusUI(userStatusParams); // On login the User Status add-on is displayed (and automatically hidden on logout)
}

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:

var userStatusUA = new gigya.socialize.UserAction();

Change the default user action, by using the various UserAction member methods to set the object's properties. For example: 

userStatusUA.setTitle('$challengeTitle');
userStatusUA.setDescription('*** Challange title: $challengeTitle *** Level title: $levelTitle *** Challange description: $challengeDescription ***');
userStatusUA.addImage('$badgeURL');

Add the userAction object to the add-on's parameters:

var userStatusParams = {
        containerID: 'divUserStatus'
        userAction: userStatusUA,
};

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).