Gigya Job Openings

gm.showNotifications JS

Skip to end of metadata
Go to start of metadata

Description

 

Displays Gigya's Game Mechanics Notifications plugin. When a user unlocks a new level in any of his active challenges, the Notifications plugin appears. The plugin notifies the user of his latest achievement, and allows him to share this to his social networks.

 

Note: If you plan on integrating the Notifications plugin, we highly recommend reading the Notifications plugin page, which is a step-by-step guide for integrating the Notifications 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 header alerting the user of the new achievement
  • The badge of the newly unlocked level
  • The title of the new level
  • 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
  • A grayed out badge of the next level
  • A Share button

 

Plugin's Default Design

The following screenshot presents the default Notifications plugin:


  

Syntax

 

 

Parameters

The following table lists the available parameters:

   

RequiredNameTypeDescription
includeChallengesstringThe challenges for which the user is notified of a newly achieved level. The default value is '*', i.e. the Notifications plugin will pop up for all challenges that the site has to offer.
excludeChallengesstringThe challenges for which the user is not notified of a newly achieved level. The default value is '', i.e. no challenges that the site has to offer are excluded from the Notifications plugin.
userActionUserAction objectThe userAction object to be used for sharing the user's achievement. The UserAction object enfolds the newsfeed data, e.g. title, description, image.
Note: If the userAction object is not defined, the plugin uses a default userAction object, the content of which is suited to sharing the user's achievement.
closeTimeoutintegerThe time in milliseconds after which to hide the notification. The default value is '4000'. The value '0' means the notification does not close automatically, the user has to click the close button).
feedIDstringThe feedID to which to publish the userAction. The value default is 'null', in which case no auto publishing to the feed will take place.
shareParamsparamsThe object containing the parameters to pass to the socialize.showShareUI method.
debugModeBooleanWhen set to 'true' the plugin always displays itself, even if no new level has been reached, and should not hide itself until it is manually closed.
headerTemplatestringAn HTML template for the title of the notification dialog. The default text is: "Alert! New Level Reached". Accepts the following placeholders: $levelTitle, $levelDescription, $challengeTitle, $badgeURL, $challengeDescription, $pointsCurrent, $requiredAchievement, $achievementsToNextLevel, $nextLevelTitle, $nextLevelDescription, $nextLevelLockedBadgeURL, $nextLevelActionURL.
bodyTemplatestringAn HTML template for the body of the notification dialog. Accepts the following placeholders: $levelTitle, $levelDescription, $challengeTitle, $badgeURL, $challengeDescription, $pointsCurrent, $requiredAchievement, $achievementsToNextLevel, $nextLevelTitle, $nextLevelDescription, $nextLevelLockedBadgeURL, $nextLevelActionURL.
footerTemplatestringAn HTML template for the footer of the notification dialog. Accepts the following placeholders: $levelTitle, $levelDescription, $challengeTitle, $challengeDescription, $pointsCurrent, $requiredAchievement, $badgeURL, $achievementsToNextLevel, $nextLevelTitle, $nextLevelDescription, $nextLevelLockedBadgeURL, $nextLevelActionURL.
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 Game Mechanics Settings section.
dialogTemplatestringThe full template of the dialog, composed of the first three templates, and also a frame, margins, $shareButton, and $closeButton.
waitForNotificationsBooleanIndicates whether to notify users of a new achievement immediately after a default action (client side) is taken that rewards them with new level. The default value is 'true'.
 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.
onClosefunction refA reference to an event handler function that will be called when the plugin has been closed manually, by clicking the close (X) button.
onNewLevelfunction refA reference to an event handler function that will be called when a new level is reached.
onSendDonefunction refA reference to an event handler function that will be called when the process of publishing the newsfeed to all selected social networks has finished.
 

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.
 
 

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

  

onNewLevel 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.
challengestringThe challenge for which a new level has been achieved.

 

onSendDone 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.
providersstringA comma-separated list of social networks to which the newsfeed was successfully published.
userMessagestringThe textual message that the user entered in the editable text box of the Share plugin.
targetURLstringThe URL that was shared.
providerPostIDsarrayAn array of JSON objects representing the social network's post ID. Each object has the following fields:
  • provider - the social network provider (string). The optional values are: 'facebook','twitter','google','yahoo',or 'microsoft'. (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used). 
  • postID - the unique ID of the post (string).

 

 

Code Sample

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

notificationUA.setTitle('$challengeTitle - $levelTitle');
notificationUA.setDescription('Challenge title: $challengeTitle * Level title: $levelTitle * Challenge description: $challengeDescription');
notificationUA.addImage('$badgeURL');

var notificationParams = {
	    userAction: notificationUA
};

gigya.gm.showNotifications(notificationParams);

 

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.