Orchestration SDKs

Starting an authentication journey in React Native

PingOne Advanced Identity Cloud PingAM React Native

The recommended way to start and navigate a journey in a React Native component is with the useJourney hook. It returns a tuple of the current node and a set of actions.

Use the actions.start() method to start an authentication journey, and pass the name of the journey as the first argument.

Starting a journey with useJourney
import { useJourney } from '@ping-identity/rn-journey';

function LoginScreen() {
  const [node, actions] = useJourney();

  useEffect(() => {
    actions.start('sdkUsernamePasswordJourney');
  }, []);

  // ...
}

Sharing journey state across multiple screens

Each screen that calls useJourney gets its own isolated state by default, so a LoginScreen and an MFAScreen would each track separate journeys, with no shared context.

The Journey module implements a JourneyProvider that you can use to hold journey state, such as the current node, in-flight requests, and the configured client. This keeps all relevant data about state in a single place that any descendant component can access when calling useJourney.

Wrapping your navigator, or your entire app, with JourneyProvider means every screen within it reads from and writes to the same journey state, allowing a multi-screen authentication flow to progress through nodes seamlessly.

Using JourneyProvider to share state across screens
import { JourneyProvider, useJourney } from '@ping-identity/rn-journey';

function App(): React.ReactElement {
  return (
    <JourneyProvider client={client}>
      <AuthNavigator />
    </JourneyProvider>
  );
}

function LoginScreen(): React.ReactElement {
  const [node, actions] = useJourney();
  return <></>;
}

Passing additional options to a journey

You can pass additional options in the second argument of the start() method, however you chose to start the journey:

Adding parameters when starting a journey with a hook
useEffect(() => {
    actions.start('sdkUsernamePasswordJourney', {
        forceAuth: true,
        noSession: false,
    });
}, []);

The options you can pass to start() include the following:

forceAuth

Set this to true to force traversal of an authentication journey, even if the user already has a valid session.

Default is false.

noSession

Set this to true to prevent the authentication journey from issuing a new session token upon successful completion.

Default is false.

Cleaning up abandoned journeys

If a user navigates away from a login screen mid-flow, the native journey instance remains allocated until it is explicitly released.

Call dispose() to tear down that in-flight instance and reset the client to a clean state, so the next call to start() begins a fresh journey rather than resuming a stale one.

Disposing an in-flight journey before starting a new one
useEffect(() => {
  return () => {
    actions.dispose();
  };
}, []);

The call to dispose() is a no-op when no journey is active, so it is safe to call unconditionally.

Calling dispose() doesn’t log the user out or revoke any tokens, you should call logoutUser() instead.

Learn more in Managing sessions and tokens in React Native.