Events

The Social Sign-In Widget supports client-side handling of a number of events. These are useful for making customizations based information gathered at run time, and for using third-party analytics to track specific events.

Registering Event Handlers ¶

To handle events generated by the Social Sign-In Widget, define the function janrainWidgetOnLoad. The widget will call this function when it is loaded, making it a good place to register event handlers. Each event object provides an addHandler function for this purpose.

Supported Events ¶

The following fields in the janrain.events object define events:

Object	Description	Event Handler
`onReturnExperienceFound`	Occurs when a user returns to the site after signing in previously, and the widget presents itself in a simplified form. It assumes the user plans to sign in with the same provider and user name. Useful for customizing the appearance of the widget in return experience mode.	An object containing the following fields: `returnProvider`. A string identifying the Identity Provider previously used. Possible values are documented in Identity Providers. `welcomeName`. The user’s name, as it appears in the “welcome back” message.
`onProviderLoginStart`	Occurs when user clicks the provider or return experience button, beginning the sign-in process.	Object with single field indicating provider chosen.
`onProviderLoginError`	Occurs when encountering an error during the sign-in process.	An object containing the following fields: `err`Error object. `code`. Numeric error code `msg`. Descriptive error string. `origin`. Origin of sign-in error. `stat`. Status message.
`onProviderLoginSuccess`	Occurs when the user successfully signs in.	None.
`onProviderLoginComplete`	Occurs when the sign-in process is complete, whether successful or not.	None.
`onProviderLoginToken`	Occurs when the user successfully signs in, and the `tokenAction` setting is true. See Client-Side Authentication.	A response object containing a single `token` field; this contains the one-time token.
`onProviderLoginCancel`	Occurs when the end user clicks the Cancel or No Thanks button on the login screen. Some Identity Providers do not include a Cancel button or their cancel message does not get passed to the Social Sign-in Widget. You may encounter issues with these providers: AOL, Yahoo, Flickr, Foursquare, Linkedin, Twitter, Verisign, LiveJournal, Disqus, Renren, Tumblr, WordPress.	This event is fired from inside the `cancelLogin` call.
`onProviderLogoutStart`	Fires when the user begins the sign out process.	Object with single field indicating provider.

Each of the above event objects has an addHandler method that takes a single function reference as an argument, designating that function as a handler for the event. An event can have any number of handlers; every handler for an event is called when the event occurs. In the following example, janrainWidgetOnLoad is used to register event handlers that trace sign-in events using console.log.

function janrainWidgetOnLoad() {
    janrain.events.onProviderLoginStart.addHandler(function() {
        console.log("Login Start!");
    });
    janrain.events.onProviderLoginComplete.addHandler(function() {
        console.log("Login Complete!");
    });
    janrain.events.onProviderLoginError.addHandler(function(response) {
        console.log("Login Error!");
        console.log(response.err.code);
        console.log(response.err.msg);
        console.log(response.origin);
        console.log(response.stat);
    });
        janrain.events.onProviderLoginSuccess.addHandler(function(something) {
        log("Login Succcess!");
    });
    janrain.events.onReturnExperienceFound.addHandler(
      function(response) {
        console.log("Return Experience Found!");
        console.log(response.returnProvider);
        console.log(response.welcomeName);
    });

}

Using Events with Janrain Engage ¶

Event handlers are useful for customizations that occur when the widget is in action.

Run-Time Customizations ¶

The following example adds a message to the parent page when a returning user signs in.

janrain.events.onReturnExperienceFound.addHandler(function(response) {
    document.getElementById('greeting').innerHTML = "Welcome back " + response.name;
}

Using Events with Third Party Analytics ¶

Events are useful with third-party analytics, and can be used to send detailed data as triggered. The following event handler uses Google Analytics to track sign-ins.

janrain.events.onProviderLoginComplete.addHandler(function(response) {
     _trackEvent('Login', 'loginComplete', 'providerName', response.provider);
});

For more information on event tracking with third-party analytics, refer to the Third-Party Analytics page.

Client-Side Authentication ¶

When you set up the Social Sign-in Widget, authentication is usually achieved by redirecting to a page that makes the auth_info RESTful call. This refreshes the page. If you use the Events API instead, the authentication process can complete without using a refresh. See Client-Side Authentication for details on this method.