Step-by-Step Implementation Process

Each website or application that interfaces with the Janrain Registration UI should use its own API client provisioned with the login_client feature. See API Clients and Permissions for more information on the behavior that API clients control.

The reference implementation provided by Janrain is configured with one example API client. The first step to integrating the Registration UI into your site is to create a new API client for your development site.

Update API Client Settings

The second step to integrating the Registration UI into your site is to apply the required settings to your new API client. The following settings are used in the default Registration experience and will need to be implemented for each API client used with the Registration UI (all settings can be modified by using the Janrain Console):

Some settings may be applied globally to all API clients, but many settings such as these control site-specific behavior and should be set on each client individually. Additional settings may be configured in your reference implementation and should be set up on new API clients as needed. Refer to the full list of settings available on the API Client Settings section.

Configure Social Providers

If you are offering social authentication on your sites, the next step to integrating the Registration UI is to configure your social providers. If you only plan to offer traditional authentication, you may skip this step.

Janrain’s Social Login product is embedded within the Registration product, so many of the steps that are documented in Implementing Social Login are handled for you. To enable social providers to be used for login and registration, you will only need to complete the following configuration steps using the Social Login dashboard:

The testing tool available in the dashboard is the first place to test that you have configured each social provider correctly and are requesting the right permissions from users.

When creating an application with social providers that require configuration on their side, it is recommended to use a shared account for your company rather than an individual developer’s account. Janrain will have no access to these applications.

Whitelist Domains for Integration

The next step to integrating the Registration UI into your site is to add your development and testing domains to your Social Login application’s Domain Whitelist setting. This step should be completed even if you only intend to offer traditional authentication.

For security reasons, only whitelisted domains are allowed to communicate with your Social Login application. Note that localhost and your Registration application domain should always be in the whitelist. Janrain will whitelist these for you as part of the provisioning process.

You will then need to add any domains where the Registration UI will be integrated. If you see an error message stating “The token URL or xdReceiver has not been whitelisted” when attempting to initiate a social login, check the domain whitelist to ensure that the site you are currently using is included.

Integrate Reference Implementation Files

Once your development site has been whitelisted, you are ready to begin integrating the source files provided with the reference implementation into your website or application code. These files can be modified as needed to incorporate the Janrain Registration UI into your site’s styling, navigation menus, and session management. Note that Janrain does not provide hosting for any of this content.

  1. Add the janrain-init.js file and, optionally, the janrain-utils.js file to the directory hosting your JavaScript files.
  2. Update janrain.settings.capture.clientId in janrain-init.js to use the new API client created earlier.
  3. Add the following scripts to the <head> of any pages that will be using the Janrain Registration UI, updating the path to the directory where you placed the JavaScript files:
    
    <script src="scripts/janrain-init.js"></script>
    <script src="scripts/janrain-utils.js"></script>
    
    
  4. Add the contents of the <body> from the index.html and edit-profile.html files to the <body> of the relevant pages of your site.
  5. Replace the sample event handlers for user navigation copied from the reference implementation as needed to integrate sign in, sign out, register, and profile links into your site’s navigation. See the Default Registration Experience page for details on how to render specific Janrain screens programmatically.
    
    <a href="#"id="captureSignInLink"onclick="janrain.capture.ui.renderScreen('signIn')">Sign In / Sign Up</a>
    <a href="edit-profile.html?screenToRender=editProfile"id="captureProfileLink"style="display:none">Edit Profile</a>
    <a href="#"id="captureSignOutLink"style="display:none"onclick="janrain.capture.ui.endCaptureSession()">Sign Out</a>
    
    
  6. Add the janrain.css and janrain-mobile.css files to the directory hosting your CSS files and update as needed to match the styling of the Registration UI to your site.
  7. Update janrain.settings.capture.stylesheets and janrain.settings.capture.mobileStylesheets in janrain-init.js to point to the directory where you placed the CSS files.

From here you can make additional changes to these files to customize the Registration UI, such as adding HTML around the JTL tags for forms and fields, reordering JTL tags within a form, defining more Janrain settings and event handlers, or adding custom JavaScript functions.

Complete Server-side Integration

When the Janrain Registration UI is properly integrated into your development environment, users will be able to log in and register just as on the reference implementation. By default, an OAuth access token will be generated upon successful user authentication and stored client-side in the localStorage key janrainCaptureToken. This key indicates to the Registration UI that a user is authenticated and can access profile management screens.

The access token will also be returned in the JavaScript event handlers that Janrain fires upon successful login and registration. Access tokens are valid for one hour, so if your site maintains user sessions for longer periods of time, you can create functions in these event handlers to send the access token to your server, and then create a session for the user and refresh the access token hourly as needed. See Access Tokens and Session Management for more information on this topic.

Below is an example event handler for the onCaptureSessionCreated event, which fires when a user successfully logs in, registers, or completes the email verification process and returns an object containing an access token. As in the example, event handlers must be included within the janrainCaptureWidgetOnLoad function in janrain-init.js, before the start argument.


functionjanrainCaptureWidgetOnLoad(){
  janrain.events.onCaptureSessionCreated.addHandler(function(result){
    vartoken = result.accessToken;
    // Insert code to pass token variable to server
  });
  janrain.capture.ui.start();
}

Alternatively, each scenario in which an access token is generated can be handled differently by targeting one of the events listed below.

Action

Event Name

Registration

onCaptureRegistrationSuccess

Login

onCaptureLoginSuccess

Email Verification

onCaptureEmailVerificationSuccess

Configure the Registration Experience

Janrain APIs offer many self-service options for modifying the Default Registration Experience. Below are the most common types of configuration changes that you will want to think about when planning your development cycles. See Customizing Registration for more details on making these configuration changes.

Note that some complex configurations may need to be completed by Janrain, such as adding computed logic to the registration flow, creating new forms and screens, or adding or removing transactional email triggers. If in scope for the project, Janrain will deliver those changes to the customer’s Development environment for Configuration Acceptance Testing on the reference implementation. The customer must sign off on this before making any additional Registration experience configurations.