Step 6. Start a journey

The Advanced Identity Cloud/PingAM 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 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 await configure() has resolved and the Widget is instantiated.

Start the default journey

// Import the Login Widget
import Widget, { configure, journey } from '@forgerock/login-widget';

// Configure the widget; always await this before any other Widget API
await configure({
  wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
  oidcClient: {
    clientId: 'sdkPublicClient',
    redirectUri: `${window.location.origin}/callback`,
    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 server and renders the initial callback.

To specify which journey to use and other parameters, refer to Configure journey() parameters and Configure start() parameters.

Configure journey() parameters

If you do not pass any parameters when calling the journey() function the Advanced Identity Cloud/PingAM 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:

Optional `journey()` parameters
Parameter	Description
`oauth`	Set to `false` to prevent the Advanced Identity Cloud/PingAM Login Widget attempting to obtain OAuth 2.0 tokens after successfully completing a journey. The default is `true`.
`user`	Set to `false` to prevent the Advanced Identity Cloud/PingAM Login Widget attempting to obtain user information by calling the `/oauth2/userinfo` endpoint after successfully completing a journey. The default is `true`.

Example - obtaining only a user session token:

const journeyEvents = journey({
    oauth: false,
    user: false,
});

For more information, refer to journey API reference

Configure start() parameters

If you do not pass any parameters when calling the start() method the Advanced Identity Cloud/PingAM Login Widget will use whichever journey is marked as the default in your server.

You can override this behavior by passing in JSON parameters:

Optional `start()` parameters
Parameter	Description
`journey`	Specify the name of the journey to use. If not specified, the Advanced Identity Cloud/PingAM Login Widget uses whichever journey is marked as the default.
`query`	An object of additional query parameters to include when starting the journey.
`resumeUrl`	Specify the full URL to visit if resuming a suspended journey, for example `window.location.href`. The server uses this to return your users to your application after clicking a "magic link" in an email, for example. Omit this property when starting a new journey.
`recaptchaAction`	Tag reCAPTCHA v3 or reCAPTCHA Enterprise events with a custom action string. Falls back to the journey name.

Example of specifying the journey to use:

// Specify a different journey
journeyEvents.start({
  journey: 'sdkRegistrationJourney',
});

For more information, refer to journey in the 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.

Example - subscribe to journey events

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);
  }
});

Handle journey errors

When authentication fails, event.journey.error is set to an object describing the failure. Check for this alongside the success condition:

Example - handle journey success and failure

journeyEvents.subscribe((event) => {
  if (event.journey.successful) {
    console.log('Authentication succeeded');
  } else if (event.journey.error) {
    console.error('Authentication failed:', event.journey.error.message);
  }
});

Redirect to a failure URL

If your journey includes the Failure URL node, the server returns a failureUrl value inside the detail property of the error object. You can read this value and redirect the user to that URL:

Example - redirect to failure URL

journeyEvents.subscribe((event) => {
  if (event.journey.error) {
    const failureUrl = event.journey.error.detail?.failureUrl;

    if (failureUrl) {
      window.location.assign(failureUrl);
    }
  }
});

The detail property is only present when the server includes it in the failure response.

Always access it with optional chaining (detail?.failureUrl) as it may not be present for all failure types.

Next, you can learn more information about observables and how to Step 7. Subscribe to events.