Gigya Job Openings

gm.showLeaderboardUI JS

Skip to end of metadata
Go to start of metadata

Description

 

Displays Gigya's Game Mechanics Leaderboard plugin. The plugin enables partners to display the users with the highest achievements in a specific challenge. The leaderboard will only display users who have a name, email or provider. 

 

Note: If you plan on integrating the Leaderboard plugin, we highly recommend reading the Leaderboard Plugin page, which is a step-by-step guide for integrating the Leaderboard plugin. In addition, you can read the Game Mechanics Guide for more information. Game Mechanics is a premium platform that requires separate activation. If Game Mechanics is not part of your site package please contact your Gigya Customer Engagement Executive 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.

 

The plugin presents:

  • A display of the highest ranking users, with their ranks, photos, and names (only users who have a name, email or provider). Users with the same number of points are ranked the same.
  • A medal icon for each of the top three users
  • A popup that opens when the user clicks one of the ranks, photos or names

 

Plugin's Default Design

The following screenshot presents the default Leaderboard plugin:


  

Syntax

 

 

Parameters

The following table lists the available parameters:

   

RequiredNameTypeDescription
containerIDstringAn ID of a <div> element on the page in which you want to display the plugin.
widthintegerDetermines the width in pixels of the plugin. The default value is 300 pixels.
challengestringThe challenge for which to display the Leaderboard plugin. The default value is '_default', representing the default challenge.
periodstringThe period for which to display the Leaderboard plugin. The valid values for this parameter are:
  • 'all' - displays the all-time highest ranking users for the specific challenge
  • '7days' (default) - displays the highest ranking users from the past seven days for the specific challenge
totalCountintegerThe total number of users to display in the Leaderboard plugin. The default value is 12, the maximum is 36.
friendsCountintegerThe maximum number of friends to display in the Leaderboard plugin. The default value is 3.
Note: Fewer friends will be displayed if the user's friends who are active in the challenge are less than the specified value.
includeSelfBooleanDetermines whether to display the current user in the Leaderboard plugin. The default value is 'true'.
userTemplatestringA template of the leaderboard display. 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.
You may use the following placeholders: $UID, $name, $rank, $points, $photo, $top3Icon, $friendIcon. The last two placeholders will be filled if the condition is true (is top3, is friend).
detailsTemplatestringA template for the body of the details popup. You may use the following placeholders: $UID, $name, $rank, $points, $photo, $challengeBadge, $otherChallengesBadges.
actionAttributesJSON objectThis parameter is used to display the Leaderboard plugin according to a specific attribute, for example you can show the plugin only for the top users on the "Glee" page of a site, instead of the top users on the entire site. The action attribute is comprised of a single set of a key (category) and a value, e.g., {"tv-show":"glee"}. In order to use this option, you need to give action attributes to actions the user may perform on the site, such as sharing or commenting, and these action attributes will be used to filter. Read more here.
 Events Registration Parameters 
onLoadfunction refA reference to an event handler function that will be called when the plugin has finished drawing itself.
onErrorfunction refA reference to an event handler function that will be called when an error occurs.
 

Plugin Events

An Event Handler is a JavaScript function with the following signature:

functionName(eventObj)

The single argument, eventObj, contains information about the event and has different fields for different events.

The following tables specify the list of fields available in the eventObj for each event:

onLoad Event Data

FieldTypeDescription
   
eventName string The name of the event.
source string The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g., 'showLoginUI', 'showCommentsUI', etc.
contextobject Any user defined data passed as a value of the context parameter by the application to the API method, it will be returned as an accessible property in the response. If no context parameter was passed, it will not be returned.

onError Event Data

FieldTypeDescription
   
eventName string The name of the event.
source string The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g., 'showLoginUI', 'showCommentsUI', etc.
contextobject Any user defined data passed as a value of the context parameter by the application to the API method, it will be returned as an accessible property in the response. If no context parameter was passed, it will not be returned.
errorCodeintegerThe result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the Error Codes table.
errorMessagestringA short textual description of an error, associated with the errorCode, for logging purposes.
errorDetailsstringThis field will contain the exception info, if available.
 

 

Code Sample

<div id="divLeaderboard"></div>
<script>
    var leaderboardParams = {
        containerID: 'divLeaderboard'
    }
    gigya.services.gm.showLeaderboardUI(leaderboardParams);
</script>

 

Notes:

  • This sample is not meant to be fully functional code. For brevity's sake, only the code required for demonstrating the API call itself is presented.
  • To run the code on your own domain, add your Gigya API key to the gigya.js URL. A Gigya API key can be obtained on the Site Dashboard page on Gigya's website. Please make sure that the domain from which you are loading the page is the same domain name that you used for generating the API key.
  • In some cases it is necessary to connect/login the user to a provider ? prior to calling the API method. You can learn more in the Social Login guide.

In the Game Mechanics Plugins demo you will find a complete working example that uses all the Game Mechanics plugins API methods. You may view the code, run it and view the outcome.