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.
-
Add theĀ janrain-init.jsĀ file and, optionally, theĀ janrain-utils.jsĀ file to the directory hosting your JavaScript files.
-
UpdateĀ janrain.settings.capture.clientIdĀ inĀ janrain-init.jsĀ to use the new API client created earlier.
-
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>
-
Add the contents of theĀ Ā from theĀ index.htmlĀ andĀ edit-profile.htmlĀ files to theĀ Ā of the relevant pages of your site.
-
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>
-
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.
-
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.
Action | Event Name |
---|---|
Registration | onCaptureRegistrationSuccess |
Login | onCaptureLoginSuccess |
Email Verification | onCaptureEmailVerificationSuccess |
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.
Updated 4 months ago