This guide explains how to leverage Gigya's plugins to acquire new site users, and log in returning site users. We will guide you on how to integrate these plugins with Social Login and Registration-as-a-Service.
Gigya's sharing and social interaction plugins embed an inner 'Add Connection' plugin:
|Share Plugin||Activity Feed Plugin*||Comments Plugin||Reactions Plugin|
The default behavior when a user clicks on one of the social network buttons within one of these plugins:
- If the user is already logged-in, clicking on a social network button will add a connection and an additional social identity to the user's current Login identity. Gigya will link between the two identities. The connection and linking is consistent, and will be available for the user the next time he logs in.
- If the user is not logged-in, clicking on a social network button will create a 'temporary' user. A temporary user in Gigya platform is a user with a temporary identity. You may look at it as a guest user, a user that is not registered in Gigya's platform .
Note: in both cases, when the operation finishes successfully, Gigya will fire the onConnectionAdded event.
* This feature or API is being deprecated and should not be used in your implementation. If it already exists in your implementation, you should locate and remove it from your code by December 1st, 2016.
This guide offers an alternative behavior for the case of a non logged-in user. We offer to login the user, and in case he is a new user, you may suggest registration.
Follow the steps below to implement this use case.
Best Practice Implementation Steps
Step 1: Register an Event Handler to the Global onLogin Event
An effect of the previous step is that each time a non-logged-in user clicks on a social network button within one of the plugins, the global onLogin event will be fired.
Make sure to listen to this event, if you want to handle the user's login in your site.
Registering a handler for a global event is done using the socialize.addEventHandlers API method (if you implement RaaS, then use accounts.addEventHandlers). For example:
Calling the addEventHandler method should be done on page load (before the plugins are loaded). The onLoginHandler method in the example, handles the onLogin event. The implementation is explained in step 4 ahead.
In the Login demo page you may find a complete working example that handles the onLogin event.
Step 2: Define a Context for Each Plugin
All of the Gigya plugins accept a context object (as member of the 'params' object). The context object is a developer custom object that will be passed back unchanged to your application through the plugin's event handlers as one of the fields of the eventObj . For example, in the code example above, eventObj.context contains the context that was passed to the plugin that initiated the onLogin event.
In our use case, we are interested in the onLogin event handler. Since we may have several sources (plugins) that initiate the onLogin event, we will use the context object to distinguish between the different sources.
Add to the params of each plugin a context parameter. As a value of the context parameter you can use different strings, identifying the different plugins (e.g. "CommentsPlugin", "SharePlugin", etc).
Step 3: Handle Global onLogin Event only if Initiated by Relevant Plugins
Now we can handle the onLogin event, and decide per plugin source whether or not to push registration. For example:
- In case of Activity Feed Plugin, Login Plugin, Add Connections Plugin: execute the login flow right away.
- In case of Share Plugin, Reactions Plugin: wait for the onSendDone event and only then execute the login flow. The motivation for postponing the login flow is that both plugins use a pop-up dialog. We want the user to first finish his sharing process. Only after the dialog closes, we will proceed to the login flow that may include redirecting or popping-up a registration form.
- In case of Comments Plugin: based on your preference; either execute the login flow right away or wait for the onCommentSubmited event.
In all cases, implement the login flow as described in the Login Implementation guide, starting with Step 3 (verifying signature) of the flow.
Step 4: Handle Relevant Event per Plugin
As mentioned in the previous step, for some plugins we need to initiate the login flow as a result of an alternative event (not the onLogin event). Thus we need to register and handle the relevant event. For example, for the Share Plugin, we need to register and handle the onSendDone event.
We would like to initiate the login flow from the onSendDone event handler. There is a small catch here - in the onLogin event data, we receive the User Object and use it in the login flow; we don't receive the User Object in the onSendDone event. The solution is to call the socialize.getUserInfo method, as shown in the following code sample:
- Important - please note that we have passed the signIDs parameter to the socialize.getUserInfo method. This will make sure that the User object passed to the callback method will be signed by Gigya.
- In the userInfoCallback method, response.user holds the User object. Use this object as part of the implementation of the login flow as described in the Login Implementation guide, starting with Step 3 (verifying signature) of the flow.
- The implementation for the Reactions Plugin is exactly the same.
Putting it all Together - Running Example
The following code example puts all the pieces together:
The Example Code