Step-by-step guide to deploying the JavaScript SDK

ūüďė

The content on this page deals with a legacy feature of the ‚ÄčAkamai‚Äč Identity Cloud (in this case, the JavaScript SDK). If you are currently an Identity Cloud customer and are using the JavaScript SDK, that SDK is still supported. However, if you‚Äôre new to the Identity Cloud the JavaScript SDK is no longer available. Instead, you should use Hosted Login for your login and registration needs.


Each website or application that interfaces with the 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 ‚ÄčAkamai‚Äč is configured with one example API client. The first step to integrating the Registration UI into your site is to create an API clientfor 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 Console):

  • site_name
  • password_recover_url
  • verify_email_url

Some settings may be applied globally to all clients but many settings such as these control site-specific behavior and should be set on individual API clients. 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 in the article Application and API client settings.


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.

‚ÄčAkamai‚Äč's Social Login product is embedded within the Registration product, so many of the steps. 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:

  • Configure providers and permissions
  • Design the UI with the 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. ‚ÄčAkamai‚Äč does not have access to these applications.


Specify 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 [IP allow list. This step should be completed even if you only intend to offer traditional authentication.

For security reasons, only domains on the list are allowed to communicate with your Social Login application. Note that localhost and your Registration application domain should always be in the allow list. ‚ÄčAkamai‚Äč will list 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 that the token URL or xdReceiver has not been listed when attempting to initiate a social login, check the domain allow list to ensure that the site you are currently using is included.


Integrate reference implementation files

Once your development site is on the allow list, 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 Registration UI into your site‚Äôs styling, navigation menus, and session management. Note that ‚ÄčAkamai‚Äč 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  of any pages that will be using the Registration UI, updating the path to the directory where you placed the JavaScript files:

<script src=""></script>
 <script src=""></script>
  1. Add the contents of the  from the index.html and edit-profile.html files to the  of the relevant pages of your site.

  2. 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 Default JavaScript SDK registration experience for details on how to render specific ‚ÄčAkamai‚Äč screens programmatically.

<a href="#"id="captureSignInLink"onclick="janrain.capture.ui.renderScreen('signIn')">Sign In / Sign Up</a>
   <a href=""id="captureProfileLink"style="display:none">Edit Profile</a>
   <a href="#"id="captureSignOutLink"style="display:none"onclick="janrain.capture.ui.endCaptureSession()">Sign Out</a>
  1. 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.

  2. 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 ‚ÄčAkamai‚Äč settings and event handlers, or adding custom JavaScript functions.


Complete server-side integration

When the 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 event handler that ‚ÄčAkamai‚Äč 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 JavaScript SDK access tokens and codes or 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.

ActionEvent Name
RegistrationonCaptureRegistrationSuccess
LoginonCaptureLoginSuccess
Email VerificationonCaptureEmailVerificationSuccess

Configure the registration experience

‚ÄčAkamai‚Äč Identity Cloud 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 Customize JavaScript SDK logins and registrations for more details on making these configuration changes.

  • Add, remove, or update fields, validation rules, labels, and error messages displayed in the Registration UI as needed using the Configuration API.

  • Add attributes to your schema as needed to support new fields that will be used in the Registration UI or any back-end integrations.

  • Add translations for any additional languages that need to be supported in the Registration UI using the Configuration API. Note that any HTML content included directly in the screen files will not be translated by ‚ÄčAkamai‚Äč.

  • Modify the content of transactional emails . Note that ‚ÄčAkamai‚Äč does not send any non-transactional emails.

  • Complete the email verification URL from which transactional mails will be sent.

Note that some complex configurations may need to be completed by ‚ÄčAkamai‚Äč, 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, ‚ÄčAkamai‚Äč will deliver those changes to the customer‚Äôs Development environment for configuration and acceptance testing on the reference implementation. The customer must sign off on this before making any additional Registration experience configurations.