Events

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

To handle events generated by Social Login, register your event handlers within the janrainWidgetOnload function. Each of the following event objects has an addHandler method that takes a single function reference as an argument. An event can have any number of handlers; each one is called when the event occurs.

The following examples show how to register event handlers. See the Janrain-Sample-Code Github repo for more. Here is a full example of using the Janrain event system to send data to a third-party analytics site such as Google Analytics.

The following fields in the janrain.events object define events

onModalWidgetReady

Fires when the modal window is ready.

onReturnExperienceFound

Occurs when a user returns to the site after signing in previously and the UI presents itself in a simplified form. It assumes the user plans to sign in with the same provider and user name.

An object containing the following fields:

  • returnProvider A string identifying the identity provider previously used. Possible values are documented here.
  • welcomeName The user’s name, as it appears in the “welcome back” message.

onProviderLoginStart

Occurs when the 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.

Error Codes

These error codes are specific to the Social Login solution and describe error states that arise from users attempting to sign in.

The error codes and descriptions are returned when the onProviderLoginError event occurs. The event returns an object containing the error details.

  • 100 Please enter your screen name
  • 101 Your OpenID must be a URL
  • 102 Your OpenID must be a URL
  • 103 Unable to contact your OpenID
  • 104 The OpenID you entered was not found
  • 105 There was an error looking up your OpenID
  • 106 Use a different OpenID server
  • 107 The URL you entered does not appear to be an OpenID
  • 108 Discovery failed for the OpenID you entered
  • 109 SSL verification failed for your OpenID
  • 132 Bad response from the OpenID server
  • 134 SSL verification failed for OpenID endpoint
  • 135 The FICAM authentication response verification failed
  • 136 The provider is not FICAM certified
  • 200 The token URL or xdReceiver has not been whitelisted
  • 201 The provider is not configured
  • 202 Error contacting the provider
  • 203 Invalid account
  • 204 The Provider does not support the requested scope (permissions)
  • 205 Error response from the provider

onProviderLoginSuccess

Occurs when the user successfully signs in.

onProviderLoginComplete

Occurs when the sign-in process is complete, whether successful or not.

onProviderLoginToken

Occurs when the user successfully signs in, and the tokenAction setting is true. 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 Social Login. You may encounter issues with these providers:

  • AOL
  • Disqus
  • Flickr
  • Foursquare
  • Linkedin
  • LiveJournal
  • Renren
  • Tumblr
  • Twitter
  • Verisign
  • WordPress
  • Yahoo!

This event is fired from inside the cancelLogin call.

onProviderLogoutStart

Fires when the user begins the sign-out process.

Object with a single field (indicating provider).

Functions

The Social Login solution supports a number of functions that allow you to interact with the solution after it has been launched. You can use these functions to affect the state of the UI or request information from the application.

An example of a popular sign-in function is to launch a sign-in flow for a UI that has been built without the use of the Dashboard. The UI’s design is coded into the webpage, and uses setProviderFlow or triggerFlow to initiate user authentication.

appendTokenParams

Adds parameter information to the query string on the token URL after the UI has loaded. This is useful for adding information not addressed in the sign-in process, such as appending an ID you get from a cookie to the end of the URL.

appendTokenParams

values are case-sensitive. When called repeatedly, the newer parameter value replaces the same parameter value set before it. Incrementally adding parameters to the token URL is not supported at this time.

debugDump

Logs a series of items to the JavaScript console. These include information about the browser, the web page, and the contents of the settings object. If debugDump is unable to locate a JavaScript console, it returns false. Otherwise it returns true.

getState

The getState function returns an object that describes the current state of Social Login. Most fields in the object correspond to fields in the settings object.

logoutFacebook

Attempts to sign the user out of Facebook, and notifies a callback URL when completed. Must contain a Facebook app ID. Note: Users must log in to Facebook using the same Facebook app at least once to use this function.

The modal functions are used to change the design and appearance of modal Social Login UI. These may also be set in the application’s Dashboard.

Close the UI.

Set the border width (in pixels).

Set the border color. The value is a web color expressed as a hexadecimal value. For example: #ffffff

Set the border opacity. The value is a number between 0 and 1.

Set the radius of corner curves. The value is expressed in degrees.

setBackplaneChannel

For Backplane-enabled tools. Sets the Backplane channel when the UI loads during user sign-in. If the channel isn’t loaded yet, the channel is set according to the configuration settings.

setNoReturnExperience

If true, the return experience form of the UI is bypassed and the user is presented with the usual, new visitor selection of providers. If false, the function does nothing.

setProviderFlow

Used for coding a custom-designed Social Login implementation. This allows a page element to begin the provider sign-in flow.

triggerFlow

Used when coding a custom-designed Social Login implementation. Triggers the sign-in flow for a provider.

version

String specifying API version.

widget

This widget object contains functions that manipulate the appearance of the UI after it is displayed.

widget.getWidth

Get width (in pixels).

widget.refresh

Used when the UI finds no identity associated with the user during sign-in. Instead of hanging on the “logging in” message, use refresh to allow a user to register or select another account.

widget.setActionText

The text that appears at the top of the UI. It is meant to describe the action that happens when a user signs in.

widget.setBackgroundColor

Set background color. The value is a web color expressed as a hexadecimal value (for example, #ffffff).

widget.setBorderColor

Set border color. The value is a web color expressed as a hexadecimal value (for example, #ffffff).

widget.setBorderRadius

Set the angle of rounding for button corners. The default value is 5.

widget.setButtonBorderColor

Set button border color. The value is a web color expressed as a hexadecimal value (for example, #ffffff).

widget.setButtonBorderRadius

Set radius of button corners.

widget.setFontColor

Set font color of action text. The value is a web color expressed as a hexadecimal value (for example, #ffffff).

widget.setFontFamily

Set font family for action text.

widget.setFontSize

Set the font size (in pixels).

widget.setFormat

Set the arrangement of provider buttons. Valid values are two columns, one column, or one row.

widget.setProviders

An array of provider-specifier strings. See Identity Providers.

widget.setProvidersPerPage

The highest number of provider buttons to display at one time.

widget.setWidth

The width (in pixels).

Settings

actionText

The text of the action.

backgroundColor

The background color, expressed as a hexadecimal value. For example: #ffffff 

borderColor

The color of the borders, expressed as a hexadecimal value. For example: #ffffff 

borderRadius

The radius of the curves of the corners.

buttonBackgroundStyle

The style of the button background.

buttonBorderColor

The color of the button borders, expressed as a hexadecimal value. For example: #ffffff 

buttonBorderRadius

The radius of the curves on the corners of the buttons.

fontColor

The font color for the action text, expressed as a hexadecimal value. For example: #ffffff 

fontFamily

Font family for the action text.

fontSize

Font size for the action text.

format

The button layout.

language

The language used for the Social Login Registration UI. The below language codes codes are supported:

CodeLanguage
arArabic
bgBulgarian
csCzech
daDanish
deGerman
elGreek (Modern)
enEnglish
esSpanish
fiFinnish
frFrench
heHebrew
hrCroatian
huHungarian
idIndonesian
itItalian
jaJapanese
koKorean
liLithuanian
nb-NONorwegian (Bokmål)
nl-BEDutch (Belgium/Flemish)
nl-NLDutch (Netherlands)
noNorwegian
poPolish
pt-BRPortuguese (Brazil)
pt-PTPortuguese (European/Continental/Portugal)
roRomanian
ruRussian
srSerbian
skSlovak
slSlovenian
svSwedish
thThai
ukUkrainian
zhChinese (Simplified)
zh-CHTChinese (Traditional)

modalState

If the UI is modal, this field is an object containing information that is specific to the modal UI.

modalState.borderColor

The border color, expressed as a hexadecimal value. For example: #ffffff 

modalState.borderOpacity

Border opacity.

modalState.borderRadius

Radius of border corners.

borderWidth

Border width.

modalState.orientation

Values are landscape or portrait. Set when the UI is viewed on a mobile device with orientation support.

Values are true or false. The default is true, which causes the UI to spawn new windows for identity provider sign-in. When set to false, this flag forces the UI to operate in a single-window mode appropriate for operation inside a WebView.

providers

Array of specifier strings for provider buttons.

providersPerPage

The number of provider buttons per UI page.

showAttribution

A boolean value. true shows the attribution text, false hides the attribution text.

type

The display type (modal or embedded).

width

The width of the UI (in pixels).

Cookies

Social Login uses cookies in several ways to help manage the user experience. Most of the cookies related to Social Login reside on the Janrain servers. Three cookies (or one, depending on your settings) reside on your website and both sets reside on the end users’ computers.

Customer Domain Cookies

These are the cookies that we place on your servers:

  • expected_tab- Used for the return experience. Has a five-year expiration.
  • login_tab - Used for the return experience. Has a one-day expiration.
  • welcome_info_name - Used for the return experience. Has a five-year expiration.

If the storageType setting is single cookie in your widget code, only one cookie will be placed on your server.

  • janrain_engage_login_data Combines the functionality and data of the three cookies previously listed into a single cookie.

Application Domain Cookies

These are the cookies we place on the Social Login application domain (such as realm.rpxnow.com):

  • expected_tab - Used for the return experience. Has a five-year expiration.
  • welcome_info - Used for the return experience. Has a five-year expiration.
  • welcome_info_name - Used for the return experience. Has a five-year expiration.
  • expected_user_input - Used for the return experience. Has a five-year expiration.
  • s_d_social - Used for the return experience. Has a one-week expiration.
  • origin_url - Used for error handling. Has a five-year expiration.
  • _accelerator_session_id - Used for login processing. Session-based, this cookie is deleted when the user quits their browser.
Scroll ↓