Subaio Fintech Bridge for iOS

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.


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 Subaio 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-like class for global configuration of all views, authentication mangagement, as well as communication between views.
    • BridgeView: A wrapper around a single embedded application.
  • Embedded application: The Subaio 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.

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. Page(name: "OVERVIEW", params: nil) or Page(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, available as Page.overview for convenience.

Views will push new pages using the BridgeViewDelegate.bridgeView(_:navigatedTo:) 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.


The subaio views use JSON web tokens for authentication. All views use a shared token, administred by the BridgeManager. The tokens generally expire after one hour, so the BridgeManager 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 BridgeManager. 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.

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

See TokenRequiredCallback.

Configuring the BridgeManager

The following options needs to be provided to BridgeManager.configure(...) before any views can be instantiated:

  • baseUrl: The URL where the embedded app is hosted.
  • allowExternalUrls: (optional, default false) Allow the embedded app to open arbitrary URLs on the phone. This is primarily used to help navigate the user to iTunes/Google Play subscription pages. This needs to be enabled for the embedded app to be fully functional.
  • allowShare: (optional, default false) Allow the embedded app to request a share dialog to share a message. This is primarily used to help the user help others to find their iTunes subscription page. This needs to be enabled for the app to be fully functional.
  • language: A BCP-47 language tag. The language can be changed on the fly.
  • onTokenRequired: Callback to request a new token. See Authentication section and platform-specific documentation for details. The callback will be called whenever the BridgeManager needs new token information (including if the user is logged out). See TokenRequiredCallback and the Authentication section.
  • authenticationChallenger: Handler for SSL pinning and other connection authentication. See SSL Pinning section.
  • customConfig: (optional, default nil) Custom key/values sent to the views. Keys and possible values should be agreed upon between the embedded and host apps. Possible uses are custom theming, dark/light mode and injecting user info.

Example initialization (found in Example/LoadingViewController.swift):

    baseUrl: URL(string: "")!,
    language: "en",
    allowExternalUrls: true,
    allowShare: true,
    authenticationChallenger: TrustKitAuthenticationChallenger(for: [
        .init(domain: "", publicKeyHashes: [
    onTokenRequired: { (language, completionHandler) in

    customConfig: ["...": "..."]

Instantiating a BridgeView

The BridgeView is a UIView that can be inserted in a controller. An example of a controller wrapping a navigation bar and a BridgeView can be found in Example/BridgeViewController.swift.

Instantiation requires a Page and a BridgeViewDelegate implementing event handlers like so:

let view = BridgeView(page:
view.delegate = delegate
return view

The delegate needs to handle the following events:

Optionally, these events can also be handled:

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.

  • new subscriptions found
  • message regarding cancellation
  • cancellation completed

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.

Adding to Xcode project

With Carthage

This library uses Carthage for dependency management, so install Carthage with (or another method found at

brew install carthage

Once Carthage is installed you build the dependencies with:

carthage bootstrap

Now you are ready to generate the universal binary.

  • Open FintechBridge.xcodeproj
  • Build the scheme FintechBridge-Universal
  • Once done the framework is located at ./universal-framework/FintechBridge.framework

NOTE: Due to it being a universal binary you have to use the script ./scripts/ in order to not have it rejected by Apple due to having Simulator symbols.

This is most easily done by simply copying the script into Build Phases as the last step for your app.

Build documentation

Install jazzy gem

$ gem install --user-install jazzy

Run jazzy gem to generate documentation

$ ~/.gem/ruby/2.3.0/bin/jazzy