Implementation

This guide walks you through everything needed to embed Managed Banking. To get started, make sure you’ve signed up for a Sandbox environment—if you haven’t yet, please do so before proceeding.

Embedding

5 minutes

If you have not done so already, embed the component into your app.

Add the script tag below to your HTML header

<script type="module" src="https://ui.s.unit.sh/release/latest/components-extended.es.js"></script>

Note

In the production environment, use https://ui.unit.co/release/latest/components-extended.es.js as the script source.

Add a new page to your app that will host Managed Banking. Paste the code below to the new page.

<unit-elements-white-label-app jwt-token="demo.jwt.token"></unit-elements-white-label-app>

Note demo.jwt.token is a real value you can use to preview the component without any setup.

You may choose to create unit-elements-white-label-app dynamically using JavaScript:

<html>
  <head>
    <script type="module"
      src="https://ui.s.unit.sh/release/latest/components-extended.es.js"
    ></script>
  </head>
  <body>
    <div id="unit-app-placeholder"></div>
    <script>
      const unit = document.createElement("unit-elements-white-label-app");
      unit.setAttribute("jwt-token", "demo.jwt.token");
      document.querySelector("#unit-app-placeholder").append(unit);
    </script>
  </body>
</html>

Authentication

Up to 2 hours

In order to seamlessly authenticate with the component, you need to pass it a JWT, that allows us to identify your user and verify that they are logged in.

Unit will not ask the user to log in using a separate set of credentials. However, before performing any sensitive banking activities, we will OTP the user.

In sandbox, please use code 000001 to complete the OTP.

Configuring your identity provider

20 minutes

If your identity provider (or your own implementation) exposes a JWKS path (for example, Okta, Auth0, AWS Cognito, or Stytch), follow the steps below. If not, follow the steps in Unit’s Custom JWT Authentication Guide.

Log into Unit's dashboard.

Under Developer, go to Settings.
In the Authentication tab, choose your identity provider from the Provider dropdown.
Paste the JWKS path into the JWKS field.

Passing The JWT

10 minutes

Pass your JWT to the component (see example below), replacing the static token that was previously there.

<unit-elements-white-label-app jwt-token="{{JwtToken}}"></unit-elements-white-label-app>

If the JWT token is recognized as an existing user, the user will see their account. If the JWT token is recognized as a new user, the user will be presented with the application form.

In sandbox, please use a unique phone number with each application submission.

Attributes

Use these attributes to configure <unit-elements-white-label-app> when embedding it in your application.

Name	Type	Required	Description
customer-token	string	No	A Unit Customer token. Can be used to embed the component for an existing customer.
navigation-position	string	No	Position of the navigation on mobile and narrow views. Use `"top"` to show navigation at the top. Defaults to bottom.
navigation-menu-items	string	No	Comma-separated list of navigation menu items to display.
is-stretching-layout	boolean string ("true" / "false")	No	Stretch the component layout to fill the available container when set to `"true"`.
application-form-full-screen-height	boolean string ("true" / "false")	No	Controls the embedded application form height. Defaults to `"true"`. Set to `"false"` to make the main part height `auto`.
products	string	No	Comma-separated list of products to enable in the component. Supported values are `"Banking"`, `"Capital"`, and `"BillPay"`.
router-type	string	No	Controls the internal routing strategy used by the component. Use `"memory"` (default) for in-memory navigation invisible to the browser's address bar, suitable for embedding inside an existing app or SPA. Use `"hash"` to reflect the current page in the URL hash (`#`), enabling bookmarks, deep links, and browser back/forward navigation — recommended when the component is the primary content of the page.

Cleanup

10 minutes

The component will use 2 keys in local storage: unitCustomerToken and unitVerifiedCustomerToken. It's important to clean them up when the user logs out from your app, or after 24 hours, whichever comes first.

localStorage.removeItem("unitCustomerToken");
localStorage.removeItem("unitVerifiedCustomerToken");

Suggestion

Starting from version 4.2.0, tokens are stored in memory rather than localStorage. If you are using version 4.2.0 or later, you no longer need to manually remove these keys on logout.

Content Security Policy

10 minutes

If you are using a Content-Security-Policy (CSP) header, you may need to extend it to allow the web components and third-party integrations (such as Zendesk and Plaid) to work correctly.

Add the following <meta> tag:

<meta
  http-equiv="Content-Security-Policy"
  content="
    connect-src 'self'
      https://*.s.unit.sh
      https://*.unit.co
      https://*.zdassets.com
      https://*.zendesk.com
      https://cdn.plaid.com
      https://*.verygoodvault.com
      https://*.vouched.id
      https://*.au10tixservices.com;
    script-src 'self'
      https://*.zdassets.com
      https://*.zendesk.com
      https://cdn.plaid.com
      https://js.verygoodvault.com
      https://*.vouched.id
      https://*.au10tixservices.com;
    frame-src 'self'
      https://*.zendesk.com
      https://cdn.plaid.com
      https://*.verygoodvault.com
      https://*.vouched.id
      https://*.au10tixservices.com;
  "
/>

Installation

5 minutes

Add the react-native-unit-components and the react-native-webview dependencies to your project:

Using npm:

npm install --save react-native-unit-components react-native-webview react-native-safe-area-context

Using yarn:

yarn add react-native-unit-components react-native-webview react-native-safe-area-context

Embedding

10 minutes

1. Initialize Unit SDK

Call UnitComponentsSDK.init in your root component with the required environment.

import React, { useEffect } from 'react';
import { UnitComponentsSDK, UNComponentsEnvironment } from 'react-native-unit-components';

export default function YourRootComponent() {
	useEffect(() => {
		UnitComponentsSDK.init(UNComponentsEnvironment.sandbox);
	}, []);
}

Note

For production environment, use UNComponentsEnvironment.production

2. Add the Bottom Sheet Component

The UNBottomSheetComponent is required when Unit components are visible. Place it in your root component:

import React from 'react';
import { UNBottomSheetComponent } from 'react-native-unit-components';

export default function YourRootComponent() {
	return (
		<>
			<YourComponents />
			<UNBottomSheetComponent />
		</>
	);
}

3. Add the UNWhiteLabelAppComponent to your view hierarchy:

import React from 'react';
import { View } from 'react-native';
import { UNWhiteLabelAppComponent } from 'react-native-unit-components';

<View style={{ height: '100%' }}>
	<UNWhiteLabelAppComponent
		jwtToken='demo.jwt.token'
	/>
</View>

Note: demo.jwt.token is a real value you can use to preview the component without any setup.

UNWhiteLabelAppComponent props:

Name	Type	Required	Description
customerToken	string	NO	Customer token.
jwtToken	string	NO	JWT token.
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.

Note

You should create your own jwtToken, or use an existing customerToken. No reason to use both. None of the tokens are mandatory, but you should provide at least one of them.

Authentication

Up to 2 hours

In order to seamlessly authenticate with the component, you need to pass it a JWT, that allows us to identify your user and verify that they are logged in.

Unit will not ask the user to log in using a separate set of credentials. However, before performing any sensitive banking activities, we will OTP the user.

In sandbox, please use code 000001 to complete the OTP.

Configuring your identity provider

20 minutes

Log into Unit's dashboard.

Under Developer, go to Settings.
In the Authentication tab, choose your identity provider from the Provider dropdown.
Paste the JWKS path into the JWKS field.

Passing The JWT

10 minutes

Pass your JWT to the component (see example above), replacing the static token that was previously there.

If the JWT token is recognized as an existing user, the user will see their account. If the JWT token is recognized as a new user, the user will be presented with the application form.

In sandbox, please use a unique phone number with each application submission.

Cleanup

10 minutes

Make sure to clear user data when the user logs out from your app:

UnitSDK.cleanUserData();

Installation

5 minutes

Make sure mavenCentral() is included in the project settings.gradle file inside dependencyResolutionManagement repositories:

mavenCentral()

Add the un-components dependency to your project:

dependencies {
    implementation 'co.unit:un-components:3.5.1'
}

Jetpack Compose

If your app uses Jetpack Compose, add the un-components-compose artifact alongside un-components:

dependencies {
    implementation 'co.unit:un-components:3.5.1'
    implementation 'co.unit:un-components-compose:3.5.1'
}

un-components-compose provides @Composable wrappers for all SDK components with the same names and parameters as their Fragment counterparts. Your Activity must extend FragmentActivity (or AppCompatActivity, which extends it). Apps that do not use Compose only need un-components.

Embedding

10 minutes

1. Initialize Unit SDK

Initialize the SDK in your main activity's onCreate method:

import co.unit.un_components.api.UnitComponentsSdk

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        val unitSdkManager = UnitComponentsSdk.manager
        val initializationSettings = UNComponentsInitializationSettingsBuilder()
            .environment(UNComponentsEnvironment.Sandbox)
            .webVersioningStrategy(UNWebVersioningStrategy.Latest)
        
        unitSdkManager.initialize(initializationSettings)
    }
}

Note

For production environment, use UNComponentsEnvironment.Production

2. Add the WhiteLabelApp Component

To get the WhiteLabelApp Component, call the getWhiteLabelAppComponent method of UnitComponentsSdk.manager.ui.views (Fragment), or use the UNWhiteLabelAppComponent @Composable from un-components-compose (Compose).

Fragment
Compose

import android.os.Bundle
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import androidx.fragment.app.Fragment
import co.unit.un_components.api.UnitComponentsSdk
import co.unit.un_components.components.UNWhiteLabelAppComponent
import co.unit.un_components.core.models.UNWhiteLabelAppToken

class WhiteLabelAppFragment : Fragment() {
    private var unWhiteLabelAppComponent: UNWhiteLabelAppComponent? = null

    override fun onCreateView(
        inflater: LayoutInflater, 
        container: ViewGroup?, 
        savedInstanceState: Bundle?
    ): View? {
        unWhiteLabelAppComponent = UnitComponentsSdk.manager.ui.views.getWhiteLabelAppComponent(
            token = UNWhiteLabelAppToken.JwtToken("demo.jwt.token")
        )

        val fragmentLayout = inflater.inflate(R.layout.FILE_NAME, container, false)
        childFragmentManager.beginTransaction()
            .replace(R.id.CONTAINER_NAME, unWhiteLabelAppComponent as Fragment)
            .commitNow()
        return fragmentLayout
    }
}

import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.foundation.layout.fillMaxSize
import co.unit.un_components.compose.UNWhiteLabelAppComponent
import co.unit.un_components.core.models.UNWhiteLabelAppToken

@Composable
fun WhiteLabelAppScreen() {
    UNWhiteLabelAppComponent(
        modifier = Modifier.fillMaxSize(),
        token = UNWhiteLabelAppToken.JwtToken("demo.jwt.token"),
    )
}

Note: demo.jwt.token is a real value you can use to preview the component without any setup.

UNWhiteLabelAppComponent props:

Name	Type	Required	Description
token	UNWhiteLabelAppToken	YES	A sealed class that holds the token and represents the token type (Customer Token or JWT Token).
theme	String	NO	A URL that specifies the UI configuration.
language	String	NO	A URL that specifies the language configuration.

UNWhiteLabelAppToken:

UNWhiteLabelAppToken is a sealed class that represents the token type (Customer Token or JWT Token) and holds the token. After generating the token, as mentioned above, instantiate the UNWhiteLabelAppToken class with it and pass it to the getWhiteLabelAppComponent method.

sealed class UNWhiteLabelAppToken(val token: String) {
    class JwtToken(token: String) : UNWhiteLabelAppToken(token)
    class CustomerToken(token: UNCustomerToken) : UNWhiteLabelAppToken(token)
}

Authentication

Up to 2 hours

In order to seamlessly authenticate with the component, you need to pass it a JWT, that allows us to identify your user and verify that they are logged in.

Unit will not ask the user to log in using a separate set of credentials. However, before performing any sensitive banking activities, we will OTP the user.

In sandbox, please use code 000001 to complete the OTP.

Configuring your identity provider

20 minutes

Log into Unit's dashboard.

Under Developer, go to Settings.
In the Authentication tab, choose your identity provider from the Provider dropdown.
Paste the JWKS path into the JWKS field.

Passing The JWT

10 minutes

Pass your JWT to the component (see example above), replacing the static token that was previously there.

If the JWT token is recognized as an existing user, the user will see their account. If the JWT token is recognized as a new user, the user will be presented with the application form.

In sandbox, please use a unique phone number with each application submission.

Cleanup

10 minutes

Make sure to clear user data when the user logs out from your app:

UnitComponentsSdk.manager.authentication.cleanUserData()

Requirements

Name	Version
iOS	>= 14.0

Installation

5 minutes

Swift Package Manager

Add the package dependency to your project: Navigate to File > Swift Packages > Add Package Dependency.
Enter the package repository URL: https://github.com/unit-finance/unit-ios-components-pod.git.
Specify the version: 3.0.0
Add the package to your target.

Cocoapods

Set the dependency in your Podfile as follows: pod 'UnitComponents', '3.0.0'
Execute pod install in Terminal.

Embedding

10 minutes

1. Initialize Unit SDK

Initialize the SDK in your AppDelegate file:

import UIKit
import UNComponents

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        let unitSdkManager = UnitComponentsSDK.manager
        let configurationSettings = UNComponentsSDKConfigurationBuilder()
            .environment(UNComponentsEnvironment.sandbox)
            .webVersioningStrategy(UNWebVersioningStrategy.latest)
        
        unitSdkManager.initialize(with: configurationSettings)
        
        return true
    }
}

Note

For production environment, use UNComponentsEnvironment.production

2. Add the WhiteLabelApp Component

To get the WhiteLabelApp Component view, call the getWhiteLabelAppComponent method of UnitComponentsSDK.manager.ui.views.

import UIKit
import UNComponents

class WhiteLabelAppViewController: UIViewController {
    private var whiteLabelAppComponent: UNWhiteLabelAppView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let unViews = UnitComponentsSDK.manager.ui.views
        
        whiteLabelAppComponent = unViews.getWhiteLabelAppComponent(
            token: UNWhiteLabelAppToken.jwtToken("demo.jwt.token")
        )
        
        view.addSubview(whiteLabelAppComponent)
        whiteLabelAppComponent.snp.makeConstraints { make in
            make.edges.equalToSuperview()
        }
    }
}

Note: demo.jwt.token is a real value you can use to preview the component without any setup.

UNWhiteLabelAppComponent props:

Name	Type	Required	Description
token	UNWhiteLabelAppToken	YES	An enum that holds the token and represents the token type (Customer Token or JWT Token).
additionalSettings	UNWhiteLabelAppViewSettingsProtocol	NO	Advanced optional settings.
theme	String	NO	A URL that specifies the UI configuration.
language	String	NO	A URL that specifies the language configuration.
callbacks	UNWhiteLabelAppComponentCallbacks	NO	Callbacks to interact with the Managed Solution component.

UNWhiteLabelAppToken:

UNWhiteLabelAppToken is an enum that represents the token type (Customer Token or JWT Token) and holds the token. After generating the token, as mentioned above, instantiate the UNWhiteLabelAppToken enum with it and pass it to the getWhiteLabelAppComponent method.

public enum UNWhiteLabelAppToken {
    case jwtToken(String)
    case customerToken(UNCustomerToken)
}

Authentication

Up to 2 hours

In order to seamlessly authenticate with the component, you need to pass it a JWT, that allows us to identify your user and verify that they are logged in.

Unit will not ask the user to log in using a separate set of credentials. However, before performing any sensitive banking activities, we will OTP the user.

In sandbox, please use code 000001 to complete the OTP.

Configuring your identity provider

20 minutes

Log into Unit's dashboard.

Under Developer, go to Settings.
In the Authentication tab, choose your identity provider from the Provider dropdown.
Paste the JWKS path into the JWKS field.

Passing The JWT

10 minutes

Pass your JWT to the component (see example above), replacing the static token that was previously there.

If the JWT token is recognized as an existing user, the user will see their account. If the JWT token is recognized as a new user, the user will be presented with the application form.

In sandbox, please use a unique phone number with each application submission.

Cleanup

10 minutes

Make sure to clear user data when the user logs out from your app:

UnitComponentsSDK.manager.authentication.cleanUserData()

Pre-filling end-user information (recommended)

You can reduce friction in Managed Banking by returning known customer data from your own API. The first time an end user (identified by the JWT sub claim) starts the banking application flow, Unit calls your HTTPS Application Prefill endpoint; your server responds with a JSON:API document of type whiteLabelAppEndUserConfig. Configure the URL under Settings → Managed Solutions → Callbacks in your sandbox or production Unit Dashboard (field: Application Prefill Endpoint), and review the full HTTP contract in Pre filling end-user information.

Embedding

Embedding​

Authentication​

Configuring your identity provider​

Passing The JWT​

Attributes​

Cleanup​

Content Security Policy​

Installation​

Embedding​

1. Initialize Unit SDK​

2. Add the Bottom Sheet Component​

3. Add the UNWhiteLabelAppComponent to your view hierarchy:​

UNWhiteLabelAppComponent props:​

Authentication​

Configuring your identity provider​

Passing The JWT​

Cleanup​

Installation​

Jetpack Compose​

Embedding​

1. Initialize Unit SDK​

2. Add the WhiteLabelApp Component​

UNWhiteLabelAppComponent props:​

UNWhiteLabelAppToken:​

Authentication​

Configuring your identity provider​

Passing The JWT​

Cleanup​

Requirements​

Installation​

Swift Package Manager​

Cocoapods​

Embedding​

1. Initialize Unit SDK​

2. Add the WhiteLabelApp Component​

UNWhiteLabelAppComponent props:​

UNWhiteLabelAppToken:​

Authentication​

Configuring your identity provider​

Passing The JWT​

Cleanup​

Pre-filling end-user information (recommended)

Embedding

Authentication

Configuring your identity provider

Passing The JWT

Attributes

Cleanup

Content Security Policy

Installation

Embedding

1. Initialize Unit SDK

2. Add the Bottom Sheet Component

3. Add the UNWhiteLabelAppComponent to your view hierarchy:

UNWhiteLabelAppComponent props:

Authentication

Configuring your identity provider

Passing The JWT

Cleanup

Installation

Jetpack Compose

Embedding

1. Initialize Unit SDK

2. Add the WhiteLabelApp Component

UNWhiteLabelAppComponent props:

UNWhiteLabelAppToken:

Authentication

Configuring your identity provider

Passing The JWT

Cleanup

Requirements

Installation

Swift Package Manager

Cocoapods

Embedding

1. Initialize Unit SDK

2. Add the WhiteLabelApp Component

UNWhiteLabelAppComponent props:

UNWhiteLabelAppToken:

Authentication

Configuring your identity provider

Passing The JWT

Cleanup