Skip navigation links
 

Subaio Fintech Bridge for Android

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.

Architecture

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

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.

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. new Page("OVERVIEW", null) or new Page("SUBSCRIPTION", new JSONObject(new HashMap() {{ put("subscriptionId", "..."); }})). The exact pages will depend on the application. For simple integrations where the views are simply started as new activities, the host application only need knowledge of the initial overview page, available as Page.overview() for convenience.

Views will push new pages using the onViewNavigated event.

Notifications for the embedded app should generally be implemented to pass name and params provided by subaio on to the host application to easily handle navigation. See the Push Notifications section for details.

Authentication

The subaio views use JSON web tokens for authentication. All views use a shared token, administred by the SubaioManager. The tokens generally expire after one hour, so the SubaioManager has 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 a callback for obtaining a token to the SubaioManager. This callback must handle three cases:

Besides providing the callback, the host application should either invoke SubaioManager.getInstance().refreshToken or set token to null directly when the current user is unauthenticated.

See SubaioManager.TokenHandler.onTokenRequired.

Configuring the SubaioManager

The following options needs to be provided to the SubaioManger before any views can be instantiated:

Example initialization (see app/src/main/java/com/subaio/example/LoadingActivity.java):

SubaioManager.getInstance().setLanguage("en");
        SubaioManager.getInstance().setConfigurationHandler(new SubaioManager.ConfigurationHandler() {
          @Override
          public void onCompletion(SubaioManager.ConfigurationResult result) {
            // Activity with SubaioView can now be started
          }
        });
        final SubaioConfiguration config = new SubaioConfiguration("https://sales-widget.demo.subaio.com", false, false, false);
        SubaioManager.getInstance().configure(config, new SubaioManager.TokenHandler() {
          @Override
          public void onTokenRequired(@NonNull String language) {
            // Fetch a new token
          }
        });

Instantiating a SubaioView

The SubaioView is a UIView that can be inserted in a controller. An example of a controller wrapping a navigation bar and a SubaioView can be found in app/src/main/java/com/subaio/example/SubaioActivity.java.

SubaioView can be added to an activity like a normal Layout. Setup requires setting a Page and a SubaioView.SubaioViewListener implementing event handlers like so:

subaioView.setPage(page)
        subaioView.setListener(new SubaioView.SubaioViewListener() {
          ...
        }

The listener needs to handle the following events:

The delegate may be implemented directly on the controller, as shown in the example.

Push notifications

Subaio is able to generate several different notifications, e.g.

These notifications are sent from Subaio to the backend of the host project, which in turn decides how/if the notification is presented to the user.

The push notification contains information identifying the user, a user facing message, and a payload with details regarding which component should be shown if the notification is activated.

To reduce the amount of maintenance required by the host project, the library provides a method that can be parsed the notification payload which then is turned into a navigation event to reuse the logic implemented there.

SSL-pinning

Configuration of SSL pinning is done through network_security_config.xml as a domain-config with pin-set. See app/src/main/res/xml/network_security_config.xml for example. Generally, subaio domains will be called <name>.<env>.subaio.com, with *.<env>.subaio.com sharing a single certificate.

Testing for external partners will generally be kept on *.qa.subaio.com and production will be run on *.prod.subaio.com. Note that some production services, e.g. error logging is still accessed by apps on *.qa.subaio.com, so *.prod.subaio.com should always be allowed.

Package com.subaio.subaio

Skip navigation links