Registration JavaScript API: Events

Registration can provide detailed information on user and application state using JavaScript 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 add a handler for an event, use the addHandler method. All events are located within the janrain.events namespace, and handlers should be added within the janrainCaptureWidgetOnLoad function before the janrain.capture.ui.start argument, which loads the Registration UI. For example:


function janrainCaptureWidgetOnLoad(){
  janrain.events.onCaptureLoginSuccess.addHandler(function(event){
    // do stuff
  }
  janrain.capture.ui.start();
}

Event Types

Depending on the event type, different information is passed to the event handler function. 

Note: Some events do not conform to these types specifically and are documented in detail where they are defined.

Transaction

These events contain information about the latest transaction between the Registration widget and the Registration service. Information included consists of the transaction ID, status, status message, flow name and version, as well as the screen the widget will render next (only when renders is true). Sometimes includes the access token. Example event:


{
  accessToken:"qazxde45rtgbnkiug",
  action:"profile",
  flow:"standard",
  renders:true
  screen:"editProfile",
  status:"success",
  statusMessage:"profileFound",
  transactionId:"fufk86ggk1uqwpfnilytfy2dv2lfsa3m5p2qx50y",
  version:"20160406190849202817",
}

Mail

These events contain information about the email that was just sent. Example event:


{
  to:"user_email@example.com",
  from:"noreply@myorg.com",
  message:"Email sent!"
}

Social

All of these types of events contain the name of the social identity provider being used. Example event:


{
  provider:"facebook"
}

Render

These events contain the flow at the time of rendering, as well as the screen being rendered. If renderingBuiltInScreen is false, the currently-rendered screen will be located in the screen property. If renderingBuiltInScreen is true, the currently-rendered screen will be located in the builtInScreenRenderedproperty. Example event:


{
  flow:{...},
  renderingBuiltInScreen:false,
  screen:"editProfile"
}
Example event with builtInScreenRendered:
{
  flow:{...},
  renderingBuiltInScreen:true,
  screen:"editProfile",
  builtInScreenRendered:"accessDenied"
}

Screen

These events contain the name of the screen being displayed.


{
  screen:"editProfile"
}

Access Token

These events contain the access token that was just returned from the Registration service. Example event:


{
  accessToken:"qazxde45rtgbnkiug"
}

Void

These events don’t contain any data, but are still useful for enriching the user experience.

onCaptureAccessDenied

Type: Void

Fires when the user attempts to access information but is not yet authorized. For example, attempting to navigate to their profile without logging in.

onCaptureAccountDeactivateFailed

Type: Transaction

Fires when an error occurs while a user is attempting to deactivate their account.

onCaptureAccountDeactivateSuccess

Type: Transaction

Fires after a user has successfully deactivated their account.

onCaptureAccountReactivateFailed

Type: Transaction

Fires when an error occurs while a user is attempting to reactivate their account.

onCaptureAccountReactivateSuccess

Type: Transaction

Fires after a user has successfully reactivated their account.

onCaptureBackplaneInitFailed

Type: Void

Fires if Backplane has not successfully initialized one minute after the Registration widget initially loads.

onCaptureBackplaneReady

Type: Void

Fires when the Backplane server signals that it is ready to run.

onCaptureContentChange

Type: Void

Fires when the content on a screen is changed. Various actions can fire this event, such as rendering a screen, displaying a validation message, adding or removing fields, and so forth.

onCaptureControlFailed

Type: Transaction

Fires when a control action fails. Control actions are small pieces of logic that can be used to trigger events (such as sending emails). See activateCaptureControl.

onCaptureControlSuccess

Type: Transaction

Fires when a control action succeeds. Control actions are small pieces of logic that can be used to trigger events (such as sending emails). See activateCaptureControl.

onCaptureEmailSent

Type: Mail

Fires when an email was sent to the user. This event fires for all email types sent through the Janrain Registration service (registration, verification, and so on).

onCaptureEmailVerificationFailed

Type: Transaction

Fires when the email verification process has failed. Usually this happens when the user has waited too long to click the verification link in their email.

onCaptureEmailVerificationSuccess

Type: Transaction

Fires when a user successfully verifies their email address.

onCaptureError

Fires when an unexpected error returns from the Registration service. The contents of this event vary depending on the nature of the error.

onCaptureExpiredToken

Type: Void

Fires when a transaction between the Registration widget and service fails due to an expired access token.

onCaptureFederateLogin

Type: Transaction

On a site with SSO enabled, fires after a user successfully authenticates on the first site he or she visits and also any time the user is automatically logged in to another site he or she visits within that SSO segment. Both onCaptureLoginSuccess and onCaptureFederateLogin will fire with the ssoImplicitLogin property set to true to identify the login event with SSO.

onCaptureFederateNoLogin

Type: Transaction

On a site with SSO enabled, fires when SSO attempts to automatically log a user in but is not successful.

onCaptureFederateRefreshedToken

Type: Access Token

Fires when a new session is created by SSO. This can indicate that the session was created by the user visiting another site with the federated segment, or that the session was refreshed so that it would not expire.

onCaptureFieldsChanged

Fires upon submission of a form if the field values have changed. The event consists of an object with keys matching the field names changed. The value of each key contains both the new and old values. Example event:


{
  nameOfSomeFieldThatChanged:{
    newValue:"This value was changed!",
    oldValue:"This is the original value."
  }
}

onCaptureForgotPasswordCodeFailed

Type: Transaction

Fires when the user was unable to exchange the forgot password code and reset their password.

onCaptureForgotPasswordCodeSuccess

Type: Transaction

Fires when a user successfully exchanges the forgot password code, but before they change their password.

onCaptureFormError

Fires when a validation error occurs after submitting a form. The event consists of an object enumerating the errors. Example event:


{
  someValidation:"There was an error."
}

onCaptureInvalidToken

Type: Void

Fires when the access token supplied to the Registration service was malformed.

onCaptureLinkAccountError

Fires when an error occurs while attempting to link a social account to a user profile. Example event:


{
  message:"Unable to link accounts.",
  provider:"facebook"
}

onCaptureLoginFailed

Type: Transaction

Fires when a user fails to log in to the Registration service.

onCaptureLoginStart

Fires when the login screen is first shown to the user. The event consists of the screen name and action (either traditionalSignin or socialSignin). Example event:


{
  action:"socialSignin",
  screen:"socialLoginScreen"
}

onCaptureLoginSuccess

Fires when the user has successfully logged in. On initial login, event handlers will receive an Access Token event. On post-login and session refresh event handlers will receive a Transaction event.

onCaptureModalReady

Type: Void

Fires when a modal screen is ready to be shown, before onCaptureScreenShow.

onCapturePhotoUploadSuccess

Type: Void

Fires after a user has successfully uploaded a profile image.

onCapturePostLoginScreen

Type: Transaction

Fires when a post-login screen is displayed to the user. The event only includes the access token on post-login confirmation screens.

onCaptureProfileCookieSet

Fires when the Registration widget sets the janrainCaptureProfileData localStorage key with the user data specified by the flow. The event consists of an object containing the user data. Example event:


{
  firstName:"Alex",
  lastName:"Smith"
}

onCaptureProfileLink

Fires when a user successfully links an additional social provider account to their current user profile. The event consists of the provider of the new account as well as the new user data. Example event:


{
  provider:"facebook",
  authProfile:{...}
}

onCaptureProfileSaveFailed

Type: Transaction

Fires when an error occurs while attempting to save the user’s profile.

onCaptureProfileSaveSuccess

Type: Transaction

Fires when changes to a user profile are saved successfully.

onCaptureProfileUnlink

Type: Social

Fires when a user successfully unlinks a social account from their current user profile.

onCaptureRegistrationFailed

Type: Transaction

Fires when an error occurs during a traditional registration.

onCaptureRegistrationStart

Fires when the registration screen is first shown to the user. The event consists of the screen name and action (either traditionalRegister or socialRegister). Example event:


{
  action:"socialRegister",
  screen:"socialRegisterScreen"
}

onCaptureRegistrationSuccess

Type: Transaction

Fires when a user has successfully registered.

onCaptureRegistrationSuccessNoLogin

Type: Transaction

Fires when a user has successfully registered, but there are post-login screens to complete before login is considered complete. The event will not contain an access token.

onCaptureRenderComplete

Type: Render

Fires when the Registration widget has finished initially rendering on the page. This event is not triggered upon subsequent screen changes.

onCaptureRenderStart

Fires before the Registration widget begins rendering any changes to the page. The event consists of the entire flow at the time the event is fired.

onCaptureSaveFailed

Type: Transaction

Fires whenever an error occurs while attempting to save profile data to the Registration service.

onCaptureSaveSuccess

Type: Transaction

Fires whenever data is successfully saved to the Registration service.

onCaptureScreenShow

Type: Screen

Fires when the Registration widget displays a screen to the user.

onCaptureServerValidationFailed

Fires when validation fails after submitting a form and the result is being rendered for the user. The event consists of the error messages from the Registration service. Example event:


{
  errors:[
    "Invalid input"
  ]
}

onCaptureSessionCreated

Type: Access Token

Fires when a new access token is issued by the Registration service.

onCaptureSessionEnded

Type: Void

Fires when the user logs out and the user’s access token is invalidated.

onCaptureSessionFound

Type: Access Token

Fires when an access token is found on page load.

onCaptureSessionNotFound

Type: Void

Fires when no access token is found on page load.

onCaptureTransactionTimeout

Fires when a transaction with the Registration service times out. See janrain.settings.capture.transactionTimeout for information on how to set the timeout threshold. Event consists of the transaction ID that timed out. Example event:


{
  transactionId:"fufk86ggk1uqwpfnilytfy2dv2lfsa3m5p2qx50y"
}

onCaptureValidationComplete

Fires after validating a form before submitting to the Registration service. The event consists of an array of the fields that contain errors. Example event:


{
  fieldsWithError:[
    "firstName",
    "emailAddress"
  ]
}

onCaptureValidationFailed

Fires when a field fails validation. Event consists of information about the field and failed validation. Example event:


{
  field:"emailAddress",
  message:"Email address is invalid",
  parentDiv:Element
}

onCaptureValidationSuccess

Fires when a field passes validation. Event consists of the field name. Example event:


{
  field:Element
}

onModalClose

Type: Void

Fires when the Registration widget modal closes.

onModalOpen

Type: Void

Fires when the Registration widget modal opens.

onProviderLoginCancel

Type: Social

Fires when the user cancels during social authentication.

onProviderLoginComplete

Type: Social

Fires when the Janrain widget has successfully retrieved the user’s profile information from the social identity provider.

onProviderLoginError

Type: Social

Fires when an error occurs during social authentication. Handler functions are called with the JSON error response from the Social Login service.

onProviderLoginStart

Type: Social

Fires when a user clicks a social identity provider button and initiates sign-in.

onProviderLoginSuccess

Type: Social

Fires when the user successfully authenticates with the social identity provider.

onProviderLogoutComplete

Type: Social

Fires once the user has successfully logged out.

onProviderLogoutStart

Type: Social

Fires when the user clicks the logout button in the Registration widget.