Skip to main content
IAM vs. CIAM CIAM Buyer's Guide Contact Us
Janrain respects your privacy and will treat the personal data you choose to share with us in accordance with our privacy policy.

Events, Customization and Client-Side Ajaxy Fun with the New Janrain Engage Social Login Widget

By Katie Keenan | Posted on August 31, 2011

Blog Banner

Now that I can finally beat the Janrain back-end software engineer’s at Foosball, I am now getting the respect that us front-end JavaScript web developers and engineers deserve. Maybe not in the realm of programming, but hey, we have to start somewhere.

In all seriousness, JavaScript API’s are getting smarter and are providing some serious options and flexibility to web developers. With the use of a JavaScript API you can get some pretty impressive features implemented on your site very quickly. Our new Janrain Engage social login widget allows you to do just that, and in fact, you can easily get a fully customized social login widget implemented on your site in no time at all. The new Janrain Engage social login widget has something for everyone with improved performance that your IT guys will enjoy, to awesome analytical tracking abilities that your marketing team is going to love, and of course, an improved end-user experience that your customers and users will appreciate. So enough of that, let’s get into the nerdy cool stuff.

Performance Improvements

We completely re-engineered from the ground up, allowing the new Janrain Engage social login widget to have dramatically faster load and execution times. Performance is greatly increased by using asynchronous loading and a host of optimizations including some HTML5, CSS3 (so fewer images to load), and improved CDN caching mechanisms (and yes, backwards compatible to IE6). International load times are as much as seven times faster. Check out our new Technical Paper on our Social Login Widget Performace Analysis.

While performance has greatly increased, so have the number of helpful features including:

  • a new event model system
  • multi-site return experience
  • expanded JavaScript API
  • optional client-side authentication (meaning no redirect allowing for an ajax-like login experience)
  • improved mobile phone support
  • a number of new ways to customize the look and feel of the social login widget

Event Model

Capture and react to a large number of custom Janrain Engage events broadcast at every step of the login authentication process. While the sky’s the limit, events are immediately useful for 3rd party analytics and custom UI tweaks. With the use of simple JavaScript handlers you can send detailed analytical data to any 3rd party analytical package every time an event is fired. Here is example JavaScript code for using Google Analytics to track the event fired when a provider login is completed (More detailed information about _trackEvent can be found in Google’s Event Tracker Guide):{
_trackEvent('Login','loginComplete','providerName', response.provider);

The new event model allows customization at nearly every step of the login process. For example, while the built in return experience is already a perfect fit for the majority of our customers, creating a completely custom return experience using the information broadcast by the onReturnExperienceFound event is trivial. In this example, we simply replace the html of a div with a welcome back message that includes the name of the user when a return experience is found.{
$("#someDivOnYourPage").html("Welcome back " +;

There are three types of events.

  • Global events – these are events that are available on a global scale.
  • Widget/Object specific events – these are events that are available per our Janrain widgets and objects, such as the modal window and auth widget. Some of these events are public while others are private.
  • Internal events

The events are available when the Janrain Engage social login widget is loaded and ready. The easiest way to know if the widget is ready, is to use the janrainWidgetOnload callback function. If this function is defined on your page then it is called once the widget is loaded and ready to go. This is similar to other initialization and callback functions found in other javascript API’s. Event handlers can be added to the janrainWidgetOnload function and when the widget is done loading the janrainWidgetOnload function will be called causing those event handlers to be registered. For example you might do something like this:

function janrainWidgetOnload(){{
// code would be placed here that would be executed every time the
// onProviderLoginStart event is fired. For instance, you may
// want to integrate a 3rd party analytics package that would track every
// time this event is fired. (Marketing people love this stuff!!!)

There is no limit to the number of handlers that can be added to an event. Every time an event is called, all the handlers that have been added to that event will be called. The following global events are currently available with many new events coming in the near future.
returns: customizable properties as json
returns: error and status
returns: returnProvider and welcomeName


We offer several options for customizing the new Janrain Engage social login widget. Using our new dashboard, you can make customizations using a web interface and then save those settings to our servers. For more information on widget customization, see Kevin Long’s blog post on our new social login widget. Customizations can also be made on the client side by adding settings in JavaScript. For example, the code below will add a custom action text (the text right above the provider buttons), set the width of the widget to 400 pixels and will display four provider buttons per page. There are over 25 custom settings that can be set in your code using JavaScript.

Fully Custom UI

For custom UIs, you will need to set janrain.settings.custom to true. By turning on the custom feature, rendering of the widget will be left to you. There are two public “helper” functions available to help with custom UIs; setProviderFlow and triggerFlow.

janrain.engage.signin.setProviderFlow(element, provider) : to use setProviderFlow, you only need to pass in an element and a provider name. Any element that has an onclick event will work, for example a div or a button.

janrain.engage.signin.triggerFlow(provider) : can be added directly to an onclick event of an element, or within a function that is called when an onclick event is fired. (If the function is used without an onclick event being fired directly by a user clicking on something then most pop-up blockers will block the popup window. So don’t do that!).

Client-side Authentication

And now introducing client-side authentication, kinda. Implemented in the way I describe below, you get what looks and feels like client-side authentication with the security and robustness of server-side authentication (because the important parts are really happening on the sever-side). You can get that cool web 2.0 ajaxy thing going on. We do it with single use client-side bearer tokens passed over SSL that are exchanged for a long-lived token along with some server-side security fail-safes. It may sound complicated, but no worries, we handle all the scary details for you.

To use the client-side feature, you just turn it on in the settings with janrain.settings.tokenAction = ‘event’, and then add a handler to the onProviderLoginToken event. In that handler you can then pass the long-lived token to your server using ajax. That page (which could be the same as what you defined before for your tokenUrl), can then make server-to-server API calls, like auth_info, using our Restful API which would return the profile information of the end-user that just had a successf

Popular Posts

About the author

Katie Keenan

Katie Keenan

Interactive Marketing Manager

A true geek at heart, Katie works behind the scenes on Janrain's website and social media strategy as the interactive marketing manager. Katie has more than 10 years of experience building websites and managing online communities in media, retail, technology, law and the nonprofit sector. Her passion: to get rid of the clutter and help to improve efficiencies across the web to spark online engagement.

View all posts by Katie Keenan