Skip to content

Flows⚓︎

During the phases where user input is required by the nextAuth Mobile SDK, the nextAuth Mobile SDK will create a flow. A flow produces a sequence of user interactions, to be handled in the mobile app’s UI.

The flow indicates what the current user interaction is, whether that is still waiting for user input (or no input is necessary). In case there was a previous interaction, the outcome of that interaction is also included.

Flow updates are received through callbacks from the SDK, which should be subscribed to in the mobile app. When combined with other update mechanisms for other models, this mechanism can be leveraged to build a reactive Mobile SDK.

Flow Structure⚓︎

Field Description
Type ENROL, LOGIN, SIGN_TRANSACTION, CHANGE_PIN, ADD_BIOMETRICS, REMOVE_BIOMETRICS, or HEADLESS_UPGRADE.
Remains unchanged during the entire flow.
State WAIT_FOR_INPUT, PROCESSING, DONE , or ERROR.
Error In case status is ERROR, a more detailed error.
CurrentInteraction Current user interaction.
PreviousInteractionResult Information about the previous interaction and the outcome.
SecondFactorAccount Information about second factor (e.g. remaining attempts, pin blocked…).
Session Information about the session.
Transaction Information about the transaction.

Flow Lifecycle⚓︎

Only one flow can be active simultaneously.

A flow is created by starting a new session, transaction signing or a specific second factor action (add/remove biometric, change pin). Newly started actions that require a flow will throw an exception if another flow is already active.

A new flow has as State WAIT_FOR_INPUT (when it can accept the user's input directly) or PROCESSING (when it first needs to communicate with the server to get additional information). After completion, the flow will have as State DONE or ERROR. These last two states are final, i.e. this flow will not receive any further update.

Whenever the flow has as State WAIT_FOR_INPUT, the UI should show the relevant elements to gather input from the user, based on the CurrentInteraction. PreviousInteractionResult contains the details of the last CurrentInteraction before completion of the flow (if any). SecondFactorAccount, Session, or Transaction might contain additional context (depending on the CurrentInteraction).

User Input⚓︎

The user’s input is to be returned to the nextAuth Mobile SDK through one of the following methods:

  • confirmSession,
  • confirmTransaction,
  • inputSecondFactor, or
  • cancel.

Each of these methods (except cancel) can throw an exception on initial input validation (e.g. unexpected input method, missing pin…). These exceptions should be caught by the mobile app, after which it can possibly try to provide input again to the nextAuth Mobile SDK.

The moment user input (except cancel) is provided to the nextAuth Mobile SDK (and passes initial input validation), it sends out a flow update callback with where the State of the flow is now PROCESSING, while the CurrentInteraction will remain mostly the same (it will now also contain the list of input types InputType that the mobile SDK is currently processing). During this time a spinner may be shown.

Once the user input is processed, the nextAuth Mobile SDK sends out a flow update callback:

  • if more user input is required: with a CurrentInteraction, indicating which user input is requested, and PreviousInteractionResult that reflects result of the just processed user input;
  • whenever an error occurs (e.g. networking error, server validation error, timeout ...) or the user cancels the flow: the State of the flow is ERROR, CurrentInteraction is null, PreviousInteractionResult might contain the outcome of the previous interaction, and Error contains a detailed error;
  • when the action in its entirety (e.g. enrol, login, transaction sign, pin change ...) is successful: the State of the flow is DONE.

Cancel⚓︎

cancel can be called at any time during the flow. Calling cancel directly stops the flow and results in a flow update callback with State ERROR.

NextAuth.getNextAuth().getFlowManager().cancel();

flowService.cancel()