This document provides informations of how to use the Subaio Fintech Bridge in your projects. There exists 3 Fintech Bridge libraries:
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.
The fintech bridge is intended for embedding small, widget-like applications inside a larger app. The application is structured in the following parts:
SubaioManager
: A singleton-class for global configuration of all subaio-views, authentication mangagement, as well as communication between views.SubaioView
: A wrapper around a single embedded application.Including embedded applications thus requires including the bridge library, configuring the SubaioManager and instantiating a SubaioView.
Each bridge project includes an example project demonstrating how to use the manager and the views.
The library supports ES6 Modules (ESM), CommonJS imports and inclusion as a library script.
import { SubaioManager, SubaioView } from '@subaio/fintech-bridge-web'
const { SubaioManager, SubaioView } = require('@subaio/fintech-bridge-web')
<script src='/path/to/fintech-bridge-web/dist/subaio.min.js'></script>
var SubaioManager = window.Subaio.SubaioManager
var SubaioView = window.Subaio.SubaioView
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.
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:
SubaioManager
will ignore this attempt and try to request a new token later (likely after 1 minute).SubaioManager
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
SubaioManager.shared.configure({
onTokenRequired: async (language) => {
// success
return token
// unauthenticated
return null
// unavailable
throw new Error('...')
},
})
// Manual promise
SubaioManager.shared.configure({
onTokenRequired: (language) => new Promise((resolve, reject) => {
// success
resolve(token)
// unauthenticated
resolve(null)
// unavailable
reject(new Error('...'))
}),
})
// Callback
SubaioManager.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 SubaioManager.shared.refreshToken
when the current user is unauthenticated or a new user is authenticated.
See OnTokenRequired
.
SubaioManager
The following options needs to be provided to the SubaioManager.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 SubaioManager needs new token information (including if the user is logged out). See OnTokenRequired
and the Authentication section.SubaioView
The SubaioView
is a wrapper around an iframe
DOM element. It has to be created in a container-element.
Example instantiation:
var view = new Subaio.View({
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.
If it is necessary to customize parts of the embedded app, such as colors, this can be passed as customValues
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:
SubaioManager.shared.configure({
customValues: {
'color': '#123456',
'fonts.regular.url': 'https://path.to/font/file',
},
})
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
.
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.URL pointing to root of Subaio template, e.g. if template is at
https://www.bar.foo/template
, then baseUrl should be
https://www.bar.foo
.
Custom named values (such as customizable colors) sent to the views.
Language to be used by all Subaio views as a BCP-47 string.
Callback invoked whenever SubaioViews need an authentication token.
Takes the current language-tag as first parameter. Can either return a promise or invoke a node-style callback provided as second parameter to signal completion.
Three cases are supported:
null
.Custom events can be added. The signature of a custom event should be agreed upon between the host and embedded app.
Called whenever a view attempts to close itself.
Called whenever an error occurs. Should handle 2 cases:
load
: The iframe failed to load the page, or the page failed to
communicate in a timely manner.internal
: An error occured inside the embedded application. A
built-in error screen is shown, it is not necessary for the host
application to show an error.Called whenever the view attempts to navigate to another page.
Called whenever the content of the iframe resizes. Is only enabled when
enableResize
is set to true
.
Called whenever the status of the view changes.
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
.
Can be used to implement a custom error-screen by hiding the view and
showing an error page on a change to errored
.
Called whenever the view changes title.
If a host-application controlled title-bar is used, this text should be shown there.
Callback invoked whenever SubaioViews need an authentication token.
Takes the current language-tag as first parameter. Can either return a promise or invoke a node-style callback provided as second parameter to signal completion.
Three cases are supported:
null
.The target element. The iframe will attempt to fill the entire container.
Enable the onResize
event. Defaults to off to avoid unnecessary
tracking of size.
Instance of SubaioManager to be used. Defaults to the shared instance,
SubaioManager.shared
. Useful in paradigms where singletons are
discuraged over distributed instances.
Override iframe settings. Both width and height defaults to '100%'.
Generated using TypeDoc
Promise implementation to be used. Defaults to native promises, which requires a polyfill to work in any Internet Explorer.
Can be replaced with another implementation, such as
Q
orBluebird
.null
disables promises returned from functions.