Default Registration Experience
This section shows examples of the code Janrain provides to customers to implement the default Janrain configuration.
The following sections provide:
- Screenshots of rendered screens and transactional emails.
- Descriptions of how each screen relates to the HTML in the reference implementation files.
- Diagrams depicting the flow of the user experience.
Note: All of the following screens and emails are available to Enterprise-level customers, but only a subset of the screens (marked with the badge below) is available to Social Data customers.
Social DataScreens Overview
Screens exist in two parts:
- Server-side configurations
- Client-side HTML
In order for a screen to render, both parts must be in place.
Server-side, the screen’s relationships to other screens and how it is displayed by default are defined in a configuration file. This information can be viewed and configured remotely, as documented in the Configuration API screens endpoints.
Client-side, screens are rendered via HTML <div>
tags that have id
attributes
corresponding to the screen’s name (as defined in the server-side configuration
file). By default, all screens contain a CSS rule set to "display: none"
, and the Janrain
JavaScript modifies this rule to display and hide the appropriate screen based user interaction moving through he registration experience.
Optionally, there may also be JTL (Janrain Templating Language)
markup within the screen’s div
. The widget uses
this markup to render form elements on the screen. An example screen <div>
for the forgotPassword
screen and JTL
tags for the forgotPasswordForm
is shown below:
<div style="display:none;" id="forgotPassword">
<div class="capture_header">
<h1>Create New Password</h1>
</div>
<h2>We'll send you a link to create a new password.</h2>
{* #forgotPasswordForm *}
{* signInEmailAddress *}
<div class="capture_footer">
<div class="capture_left">
{* backButton *}
</div>
<div class="capture_right">
<input value="Send" type="submit" class="capture_btn capture_primary">
</div>
</div>
{* /forgotPasswordForm *}
</div>
Screen Modality
By default, screens render client-side as a modal (with the exception being the
editProfile
screen). To change this
configuration to all-embedded, you will need to make both client-side and
server-side changes:
- Server-side: Set all screens to
modal=false
via the Configuration API screens endpoint. - Client-Side: Remove all anchor tags with
onclick
attributes that call thejanrain.capture.ui.modal.close()
function, or replace them with your own functions (for example, redirecting a user from thesignIn
screen to theeditProfile
screen after successful login).
Note: If you want both a modal and an embedded version of your screens, you can do one of the following:
- Embed all screens, then create your own modals client-side where desired.
- Create two backend configuration files.
Talk to your Janrain representative for details.
Information on customizing the appearance/styling of screens can be found on the Customizing Registration page.
Rendering Screens Programmatically
Unless noted otherwise (such as for the
verifyEmail
screen), most screens can be
rendered in the browser programmatically, either by calling a JavaScript
function or placing a data-capturescreen
HTML attribute on an anchor
tag.
For example, the forgotPassword
screen
can be rendered by either of the following methods, assuming the screen markup
exists on the user’s current page.
<a href="#" onclick="janrain.capture.ui.renderScreen('forgotPassword')">Forgot your password?</a>
<a href="#" data-capturescreen="forgotPassword">Forgot your password?</a>
Screen Entry-Points
The registration or login flow begins at one of these screens (refer to the individual sections for more details):
Emails Overview
Janrain’s Standard Registration Experience provides transactional emails for common events such as registration confirmation, email verification, and password reset. By default, Janrain sends emails for you by using Amazon Simple Email Services (Amazon SES). However, customers can choose to send transactional emails using their own email service or provider. Email preference is configured by using the email_method
API Client setting. If email_method
is set to ses_sync (the default value) then transactional emails are sent by Janrain and Amazon SES. To send emails using a different service or provider, contact your Janrain representative.
The content for existing emails can be modified by using the Configuration API. In addition, Janrain can add new emails (to be sent in response to additional registration events) to your flow. Additional information on transactional emails can be found in the Customizing Transactional Emails topic
The following sections describe the default emails and when they are triggered.
Email Template Variables
Janrain Registration can perform string substitutions in email templates for variables such as the user’s name or the site name where the user registered for personalization and site-specific customization. This allows you to use the same email templates for different websites or applications that share the same Registration configuration. Variables may be pulled from either the user’s record or API client settings (configured through the Janrain dashboard in the Settings tab). The example email below shows how this will look.
<p>Welcome to {*#settings*}{*site_name*}{*/settings*}, {*#user*}{*givenName*}{*/user*}!</p>
<p>To complete your new registration, just click on or browse to the URL below to verify this email address.</p>
<p><a href="{*email_verification_url*}">{*email_verification_url*}</a></p>
User data variables are included by specifying the entity type in a JTL tag
wrapper around the schema attribute name. For example,
{*#user*}{*givenName*}{*/user*}
pulls in data stored in the givenName schema
attribute. Any schema attribute may be referenced in this way.
Setting variables are included by specifying the setting name inside of a JTL
tag wrapper for settings. For example,
{*#settings*}{*site_name*}{*/settings*}
- pulls in the content defined in
the site_name
API client setting. Any setting may be referenced in this way.
Email templates may also include special JTL link tags that reference API
client settings without the {*#settings*}{*/settings*}
wrapper. These JTL tags
may not be modified.
{*password_recover_url*}
- Generates a unique link for thepasswordRecover
email by appending an authorization code to the URL defined in thepassword_recover_url
client setting. This code has a configurable duration and is valid for 1 day by default.{*email_verification_url*}
- Generates a unique link for theregistrationVerification
andemailAddressChanged
emails by appending a verification code to the URL defined in theverify_email_url
client setting. This code has a configurable duration and is valid for 1 day by default.
Email Template Formatting
Janrain transactional emails are always sent in a combined .html
and .txt
format. Both versions must be supplied for each email and should follow these
formatting guidelines:
- Images - Images must be hosted on your servers and included in the HTML as absolute paths. If you need to include different images per site, variables pulled from the API client settings may reference image URL paths. See Email Template Variables above for more information on how to include variables in email templates.
- CSS Styling - HTML emails should include inline CSS for styling so that the content can be properly displayed in email client applications. We recommend researching how best to prepare single-file HTML content for email transfers as the structure will be slightly different than a traditional HTML web page.
- Encoding HTML Entities - Janrain Registration encodes HTML entities in the URLs by default, which is the desired behavior in an HTML email but not in a text email. Variables used in the text versions of the emails must include an ampersand (”&“) character before the setting or schema attribute name to suppress the encoding. The example below shows how you would format the same email given in the example above as a text version.
Welcome to {*#settings*}{*&site_name*}{*/settings*}, {*#user*}{*&givenName*}{*/user*}!
To complete your new registration, just click on or browse to the URL below to verify this email address.
{*&email_verification_url*}
Screens
accountDeactivated
Social DataThis screen is shown when a user attempts to sign in to a deactivated account.
(An account is deactivated if there is a date/timestamp in the deactivateAccount
attribute in the user’s record.)
Rendered Screen

Next Screens
There are no screens that follow the accountDeactivated screen.
Previous Screens
This screen may have been rendered after visiting one of the following screens:
changePassword
This screen is displayed when the user clicks on the Change Password link
on the Edit Profile
page. The user is required to enter the current
password, new password, and confirm the new password. If this passes
validation, the password is updated when the user clicks Save.
Note: This screen is not displayed unless the user is logged in.
Rendered Screen

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User successfully changes their password. | editProfile |
Previous Screens
This screen may have been rendered after visiting one of the following screens:
confirmAccountDeactivation
This screen is displayed when the user clicks the Deactivate Account link on
the Edit Profile
page. If the user clicks Yes, the current date/time is
entered into the deactivateAccount
attribute in the user’s record.
Note: This screen is not displayed unless the user is logged in.
Rendered Screen

Next Screens
Condition | Next Screen |
---|---|
User clicks Yes to confirm account deactivation. | accountDeactivated Note: User is logged out, redirected to index.html , and accountDeactivated is displayed.Email Sent: accountDeactivated |
User clicks No to avoid deactivating their account. | editProfile |
Since account deactivation involves logging out the user and redirecting the
user away from the Edit Profile
page, this functionality is implemented as
the client-side function handleAccountDeactivation
that is registered with
the onCaptureAccountDeactivateSuccess
event. This function is provided by
your Janrain representative with the reference implementation inside the
janrain-init.js
file. You must include this function to handle
account deactivation.
Previous Screens
This screen may have been displayed after visiting one of the following screens:
editProfile
This screen can be displayed to a user after the user has logged into a site. Unlike all other screens, it is embedded by default.
The Linked Accounts section is populated with the list of previously-linked
social accounts and the ability to add additional social accounts using the
login
widget.
The Password section is displayed only for a traditional account (an
account that has an associated password) based on the CSS class
janrain_traditional_account_only
.
Rendered Screen - Logged-in User

If the user does not have a Janrain access token, the user is presented with a
“permission denied” message. Attempting to render this screen via the Janrain
function renderScreen
also generates this message since the function doesn’t
support additional arguments (so no token is passed to the screen
logic).
Rendered Screen - Logged-out User

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User clicks Deactivate Account. | confirmAccountDeactivation |
User clicks Change Password. | changePassword |
User clicks Link Account. | linkAccount |
User clicks Choose a new photo. | photoManager |
User updates fields including email and clicks Save AND form passes server-side validation. |
editProfile Email Sent: emailAddressChanged |
User updates fields not including email and clicks Save AND form passes server-side validation. |
editProfile |
User edits form and clicks Save AND form fails server-side validation. |
editProfile |
Previous Screens
There are no screens that cause the editProfile
screen to render. In order to access this screen, the user must navigate to
edit-profile.html
by clicking the Edit Profile link from index.html
(after the user has successfully logged in).
emailVerificationNotification
This screen is shown to a user if the user registered without a verified email address.
Rendered Screen

Next Screens
There are no screens that follow the emailVerificationNotification screen.
Previous Screens
This screen may have been rendered after visiting one of the following screens:
forgotPassword
This screen is displayed to a user when the user clicks the Forgot your password? link.
Rendered Screen

Next Screens
One of the following screens can be reached from this screen.
Condition | Next Screen |
---|---|
User enters valid email of an active account. | forgotPasswordSuccess Email Sent: passwordRecover |
User enters valid email of a deactivated account. | accountDeactivated |
User clicks Back button. | signIn |
Previous Screens
This screen may have been rendered after visiting one of the following screens:
forgotPasswordSuccess
This screen is shown after a user enters a valid email on the
forgotPassword
screen. There are no
fields on this screen.
Rendered Screen

Next Screens
There are no screens that follow the
forgotPasswordSuccess
screen.
Previous Screens
This screen may have been rendered after visiting one of the following screens:
linkAccount
After signing in and visiting the profile page, the user has the option to link additional social accounts to their existing account. This screen is displayed when the user clicks the Link Account link in their profile.
Note: This screen cannot be modified and is not rendered by including
<div>
elements on the page. Instead, this screen is included on the
editProfile
page via JTL tags as shown in the following example:
{* #linkAccountContainer *}
<div class="capture_header">
<h1>Link Your Accounts</h1>
</div>
<h2>This allows you to sign in to your account using that provider in the future.</h2>
<div class="capture_signin">
{* loginWidget *}
</div>
{* /linkAccountContainer *}
Note: This screen cannot be rendered programmatically (via the
janrain.capture.ui.renderScreen
function, for example). This screen must be
rendered manually by:
- Logging into an account
- Navigating to the
editProfile
screen - Clicking the Link Account link
Rendered Screen

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User successfully links social account. | editProfile |
User fails to link social account . | linkAccount |
Previous Screens
This screen may have been rendered after visiting one of the following screens:
mergeAccounts
Social DataWhen a user has registered previously and attempts to authenticate with a
new social provider (that returns a matching verified email), the
mergeAccounts
screen is displayed. This screen prompts the user to create a
new account or merge with the existing account.
Note: The reverse cannot occur–if a user originally created an account socially and then attempts to register an account traditionally, this screen will not be displayed.
If the user elects to merge the accounts, the user must authenticate through the existing account before this process is complete. If the existing account is a traditional account, the user is presented with the traditionalAuthenticateMerge screen. If the user elects to create a new account, the socialRegistration screen is displayed that asks the user for a new email address.
Note: This screen cannot be rendered with the JavaScript renderScreen
function.
Rendered Screen

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User elects to merge accounts AND the pre-existing account is a traditional account. |
traditionalAuthenticateMerge |
User elects to merge accounts AND the pre-existing account is a social account. |
(no screen) Note: User is now logged in. |
User elects to create a new account (from either a pre-existing social or traditional account). |
socialRegistration |
Previous Screens
This screen may have been rendered after visiting one of the following screens:
photoManager
After signing in and visiting the profile page, the user can edit the profile image for their account.
Note: You cannot modify this screen, and it is not rendered by including
<div>
elements on the page. Instead, this screen is included on the
editProfile
page via the {* photoManager *}
JTL tag.
Rendered Screen

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User successfully updates their profile image. | editProfile |
User fails to update their profile image (attempts to upload a file that is not a .gif , .jpg , or .png ). |
photoManager |
Previous Screens
This screen may have been rendered after visiting one of the following screens:
resetPassword
Users can submit a request to reset their password via the forgotPassword screen. If successful, the user receives an email that includes a one-time link with an authorization code the user can click to reset their password. This screen is one of two screens that may be displayed; this screen is displayed when the verification code is successfully accepted.
For the case where the verification code is rejected, see the resetPasswordRequestCode screen.
Rendered Screen

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User enters a new password and clicks Submit. | resetPasswordSuccess |
Previous Screens
There are no previous screens. This screen is reached by clicking on the link sent in the passwordRecover email.
resetPasswordRequestCode
Users can submit a request to reset their password via the forgotPassword screen. If successful, the user receives an email that includes a one-time link with an authorization code the user can click to reset their password. This screen is one of two screens that may be displayed; this screen is displayed when the verification code is rejected.
For the case where the verification code is accepted, see the resetPassword screen.
Note: This screen cannot be displayed directly with the JavaScript
renderScreen
function from index.html
. However, it can be rendered by
passing this screen to the screenToRender
URL parameter and by passing the
value foo
to the code
URL parameter.
{widget URL}/index.html?screenToRender=resetPasswordRequestCode&code=foo
Rendered Screen

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User provides a valid email address and clicks Send. | resetPasswordRequestCodeSuccess |
User provides an invalid email address and clicks Send. | resetPasswordRequestCode User is prompted to try again. |
Previous Screens
There are no previous screens. This screen is reached by clicking on the link sent in the passwordRecover email.
resetPasswordRequestCodeSuccess
This screen is rendered after a user enters a valid email in the resetPasswordRequestCode screen, in order to resend the passwordRecover email.
Rendered Screen

Next Screens
There are no screens that follow the resetPasswordRequestCodeSuccess screen.
Previous Screens
This screen may have been rendered after visiting one of the following screens:
resetPasswordSuccess
This screen is rendered when the user successfully changes their password from the resetPassword screen.
Rendered Screen

Next Screens
There are no screens that follow the resetPasswordSuccess screen.
Previous Screens
This screen may have been rendered after visiting one of the following screens:
returnSocial
Social DataThis screen is displayed when a user returns to the site and had
logged in/registered with a social provider on their last visit. The social
sign-in options are populated into the loginWidget
JTL tag from the
customer’s Engage settings. The welcomeName
JTL tag is populated from
the welcome_info_name
cookie.
Note: This screen is rendered only if the janrainLastAuthMethod
local
storage key is set.
Rendered Screen

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User signs in with social account . | (no screen) Note: User is now logged in. |
User clicks “Use another account” link. | signIn |
Previous Screens
There are no previous Janrain screens.
returnTraditional
This screen is displayed when a user returns to the site and had logged
in/registered with a traditional account on their last visit. The displayName
attribute on the user record (if it exists) is added to the span with id
value traditionalWelcomeName
with the function enhanceReturnExperience
in the
janrain_init.js
file. Within the signInForm
are the fields that are used
for validating a traditional login.
Note: This screen is rendered only if the janrainLastAuthMethod
local
storage key is set.
Rendered Screen

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User enters a valid email address and password combination. | (no screen) Note: User is now logged in. |
User clicks “Use another account” link. | signIn |
Previous Screens
There are no previous Janrain screens.
signIn
Social DataThis is the default screen that renders for the widget, and it includes both
traditional and social sign-in options. Within the signInForm
are the fields
that are used for validating a traditional login. The social sign-in options
are populated into the loginWidget
JTL-tag from the Engage settings as
configured in the Engage dashboard.
Note: If the janrainLastAuthMethod
local storage key is set, the
widget will render the
returnTraditional
or returnSocial
screens instead.
Rendered Screen

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User clicks Create Account. | traditionalRegistration |
User selects social login AND the social provider returns an email address that does not match the email address on an existing account OR the social provider returns an unverified email address that does match the email address on an existing account OR the social provider does not return an email address. |
socialRegistration |
User selects social login AND the social provider returns a verified email address that matches the email address on an existing account that is not linked to that social provider. |
mergeAccounts |
User clicks Forgot your password? | forgotPassword |
User selects social login AND their account already exists. |
(no screen) Note: User is now logged in. |
User enters a valid email and password combination. | (no screen) Note: User is now logged in. |
User attempts any of the above with an account that has been deactivated. | accountDeactivated (more details below). |
Note: For the case where a user attempts to log in with an account that has
been deactivated, this functionality is implemented as the client-side function
handleDeactivatedAccountLogin
that is registered with the
onCaptureLoginFailed
event. This function is provided by your Janrain
representative with the reference implementation inside the janrain-init.js
file; you must include this function to handle login of deactivated accounts.
See the JS API documentation
for more information on event handling.
Previous Screens
There are no previous Janrain screens.
socialRegistration
Social DataThis screen is displayed after a user logs in for the first time using a social provider, and may be prepopulated with the data returned by the social provider. Until this form is successfully submitted, the user record does not exist in Janrain’s servers.
Rendered Screen

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User completes form and clicks Create Account AND form passes server-side validation AND email returned by social provider is verified. |
(No screen) Note: User is now logged in. |
User completes form and clicks Create Account AND form passes server-side validation AND email returned by social provider has not been verified. |
emailVerificationNotification Note: User is now logged in. Email Sent: registrationVerification (Email not available for Social Data customers) |
User completes form and clicks Create Account AND form fails server-side validation. |
socialRegistration |
User clicks Back. | signIn |
Previous Screens
This screen may have been rendered after visiting one of the following screens:
traditionalAuthenticateMerge
This screen is displayed if the user selected the option on the mergeAccounts screen to merge a new social account into an existing traditional account.
Rendered Screen

Next Screens
There are no screens that follow the traditionalAuthenticateMerge screen.
Previous Screens
This screen may have been rendered after visiting one of the following screens:
traditionalRegistration
This screen is displayed when a user clicks Create Account. After this form is successfully submitted, Janrain creates the user record.
Rendered Screen

Next Screens
One of the following screens can be reached from this screen:
Condition | Next Screen |
---|---|
User completes form and clicks Create Account AND form passes server-side validation. |
emailVerificationNotification Note: User is now logged in. Email Sent: registrationVerification |
User completes form and clicks Create Account AND form fails server-side validation. |
traditionalRegistration |
User clicks Back. | signIn |
Previous Screens
This screen may have been displayed after visiting one of the following screens:
resendVerificationSuccess
This screen is rendered when a user requests a new verification email on the verifyEmail screen.
Rendered Screen

Next Screens
There are no screens that follow the resendVerificationSuccess screen.
Previous Screens
This screen may have been rendered after visiting one of the following screens:
verifyEmail
When a new user registers with a traditional account or with a social account that does not return a verified email address, an email is sent to the user that includes a one-time link with a verification code the user can click to complete the email verification process. This screen is one of two screens that may be displayed; this screen is displayed when the verification code is not accepted.
See the verifyEmailSuccess screen for the case where the verification code is successfully accepted.
Note: This screen cannot be displayed directly with the JavaScript
renderScreen
function from index.html
. However, it can be displayed by
passing this screen to the screenToRender
URL parameter and by passing the
value foo
to the verification_code
URL parameter.
{widget URL}/index.html?screenToRender=verifyEmail&verification_code=foo
Rendered Screen

Next Screens
Condition | Next Screen |
---|---|
User provides a valid email address and clicks Submit. | resendVerificationSuccess Email Sent: registrationVerification |
User provides an invalid email address and clicks Submit. | verifyEmail User is prompted to try again. |
User provides a valid email address that has already been verified and clicks Submit. | verifyEmail User receives an error message stating that the email has already been verified. |
Previous Screens
There are no previous Janrain screens. This screen is reached by clicking the link sent in the verification email after registering via an unverified email.
verifyEmailSuccess
When a new user registers with a traditional account or with a social account that does not return a verified email address, an email is sent to the user that includes a one-time link with a verification code the user can click to complete the email verification process. This screen is one of two screens that may be displayed; this screen is displayed when the verification code is successfully accepted.
See the verifyEmail screen for the case where the code is rejected.
Rendered Screen

Next Screens
There are no screens that follow the verifyEmailSuccess screen.
Previous Screens
There are no previous Janrain screens. This screen is reached by clicking the link sent in the verification email after registering via an unverified email.
Emails
emailAddressChanged
This email is sent when a user changes their email address from the
editProfile
screen. It includes the
{*verify_email_url*}
JTL tag used to
generate a unique email verification link.
Rendered Email

Next Screens
Condition | Next Screen |
---|---|
User clicks link in email and verification_code is accepted. |
verifyEmailSuccess |
User clicks link in email and verification_code is not accepted. |
verifyEmail |
passwordRecover
This email is sent when a user submits a valid email address on the
forgotPassword screen. It includes the
{*password_recover_url*}
JTL tag used to
generate a unique link with authorization code.
Rendered Email

Next Screens
Condition | Next Screen |
---|---|
User clicks link in email and code is accepted. |
resetPassword |
User clicks link in email and code is not accepted. |
resetPasswordRequestCode |
accountDeactivated Email
This email is sent when a user deactivates an account from the
confirmAccountDeactivation screen accessible
from the editProfile
screen.
Rendered Email

Next Screens
There are no screens that follow the accountDeactivated email.
registrationVerification
This email is sent when a user registers with an unverified email address from
the traditionalRegistration or the
socialRegistration screens. It may also be sent when a
user selects to resend a verification email with a link that has expired or
that was never received. It includes the
{*verify_email_url*}
JTL tag used to generate a
unique email verification link.
Rendered Email

Next Screens
Condition | Next Screen |
---|---|
User clicks link in email and verification_code is accepted. |
verifyEmailSuccess |
User clicks link in email and verification_code is not accepted. |
verifyEmail |