Flows⚓︎
The nextAuth Mobile SDK creates a flow to handle sequences in which user input is required by the SDK. A flow represents the sequence of high-level user interactions that are to be handled by your mobile app’s UI.
The flow indicates what the current user interaction is and whether it is still waiting for user input (or whether 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 allow creation of a reactive app (i.e. one that can refresh its state automatically).
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 at a given time.
A flow is created by starting a new session, by initiating a transaction signing or by specific second factor actions (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 starts with a State of WAIT_FOR_INPUT when it can accept the user’s input right away, or PROCESSING when it first needs to communicate with the server to get additional information. After completion, the flow will have a State of DONE or ERROR. These last two states are final states, i.e. the flow will not receive any further updates afterwards.
Whenever the flow has a State of WAIT_FOR_INPUT, the UI should show the relevant elements to gather input from the user, based on the CurrentInteraction. The field 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 value of 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 during the initial input validation (e.g. for an unexpected input method or a missing pin). These exceptions should be caught by the mobile app, after which it can optionally 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 to indicate that the State of the flow is now PROCESSING, while the CurrentInteraction will remain mostly the same (it will now also contain the list of the 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 a PreviousInteractionResult that reflects the result of the user input just processed;
* 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 immediately stops the flow and results in a flow update callback with a State of ERROR.
NextAuth.getNextAuth().getFlowManager().cancel();
flowService.cancel()