Subaio Fintech Bridge for Web

This document provides informations of how to use the Subaio Fintech Bridge in your projects. There exists 3 Fintech Bridge libraries:

• Fintech Bridge for iOS
• Fintech Bridge for Android
• Fintech Bridge for Web.

The libraries provides user interfaces, API integrations and other functionality related to Subaio. The purpose of the libraries is to reduce the implementation and maintenance cost the host applications, while enabling the Subaio application to evolve parallel with the host application. While there are slight differences between them because of differences in syntax and convention, the general structure is the same.

Architecture

The fintech bridge is intended for embedding small, widget-like applications inside a larger app. The application is structured in the following parts:

• Host application: The iOS-, Android-, or web-application that hosts the web-components. This might be a mobile bank application or web home banking solution.
• Bridge: The bridge library is used by the host application to grant easy control over the embedded app as well as a standardized event system. It consists primarily of two components:
  • BridgeManager: A singleton-class for global configuration of all subaio-views, authentication mangagement, as well as communication between views.
  • BridgeView: A wrapper around a single embedded application.
• Embedded application: The web-application running inside of a webview/iframe.

Including embedded applications thus requires including the bridge library, configuring the BridgeManager and instantiating a BridgeView.

Each bridge project includes an example project demonstrating how to use the manager and the views.

Importing

The library supports ES6 Modules (ESM), CommonJS imports and inclusion as a library script.

ESM

import { BridgeManager, BridgeView } from '@subaio/fintech-bridge-web'

CommonJS

const { BridgeManager, BridgeView } = require('@subaio/fintech-bridge-web')

Library

<script src='/path/to/fintech-bridge-web/dist/subaio.min.js'></script>

var BridgeManager = window.FintechBridge.BridgeManager
var BridgeView = window.FintechBridge.BridgeView

Navigation

To better facilitate native transitions between pages, the subaio app is separated in pages that can be placed in separate view-controllers and pushed separately to the nagivation stack.

Each instance of an embedded view can be set to show a specific Page, defined by a name and optionally a set of parameters, e.g. { name: "OVERVIEW", params: null } or { name: "SUBSCRIPTION", params: { subscriptionId: "..." } }. The exact pages will depend on the application. For simple integrations where the views are simply pushed to the navigation stack, the host application only need knowledge of the initial overview page.

Views will push new pages using the onNavigatedTo event.

Authentication

The subaio views use JSON web tokens for authentication. All views use a shared token, administred by the global configuration. The tokens generally expire after one hour, so there is internal logic to automatically refresh the token when necessary.

The preferred method of obtaining a subaio token is to let the host application make an authenticated request to its own backend, which will then request a token from the subaio backend.

The host application is responsible for providing an onTokenRequired callback for obtaining a token. This callback must handle three cases:

• Successfully obtained a token. This is distributed to the views and used for future requests.
• Temporarily unavailable, from a network outage or similar. The BridgeManager will ignore this attempt and try to request a new token later (likely after 1 minute).
• User unauthenticated. The user is no longer logged in and any active views should be cleared of all data. The BridgeManager will stop requesting new tokens. This is signalled by throwing any error, to ease usage with fetch.

The onTokenRequired callback provided to the configure function has two modes of operation: a promise-based version and a node-style callback version.

// Async/await
BridgeManager.shared.configure({
    onTokenRequired: async (language) => {
        // success
        return token
        // unauthenticated
        return null
        // unavailable
        throw new Error('...')
    },
})

// Manual promise
BridgeManager.shared.configure({
    onTokenRequired: (language) => new Promise((resolve, reject) => {
        // success
        resolve(token)
        // unauthenticated
        resolve(null)
        // unavailable
        reject(new Error('...'))
    }),
})

// Callback
BridgeManager.shared.configure({
    onTokenRequired: (language, callback) => {
        // success
        callback(null, token)
        // unauthenticated
        callback(null, null)
        // unavailable
        callback(new Error('...'))
    },
})

Besides providing the callback, the host application should invoke BridgeManager.shared.refreshToken when the current user is unauthenticated or a new user is authenticated.

See OnTokenRequired.

Configuring the BridgeManager

The following options needs to be provided to the BridgeManager.shared.configure function before any views can be instantiated:

• baseUrl: The URL where the embedded app is hosted.
• language: (default null) A BCP-47 language tag. The language can be changed on the fly. If a language is not provided, views will stay in loading-state until one is provided.
• onTokenRequired: Callback to request a new token. The callback will be called whenever the BridgeManager needs new token information (including if the user is logged out). See OnTokenRequired and the Authentication section.

Instantiating a BridgeView

The BridgeView is a wrapper around an iframe DOM element. It has to be created in a container-element.

Example instantiation:

var view = new BridgeView({
    element: element,
    page: { name: 'OVERVIEW', params: null },
    eventHandlers: {
        onNavigateTo: function (page) { },
        onBack: function (view) { },
        onStatusChange: function (status) { },
        onTitleChange: function (title) { },
        onError: function (type) { },
    },
})

The events provided are:

• onNavigateTo: Handles navigation to a new Page.
• onBack: Handles navigation away from the current view.
• onStatusChange: Called whenever the view changes status. It can be safely ignored. Can be used to implement a custom loading-screen by hiding the loading-screen and showing the view on a change to running or errored, or to implement a custom error-screen by hiding the view and showing an error page on a change to errored.
• onTitleChange: Called whenever the view changes title. This is useful if a host application controlled navigation bar is used. Otherwise it can be safely ignored.
• onError: Called whenever the view receives an error.
  • load: The iframe failed to load the page, or the page failed to communicate in a timely manner.
  • internal: Does not need to be handled as the View will show its own error page.

Before the container-element is removed from the DOM, the view.cleanup method should always be called.

Customization

If it is necessary to customize parts of the embedded app, such as colors, this can be passed as customConfig when configuring the manager.

The specific custom value names should be agreed between host and embedded app. Note that while an arbitrary JSON-serializable POJO can be passed, it is recommended to use a flat object with string keys as JS-style dot-paths to ensure compatibility with iOS/Android versions, where creating arbitrary object structures is less straight forward.

Example:

BridgeManager.shared.configure({
    customConfig: {
        'color': '#123456',
        'fonts.regular.url': 'https://path.to/font/file',
    },
})

Build package

The package can be built by running yarn build or npm run build. Output will be placed in dist, documentation will be placed in docs.

Examples

Development can be started by running yarn start or npm run start. Server port is specified by PORT env variable (default 8080).

• /exampleSimple.html: A minimalist example of usage. The bridge is included as a script tag and everything is written to be runnable on older browsers.