Step 6. Start a journey

The Ping (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 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.

Start the default journey

// Import the 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 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 Ping (ForgeRock) Login Widget will use whichever journey is marked as the default in your server.

The Ping (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:

Optional `start()` parameters
Parameter	Description
`journey`	Specify the name of the journey to use. If not specified, the Ping (ForgeRock) Login Widget uses whichever journey is marked as the default
`forgerock`	Override the current SDK configuration with any new or altered settings. For more information, refer to Step 4. Configure the SDK.
`resumeUrl`	Specify the full URL to visit if resuming a suspended journey. The server uses this to return your users to your application after clicking a "magic link" in an email, for example. The default is `window.location.href`.

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.

Configure journey() parameters

If you do not pass any parameters when calling the journey() function the Ping (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:

Optional `journey()` parameters
Parameter	Description
`oauth`	Set to `false` to prevent the Ping (ForgeRock) Login Widget attempting to obtain OAuth 2.0 tokens after successfully completing a journey. The default is `true`.
`user`	Set to `user` to prevent the Ping (ForgeRock) 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

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

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

Ping SDKs

Step 6. Start a journey

Configure start() parameters

Configure journey() parameters

Listen for journey completion

Next