Step 6. Start a journey
The ForgeRock Login Widget displays a loading spinner graphic if it does not yet have a callback from the server to render.
You must specify and start a journey to make the initial call to the server and obtain the first callback.
To start a journey, import the journey
function and execute it to receive a journeyEvents
object. After you have this journeyEvents
object, you can call the journeyEvents.start()
method, which starts making requests to the ForgeRock server for the initial form fields.
You can call the journeyEvents.start()
method anywhere in your application, or anytime, as long as it is after calling the configuration’s set()
method and after instantiating the Widget.
// Import the ForgeRock Login Widget
import Widget, { configuration, journey } from '@forgerock/login-widget';
// Configure SDK options
const myConfig = configuration();
myConfig.set({
forgerock: {
serverConfig: {
baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am',
timeout: 3000,
},
// Optional but recommended configuration:
realmPath: 'alpha',
clientId: 'sdkPublicClient',
redirectUri: window.location.href,
scope: 'openid profile email address'
},
},
});
// Get the element in your HTML into which you will mount the widget
const widgetRootEl = document.getElementById('widget-root');
// Instantiate Widget with the `new` keyword
new Widget({
target: widgetRootEl,
});
// Assign the journey function
const journeyEvents = journey();
// Ensure you call `.start` *AFTER* instantiating the Widget
journeyEvents.start();
This starts the journey configured as the default in your ForgeRock server and renders the initial callback.
To specify which journey to use and other parameters, refer to Configure start() parameters.
Configure start() parameters
If you do not pass any parameters when calling the start()
method the ForgeRock Login Widget will use whichever journey is marked as the default in your ForgeRock server.
The ForgeRock Login Widget will also use the values configured in the last invocation of the configuration’s set()
method.
You can override both of these behaviors by passing in JSON parameters:
Parameter | Description |
---|---|
|
Specify the name of a journey in your ForgeRock instance to use. If not specified, the ForgeRock Login Widget uses whichever journey is marked as the default |
|
Override the current SDK configuration with any new or altered settings. For more information, refer to Step 4. Configure the SDK. |
|
Specify the full URL to visit if resuming a suspended journey. The ForgeRock server uses this to return your users to your application after clicking a "magic link" in an email, for example. The default is |
// Specify a different journey
journeyEvents.start({
journey: 'sdkRegistrationJourney',
});
For more information, refer to journey in the API reference.
Configure journey() parameters
If you do not pass any parameters when calling the journey()
function the ForgeRock Login Widget will attempt to retrieve OAuth 2.0 tokens and user information by default.
You can override this behavior by passing in the following JSON parameters:
Parameter | Description |
---|---|
|
Set to The default is |
|
Set to The default is |
const journeyEvents = journey({
oauth: false,
user: false,
});
For more information, refer to journey API reference
Listen for journey completion
Use the journeyEvents.subscribe
method to know when a user has completed their journey.
A summary of the events for a journey and their order is as follow:
-
Journey is loading
-
Journey is complete
-
Tokens are loading
-
Tokens are complete
-
Userinfo is loading
-
Userinfo is complete
Pass a callback function into this method to run on journey related events, of which there will be many, and each event object you receive contains a lot of information about the event.
You conditionally check for the events you are interested in and ignore what you do not need.
journeyEvents.subscribe((event) => {
// Called multiple times, filtering by event data is recommended
if (event.journey.successful) {
// Only output successfull journey log entries
console.log(event);
}
});
Next
Next, you can learn more information about observables and how to Step 7. Subscribe to events.