The Gigya service generates many different types of events driven by user interactions such as user login, button clicks, etc. This page details the events the Gigya service generates, and specifies how to define events handlers and register for events.

 

The Gigya service generates many different types of events driven by user interactions such as user login, button clicks, etc. Applications may register event handlers that listen for particular events and execute code when these events are received. 

This page details the events the Gigya service generates, and specifies how to define events handlers and register for events.

Events generated by the Gigya service are divided into two categories:

Event handlers are defined the same way for both types of events, but registering those event handlers for events is performed differently. Read the sections below for instructions on defining and registering event handlers for each type of event.

See Overriding the Default Event Map for an alternative way to register event handlers.

Global Application Events

Global application events are generated by the Gigya service whenever the event to which they refer occurs, regardless of the action that triggered the event. This is in contrast to plugin events, which are only fired by the specific plugin on which they were configured.

These are the available global application events:

onLogin Event Data

FieldTypeDescription
eventNamestringThe name of the event: 'login'.
sourcestringThe source plugin that generated this event. The value of this field is the name of the plugin's API method, in this case 'showLoginUI'.
Note: this field will not be available if the source of this event is not a plugin (e.g. if the source is a socialize.login API call).
contextobjectThe context object passed as a parameter to the plugin/method that triggered this event, or null if no object was passed.
loginModestringThe type of login:
  • standard - the user is logging into an existing account.
  • reAuth -  the user is proving ownership of an account by logging into it.
providerstringThe name of the provider that the user used in order to login (e.g. "Facebook"). Note: If this event is fired as a result of a socialize.notifyLogin call, i.e., the user was authenticated by your site, the provider field will be set to "site".
UIDstringThe User ID that should be used for login verification*.
UIDSignature stringThe signature that should be used for login verification, as described under the Validate the UID Signature in the Social Sign-On Process section.
userUser objectUser object with updated information for the current user.
signatureTimestamp stringThe GMT time of the response in UNIX time format (i.e. the number of seconds since Jan. 1st 1970). The time stamp should be used for login verification, as described under the Validate the UID Signature in the Social Sign-On Process section.
fullEventNamestringThis is occasionally returned as an internally used parameter.

* To learn more about login verification, please refer to the Validate the UID Signature in the Social Sign-On Process section in the Security page of the Developer's Guide.

Defining an Event Handler

An event handler is a function with the following signature: 

functionName(eventObj)
Where eventObj is an object that includes the following members:

 

The following code defines a simple event handler:

function DisplayEventMessage(eventObj) {
    alert("congrats on your " + eventObj.eventName);
}

Registering a Handler for an Event

Having defined an event handler, you can register it for an event using the accounts.addEventHandlers or socialize.addEventHandlers Gigya API methods. Like any other Gigya API method, addEventHandlers receives the params object (refer to the JavaScript API Basics page for more information).

The params object may include the following members (all optional):

 

The following code registers the DisplayEventMessage function, as defined above, for the user login event:

gigya.socialize.addEventHandlers({
	onLogin:DisplayEventMessage
});

 

This means that whenever the user logs in, the DisplayEventMessage function is called. It receives the eventObj parameter which includes the context object (passed to the accounts.socialLogin or socialize.login/socialize.showLoginUI methods) and the eventName (which, in this case is 'login').

The output of this example is:

 

Combined Event Handlers

You may register one event handler (one function) for several events, and you may register several events within one addEventHandlers method call .

Example: 

function displayEventMessage(eventObj) {
    alert(eventObj.context+' '+eventObj.eventName);
}

function confirmEventMessage(eventObj) {
    var r = confirm('Have you '+eventObj.eventName+ '?');
    if (r==true) {
        alert(eventObj.context);
	}
}

gigya.socialize.addEventHandlers({
    onLogin:displayEventMessage,
    onConnectionAdded:confirmEventMessage
});

gigya.socialize.addEventHandlers({
    onConnectionRemoved: displayEventMessage
});

The onLinkback Event

The onLinkback event is initiated whenever a linkback is detected.

Linkbacks are detected in the following cases:

 

The event includes the following fields (if available):

 

FieldTypeDescription
eventNamestringThe name of the event.
sourcestringThe source plugin that shared the link that led to the page.
contextobjectThe context object passed as a parameter to the method, or null if no object has been passed.
providerstringThe provider from which the linkback came.
cidstringThe context ID used for reports. Read more here.
shortCodestringThe original short URL code.
fullEventNamestringThis is occasionally returned as an internally used parameter.

 

Working Example

Please explore the following pages, where you may activate full working examples and then grab the code:

Screen-Set Events

The following events are triggered by RaaS Screen-Sets

For full details on these events, see accounts.showScreenSet.

You can add custom code to handle these events directly to the UI Builder. For more information, see UI Builder - JavaScript Parameters.  

Plugin Events

Each plugin defines events that it generates for specified situations.

The following events are generated by all plugins:

 In addition to the events generated by all plugins, the Share plugin generates the following event:

Defining an Event Handler

An event handler is a function with the following signature:

functionName(eventObj)
Where eventObj is an object whose members change depending on the specific event that was fired. 

For example, in an onSelectionDone event, eventObj will include the following members:

FieldTypeDescription
eventNamestringThe name of the event.
contextobjectThe context object passed as a parameter to the method, or null if no object has been passed.
friendsCollectionA collection of basic ? Friend objects, representing the list of the selected friends.
fullEventNamestringThis is occasionally returned as an internally used parameter.

 

The following properties of eventObj are available for all events:

 

Registering a Handler for an Event

Registration for plugin events is performed at the creation of the plugin.

The creation method for each plugin (e.g. socialize.showLoginUI) receives the following optional parameters (as fields of the params object):

Each of the above parameters may be assigned a value, which is the name of the event handler function to be called when the corresponding event occurs.

Overriding the Default Event Map

An Event Map is an object that maps Gigya events to methods, and it constitutes another way of registering for Gigya's events.

Gigya defines a default Event Map, which is used for Google Analytics integration and specifies which Gigya events will be tracked and how (for more information, see Google Analytics - The Default Tracking Behavior).

You may override or add to the default Event Map by setting the customEventMap parameter of the Global Conf object.

customEventMap Object Specification

RequiredField NameTypeDescription
RequiredeventMapArray of event mapping objects
An array of JSON objects. Each object specifies a certain event mapping. Each event mapping object may have the following fields:
  • events (required) - a comma separated list of Gigya event names. E.g. "onLogin, onLogout, onConnectionAdded".
Note:
  • You may remove the "on" from the event names,  e.g. "login, logout, connectionAdded".
  • You may use an asterisk "*" to specify all events.
  • sources (optional) - a comma separated list of Gigya event sources.
  • method  (optional) - the method that will be invoked when one of the events (specified in the events field) is fired. If not specified then the defaultMethod (see below) is used. 
  • args  (required) - an array of parameters to pass to the method. Each argument can be:
    • value
    • Function reference - the function signature should always be: string function(event)  i.e. receive the event object as a single parameter and return a string. For example: 
function (e) { 
    return (e.mode == 'reviews' ? 'Review Published' : 'Comment Published') 
}
  • String template - where fields from the event object may be embedded by preceding their name with $. For example: 'Followed via: $button.provider'
  • override (optional) - the default value is false. Setting this parameter to true will cause Gigya to stop processing additional maps that match the current event. You may use this to override the default mapping of certain events.
OptionaldefaultMethodmethod nameThe default method that will be invoked when one of the events (specified in the eventMap field) is fired.

Example: Defining a Custom Event Map

<script type="text/javascript" src="https://cdns.gigya.com/js/gigya.js?apiKey=INSERT-YOUR-APIKEY-HERE">
{
    customEventMap : {
        defaultMethod: defaultEventHandler,
        eventMap : [
            {
                events:"sendDone", 
                sources:"showShareUI,showShareBarUI,showFollowBarUI", 
                args:["provider", "Share Published", document.location.href] 
            },
            {
                events:"followClicked", 
                method:followHandler, 
                args:["provider", "Gigya Follow - button clicked", document.location.href]
            },
            {
                events:"reactionClicked,reactionUnclicked", 
                args:["Gigya Reaction Bar", "Button Clicked", "$reaction.text"] 
            },
            {
                events:"commentSubmitted", 
                method:commentHandler, 
                args:[
                    function (e) {return (e.mode == 'reviews' ? 'Gigya Reviews' : 'Gigya Comments') }, 
                    function (e) { return (e.mode == 'reviews' ? 'Review Published' : 'Comment Published') }, 
                    "stream: $streamID"
                ]
            }
        ]
    }
}
</script>

Available Events

Event NameTriggered By
onReactionClicked socialize.showReactionsBarUI
onReactionUnClicked socialize.showReactionsBarUI
onCommentEditedcomments.showCommentsUI
onCommentSubmittedcomments.showCommentsUI
onCommentVotedcomments.showCommentsUI
onLoginsocialize.loginsocialize.showLoginUI and various plugins
onLogoutsocialize.logout and various plugins
onConnectionAddedsocialize.addConnectionsocialize.showAddConnectionsUI and various plugins
onConnectionRemovedsocialize.removeConnectionsocialize.showAddConnectionsUI and various plugins

Note: You may remove the "on" prefix from the event names,  e.g., "login, logout, connectionAdded".