CustomerJourneyNavigator

MJCS includes the ability to inject custom fragments in between journey steps. This is an advanced feature and will require more implementation than most MJCS features. By implementing the following CustomerJourneyNavigator interface and passing it to the the CustomerJourneyActivity.startActivity function (described in quick setup) you can insert fragments in various phases of MJCS.

/**
 * The [CustomerJourneyNavigator] allows custom fragments to be injected into the [CustomerJourneyActivity] flow
 * This can be used to display Fragments between actions. The custom Fragment must extend [CustomerJourneyFragment].
 * It is also possible to display a custom loading fragment this must extend [CustomerJourneyLoadingFragment]
 * and will be called every time a background task is started.
 */
@Keep
interface CustomerJourneyNavigator : Serializable {
    /**
     * Called before an [Action] is displayed. The following actions can be returned:
     *
     * [Action.FrontSide]
     * [Action.BackSide]
     * [Action.Selfie]
     * [Action.Liveness]
     * [Action.AddressDocument]
     * [Action.PassiveLiveness]
     * [Action.NfcScan]
     *
     * @param action The action that is going to be presented to the user
     * @param responseUpload The response to the document that was just
     * uploaded containing the triple scan result
     *
     * If this method is overridden super should be returned instead of null to ensure default implementation runs
     *
     * @returns null if there isn't a fragment to be displayed or the fragment to be displayed before the action
     */
    fun actionBefore(action: Action, responseUpload: ResponseUpload?): CustomerJourneyFragment?

    /**
     * Called before an upload task that requires a loading screen is called
     *
     * @param action The action the loading screen will be displayed for
     *
     * returns null or a fragment to be displayed. If null is returned a default loading dialog will be displayed
     * If this method is overridden super should be returned instead of null to ensure default implementation runs
     */
    fun onUploadStarted(action: Action): CustomerJourneyLoadingFragment?

    /**
     * Called when user clicks HW back or cancel button throughout the journey.
     *
     * returns null or a fragment to be displayed.
     *
     * If null is returned journey will be cancelled without any UI to be shown before.
     */
    fun actionBeforeCancel(): CustomerJourneyCancelFragment?
}

Fragments

The interfaces/abstract classes for the three fragment types are shown below. For an example of an implementation of the fragments, see our sample code on github.

/**
 * Should be extended when using [CustomerJourneyNavigator]
 */
@Keep
abstract class CustomerJourneyFragment : Fragment(), WindowUiConfigProvider {
    /**
     * Must be a unique tag
     */
    abstract var TAG: String

    @CallSuper
    open fun finish()

    @CallSuper
    open fun endCustomerJourney()
}

/**
 * Should be extended when using [CustomerJourneyNavigator]
 */
abstract class CustomerJourneyLoadingFragment : Fragment(), WindowUiConfigProvider {

    /**
     * Must be a unique tag
     */
    abstract var TAG : String

    /**
     * Is called when an error has occurred.
     * Retry and Cancel buttons should be displayed when this is called
     * and a description to the user about the error.
     */
    abstract fun <E>onError(error : E)

    /**
     * Called when uploading is finished.
     * Should return true if event has been consumed. Otherwise false.
     * If true is returned [finish] must be called to remove the fragment.
     * Otherwise this will be done automatically
     *
     * @returns boolean indicating if the event has been consumed
     */
    open fun onUploadFinished(): Boolean

    @CallSuper
    /**
     * Prompts CustomerJourney to remove the fragment.
     */
    open fun finish()

    /**
     * Should be called after [onError].
     * Retries the network call.
     */
    @CallSuper
    open fun retry()

    /**
     * Should be called after [onError].
     * Cancels the journey.
     */
    @CallSuper
    open fun cancel()
}

and

/**
 * Optional fragment can be used to show UI if user presses hardware back button
 * or 'X' before cancelling MJCS journey.
 *
 * You don't have to override this, if you don't want to have custom UI before cancelling journey.
 *
 * Overriden fragment needs to be returned from [CustomerJourneyNavigator.actionBeforeCancel]
 *
 * Make sure to call [cancelJourney], when you want to cancel the journey from your UI
 * (e.g. positive button in AlertDialog)
 *
 * Make sure to call [close], when you want to pop this fragment and return to previous journey step
 * (e.g. negative button in AlertDialog)
 *
 * @since 12.3.0
 */
@Keep
abstract class CustomerJourneyCancelFragment : Fragment(), WindowUiConfigProvider {

    /**
     * Must be a unique tag
     */
    abstract val TAG: String

    /**
     * Ensures that [close] is invoked when hardware back button is pressed.
     * If you override this lifecycle method, always call super implementation.
     */
    override fun onViewCreated(view: View, savedInstanceState: Bundle?)

    /**
     * Call this method to cancel MJCS journey.
     */
    open fun cancelJourney()

    /**
     * Call this method to close [CustomerJourneyCancelFragment].
     * It will pop fragment from backstack and restart camera frame feed if needed.
     */
    open fun close()
}