Events

Skip to end of metadata
Go to start of metadata

 

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:

  • Global Application Events - Events that are initiated by the application, such as when a user logs in.
  • Plugin Events - Events that are initiated by a plugin, such as when a user clicks the "OK" button of a plugin.

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

Note: The UID string must be encoded using the encodeURIComponent() function before sending it from your client to your server.

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.

* 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:
  • eventName property - the name of the event fired. May be: 'login', 'logout', 'connectionAdded' or 'connectionRemoved' respectively.
  • context property - will be available only if passed as parameter to the plugin/method that triggered the specific event.

 

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

  • onLogin - The value assigned to this parameter is a name of an Event Handler function that will be called when the user is successfully authenticated by Gigya. 
  • onLogout - The value assigned to this parameter is a name of an Event Handler function that will be called when the user logs out.
  • onConnectionAdded - The value assigned to this parameter is a name of an Event Handler function that will be called when the user is successfully connected to a provider.
  • onConnectionRemoved - The value assigned to this parameter is a name of an Event Handler function that will be called when the user disconnects from a provider.
  • onLinkback - The value assigned to this parameter is a name of an Event Handler function that will be called when a linkback is detected.
  • callback - A reference to a callback function that will be called, along with the results of the operation when the operation completes.
  • context - A developer-created object that will be passed back unchanged to the application as one of the fields in the response object.

 

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:

  • A linkback from shortened URLs. These are reported by the server, and an extra parameter (hash or querystring) is added to the URL to let the Gigya JS SDK know that it was reported.
  • Facebook like or send buttons referral traffic. In these cases Facebook adds a context parameter to the URL that was passed by our like button.
  • When the referrer is from a list of domains the client detects as linkbacks.
  • From AddressBarShares - when trackAddressBarShares is set to 'true' (see the global Conf object). 

 

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.

 

Working Example

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

Plugin Events

Each plugin defines events that it generates for specified situations.

The following events are generated by all plugins:

  • onLoad - When the plugin has finished drawing itself.
  • onError - If an error occurs.
  • onClose - When the plugin is closed. Plugins may be "closed" in either of the following ways:
    • If the plugin is opened as a popup dialog, an "X" button appears. Clicking the "X" button closes the plugin and an onClose event is generated.
    • In case the plugin has an "OK" and/or "Cancel" button, clicking either buttons closes the plugin and an onClose event is generated.

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

  • onSendDone - This event is triggered when the process of publishing the newsfeed to all selected social networks has finished. The event data includes the list of the social networks to which the newsfeed was successfully published.

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.

 

The following properties of eventObj are available for all events:

  • eventName: the name of the event fired.
  • context: available only if passed as a parameter to the plugin/method that triggered the specific event (see the next section for more details).

 

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

  • onLoad
  • onError
  • onClose

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="http://cdn.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".