React Native SDK

Installation#

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

Using yarn:

$ yarn add react-native-unit-components react-native-webview

Usage#

Initialize Unit SDK#

Call UnitSDK.init in your root component with the required environment and your source. By doing so you will also helps us improve the app performance.

The UNEnvironment enum should be used.

enum UNEnvironment {  sandbox,  production}

Input:#

Name	Type	Required	Description
env	UNEnvironment	YES	Unit environment.
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.
fonts	UNFonts	NO	UNFonts object that specifies your custom fonts.
webVersioningStrategy	UNWebVersioningStrategy	NO	Web SDK version management strategy.

Example:#

import React, { useEffect } from 'react';import { UnitSDK, UNEnvironment } from 'react-native-unit-components';
const THEME = 'A URL that specifies the UI configuration';const LANGUAGE = 'A URL that specifies the language configuration.';
export default function YourRootComponent() {  useEffect(() => {    UnitSDK.init(UNEnvironment.production, THEME, LANGUAGE, CUSTOM_FONTS);  }, [])}

Setup Fonts:#

The UNFonts object is a dictionary-like structure where each key is a font family, and each font family can have multiple variants, currently distinguished by weight.

File Naming Convention#

Your font file must adhere to the naming convention: <family-name>-<font-weight>. This standardization is critical for the SDK to correctly identify and utilize the fonts.

Integrating Custom Fonts into a React Native Project:#

Add and link your font files to your React Native project, following the normal procedures for asset inclusion. You can follow these step-by-step instructions:

1. Adding Font Files#

First, add your custom font files to a directory within your project. Typically, this would be an assets/fonts/ directory.

2. Configure Asset Inclusion#

Create Config File: If it does not already exist, create a configuration file at the root directory of your project. Name this file react-native.config.js.
Add Configuration: Open the react-native.config.js file and add the following lines within module.exports:
```
module.exports = {    // Your existing configuration here
    assets: ['./assets/fonts/'],};
```

3. Linking the Assets#

Now, you need to link these assets to your project. This process will vary based on your React Native version.

For React Native Version <= 0.69 Run one of the following commands:
```
npx react-native link
```
or
```
yarn react-native link
```
For React Native Version > 0.69 Run one of the following commands:
```
npx react-native-asset
```

4. Verification#

iOS: Open your info.plist file and verify that the font files have been added under the key UIAppFonts.
Android: Navigate to your Android assets directory and ensure that a new font file has been created.

Define the UNFonts Object#

After integrating your fonts, the next step is to define the UNFonts object. Below is the schema for UNFonts and its nested types:

export type UNFonts = {  [fontFamily: string]: UNFontData[];}
export type UNFontData = {  fontWeight: FontWeight;  sources: UNFontSource[];}
export type UNFontSource = {  fileName: string;  assetDirRelativePath: string;  format?: string;  // Optional, might be effective when fallbacks are used}

Example#

Here's a simple example to illustrate how you might define a UNFonts object:

const CustomFonts: UNFonts = {  "Helvetica": [    {      fontWeight: FontWeight.Regular,      sources: [{ fileName: "Helvetica-Regular.ttf", assetDirRelativePath: "fonts/"}]    },    {      fontWeight: FontWeight.Bold,      sources: [{ fileName: "Helvetica-Bold.ttf", assetDirRelativePath: "fonts/" }]    }  ],  "Arial": [    {      fontWeight: FontWeight.Regular,      sources: [{ fileName: "Arial-Regular.ttf", assetDirRelativePath: "fonts/"}]    }  ]};

Web SDK Versioning Strategy Guide#

It's essential to understand that this SDK utilizes the web SDK views for certain components.

To give you optimal flexibility in managing the Web SDK versions, we've devised a strategy that allows you to either keep your SDK up-to-date or fixate on a particular version. To set your preferred versioning approach, using the type UNWebVersioningStrategy. Below are the options you can select from:

Exact Versioning -

  type: UNVersioningStrategyType.exact;  major: number;  minor: number;  patch: number;

This method allows you to lock onto a specific version that suits your needs.

Up to Next Minor -
```
  type: UNVersioningStrategyType.upToNextMinor;  major: number;  minor: number;
```
- This is the default and recommended approach. While it keeps your SDK updated with minor patches, a manual update is needed for minor version changes.
Up to Next Major -
```
  type: UNVersioningStrategyType.upToNextMajor;  major: number;
```
- With this strategy, your SDK will automatically update until there's a major version change.

For a comprehensive understanding, refer to our Web SDK - Versioning Guide.

const myWebSdkStrategy: UNWebVersioningStrategy = {  type: UNVersioningStrategyType.upToNextMinor,  major: 1,  minor: 2,};

For the latest SDK, the latest webVersioningStrategy is upToNextMinor(major: 1, minor: 3).

Bottom Sheet Component#

The UNBottomSheetComponent is a View that our SDK controls in order to show menus and forms in your application. It is mandatory to have one UNBottomSheetComponent when our components are visible.

The UNBottomSheetComponent has an absolute position and should be able to take the full width and the height of the screen. We recommend to place the UNBottomSheetComponent in your root component of your application.

The structure of your root component might look as follows:#

import React, { useEffect } from 'react';import { UNBottomSheetComponent } from 'react-native-unit-components';
export default function YourRootComponent() {  return (    <>      <YourComponents />      <UNBottomSheetComponent />    </>  );}

Card Component#

UNCardComponent props:#

Name	Type	Required	Description
customerToken	string	YES	A Unit Customer token.
cardId	string	YES	Unit card id.
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.
hideActionsMenuButton	boolean	NO	Hide menu button in case value is true
hideCardTitle	boolean	NO	Hide card title in case value is true
hideSensitiveDataButton	boolean	NO	Hide sensitive data button in case value is true
learnMoreUrl	string	NO	A “Learn more” URL on the report lost/close card info note.
onStatusChanged	(card: UNCardData) => void	NO	Callback for card status changes.
onLoad	`(response: UNOnLoadResponse<UNCardData>) => void`	NO	Callback for a loaded component
onCardActivated	(card: UNCardData) => void	NO	Callback for card activated.
pushProvisioningModule	typeof NativeModules	NO	A Native Module that implements Visa's push provisioning

Example:#

import React from 'react';import { UNCardComponent, UNCardData } from 'react-native-unit-components';import { NativeModules } from 'react-native';const { PushProvisioningModule } = NativeModules;

export default function YourComponent() {  return (    <UNCardComponent      cardId={'632197'}      customerToken={/*Customer token here*/}      onStatusChanged={(card: UNCardData) => { console.log(card) }}      onCardActivated={(card: UNCardData) => { console.log(card) }}      pushProvisioningModule={PushProvisioningModule}      onLoad={(response: UNOnLoadResponse<UNCardData>) => { console.log(response) }}    />  );}

Incoming Events:#

In some cases, the default menu button won't fit into the design of an application. By using the openActionsMenu() method, it's possible to open the card actions bottom sheet from a custom button.
Important Note: one can use the openActionsMenu() only after UNCardComponent is loaded. (can be verified by onLoad callback)

Example:#

import { UNCardComponent, CardRef } from 'react-native-unit-components';
...
const cardRef = useRef<CardRef>(null);
...
const openActionsMenu = () => {  cardRef.current?.openActionsMenu();};
...
<UNCardComponent  ref={cardRef}  cardId={"4242"}  customerToken={''}/>

It's also possible to create your own menu and call card actions from it. Use openAction(action: UNCardMenuAction) method and send inside an action you want to perform. Use API Docs in order to understand which actions could be applied for any particular card statuses.
Example:#


import { UNCardMenuAction } from 'react-native-unit-components';
// .......
const openAction = (action: UNCardMenuAction) => {  cardRef.current?.openAction(action);};
// .......

You can choose to implement your own show / hide card sensitive data button. In this case use 'showSensitiveData()' method to show sensitive data and 'hideSensitiveData()' method to hide it.
Example:#



// .......
const showSensitiveData = () => {    cardRef.current?.showSensitiveData();  }; const hideSensitiveData = () => {    cardRef.current?.hideSensitiveData();  };
// .......

Adding a card to Wallet (Optional)#

Start by following the Add card to wallet instructions to use this capability. Then pass the PushProvisioningModule as a prop to Unit's Card Component. This will let the SDK get wallets and start card provisioning for you once the native Add to Wallet button was pressed. Then, you can add a card to the wallet using the "Manage Apple Wallet" or "Manage Google Wallet" tab in the Card Components's native menu or using an AddToWallet as the Incoming event action.

Book Payment Component#

UNBookPaymentComponent props:#

Name	Type	Required	Description
customerToken	string	YES	A Unit Customer token.
accountId	string	YES	Unit account id. The account from which money is being sent.
counterPartyAccountId	string	YES	Unit account id. The account which will receive money.
counterPartyName	string	YES	Name of the counterparty. This is the name that will be displayed in the Book Payment UI during the transfer.
isSameCustomer	boolean	NO	Stating whether both accounts belong to the same customer. Allows fetching additional information about the counterparty account. Default "false"
isAutoFocus	boolean	NO	Auto-focus the money input field once the component is mounted. Default `false`
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.
onPaymentCreated	(bookPayment: UNBookPaymentData) => void	NO	Callback for the created bookPayment.
onLoad	`(response: UNOnLoadResponse<UNAccountData>) => void`	NO	Callback for handling onload event, also usable for error handling.

Example:#

import React from 'react';import { UNBookPaymentComponent, UNBookPaymentData, UNAccountData} from 'react-native-unit-components';
export default function YourComponent() {  return (    <UNBookPaymentComponent      customerToken={/*Customer token here*/}      accountId={'1105561'}      counterPartyAccountId={'1105562'}      counterPartyName={'Peter Parker"'}      isSameCustomer={true}      onPaymentCreated={(bookPayment: UNBookPaymentData) => { console.log(bookPayment) }}      onLoad={(response: UNOnLoadResponse<UNAccountData>) => { console.log(response) }}    />  );}

Activity Component#

UNActivityComponent props:#

Name	Type	Required	Description
customerToken	string	YES	A Unit Customer token.
accountId	string	NO	Unit account id. The account for which the activity will be shown. If not specified: the activity of the customer (all accounts) will be shown
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.
hideFilterButton	boolean	NO	Hide filter button in case value is true
queryFilter	string	NO	Query for filtering transactions and authorizations: Transactions, Authorizations
paginationType	UNActivityComponentPaginationType	NO	Defines the method by which additional content is loaded. Possible values: `infiniteScroll` (default), `pagination`
transactionsPerPage	number	NO	Number of transactions to fetch on each page or scroll to bottom. Also acts as initial number of transactions to fetch. The default is `8` for pagination and `15` for infinite scroll
onLoad	`(response: UNOnLoadResponse<UNActivityOnLoadData>) => void`	NO	Callback for handling onload event, also usable for error handling.

Example:#

import React from 'react';import { UNActivityComponent, UNActivityOnLoadData } from 'react-native-unit-components';
export default function YourComponent() {  return (    <UNActivityComponent      customerToken={/*Customer token here*/}      accountId={'1105561'}      onLoad={(response: UNOnLoadResponse<UNActivityOnLoadData>) => { console.log(response) }}      queryFilter={'filter[since]=2023-01-01T00:00:00.000Z&filter[until]=2023-04-26T00:00:00.000Z&sort=-createdAt'}    />  );}

Account Component#

UNAccountComponent props:#

Name	Type	Required	Description
customerToken	string	YES	A Unit Customer token.
accountId	string	NO	Unit account id. The account to show, when not provided, one of the customer's accounts will be shown.
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.
hideActionsMenuButton	boolean	NO	Hide actions menu button in case value is true
hideSelectionMenuButton	boolean	NO	Hide selection menu button in case value is true
onAccountChanged	(account: UNAccountData) => Void	NO	Callback for account changes.
onLoad	`(response: UNOnLoadResponse<[UNAccountData]>) => void`	NO	Callback for a loaded component

Example:#

import React from 'react';import { UNAccountComponent, UNAccountData } from 'react-native-unit-components';
export default function YourComponent() {  return (    <UNAccountComponent      customerToken=""      accountId="1105561"      onAccountChanged={(account: UNAccountData) => console.log('Account changed', account)}      onLoad={(response: UNOnLoadResponse<[UNAccountData]>) => { console.log(response) }}    />  );}

Incoming Events:#

In some cases, the default menu button won't fit into the design of an application. By using the openActionsMenu() method, it's possible to open the account actions bottom sheet from a custom button.
Important Note: one can use the openActionsMenu() only after UNAccountComponent is loaded. (can be verified by onLoad callback)

Example:#

import { UNAccountComponent, UNAccountRef } from 'react-native-unit-components';
...
const accountRef = useRef<UNAccountRef>(null);
...
const openAccountMenu = () => {    accountRef.current?.openActionsMenu();};
...
<UNAccountComponent  ref={accountRef}  accountId={"4242"}  customerToken={''}/>

It's also possible to create your own menu and call account actions from it. Use openAction(action: UNAccountMenuAction) method and send inside an action you want to perform. Use Unit's API Docs in order to understand which actions could be applied.

Example:#

import { UNAccountMenuAction } from 'react-native-unit-components';
// .......
 const openAction = (action: UNAccountMenuAction) => {     accountRef.current?.openAction(action); };
// .......

Check Deposit Component#

Prerequirements:#

To enable check scanning with our SDK, please request the camera permissions in your application. Android: navigate to the AndroidManifest.xml file and insert the following:

    <uses-permission android:name="android.permission.CAMERA" />

iOS: navigate to the Info.plist file and insert the camera permission key:

    <key>NSCameraUsageDescription</key>    <string>Your custom message requesting permission from the user</string>

UNCheckDeposit props:#

Name	Type	Required	Description
accountId	string	YES	Unit account id. The account to deposit to.
fee	number	YES	Fee changed for making the check deposit, will be presented to the user.
customerToken	string	YES	A Unit Customer token.
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.
onDepositCreated	(depositCheckData: UNCheckDeposit) => Void	NO	Occurs when a check deposit is successfully created
onRestartRequest	(depositCheckData: UNCheckDeposit) => Void	NO	Occurs when "Deposit another check" is clicked
onLoad	`(response: UNOnLoadResponse<UNAccountData>) => void`	NO	Callback for a loaded component

Example:#

import React from 'react';import { UNCheckDepositComponent, UNCheckDepositData, UNAccountData, UNOnLoadResponse } from 'react-native-unit-components';
export default function YourComponent() {  return (    <UNCheckDepositComponent      customerToken={"<Your customer token>"}      accountId={"424242"}      fee={1.5}      onDepositCreated={(checkData: UNCheckDepositData) => console.log('Check deposit created:' , checkData)}      onRestartRequest={(checkData: UNCheckDepositData) => console.log('Restart Request. Check data: ', checkData)}      onLoad={(response: UNOnLoadResponse<UNAccountData>) => { console.log(response) }}    />  );}

ACH Debit Payment Component#

Prerequirements#

This component is using the Plaid API to connect your users' financial accounts using the Plaid integration. You must have a Plaid account and provide your Plaid credentials in the Unit Sandbox Dashboard and Unit Production Dashboard.

Installation of the SDK#

In your project directory, run:

With npm:

npm install --save react-native-plaid-link-sdk

With yarn:

yarn add react-native-plaid-link-sdk

Installation for iOS#

Add Plaid to your project’s Podfile as follows (likely located at ios/Podfile).

pod 'Plaid', '~> <insert latest version>'

Then install your CocoaPods dependencies:

(cd ios && pod install)

Installation for Android#

Please provide your applicationId to Unit, which will be utilized for generating a link token and redirecting Plaid Activity to your application.

UNACHDebitComponent props:#

Name	Type	Required	Description
customerToken	string	YES	A Unit Customer token.
accountId	string	YES	Unit account id. The account from which money is being sent.
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.
fee	number	NO	Bill your counterparty for his activity.
isAutoFocus	boolean	NO	Auto-focus the 'add new recipient' button once the component is mounted. Default "false"
sameDay	boolean	NO	Enables Same Day ACH
onPaymentCreated	(data: UNACHData) => Void	NO	Callback for ACH payment created
onLoad	`(response: UNOnLoadResponse<UNACHOnLoadData>) => void`	NO	Callback for a loaded component

Example:#

import React from 'react';import { UNACHDebitComponent, UNACHData, UNACHOnLoadData } from 'react-native-unit-components';
export default function YourComponent() {  return (    <UNACHDebitComponent      customerToken={/*Customer token here*/}      accountId={'1105561'}      onPaymentCreated={(payment: UNACHData) => { console.log(payment) }}      onLoad={(response: UNOnLoadResponse<UNACHOnLoadData>) => { console.log(response) }}    />  );}

ACH Credit Payment Component#

Prerequirements:#

If you wish to use plaid in this component, please follow the pre-requisites of ACHDebitComponent .

UNACHCreditComponent props:#

Name	Type	Required	Description
customerToken	string	YES	A Unit Customer token.
accountId	string	YES	Unit account id. The account from which money is being sent.
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.
fee	number	NO	Bill your counterparty for his activity.
withPlaid	boolean	NO	Use the Plaid API to connect your users' financial accounts. To utilize this integration, follow the prerequirements and set the value as `true`. Default `false`.
isAutoFocus	boolean	NO	Auto-focus the 'add new recipient' button once the component is mounted. Default "false"
sameDay	boolean	NO	Enables Same Day ACH
onPaymentCreated	(data: UNACHData) => Void	NO	Callback for ACH payment created
onLoad	`(response: UNOnLoadResponse<UNACHOnLoadData>) => void`	NO	Callback for a loaded component

Example:#

import React from 'react';import { UNACHCreditComponent, UNACHData, UNACHOnLoadData } from 'react-native-unit-components';
export default function YourComponent() {  return (    <UNACHCreditComponent      customerToken={/*Customer token here*/}      accountId={'1105561'}      onPaymentCreated={(payment: UNACHData) => { console.log(payment) }}      onLoad={(response: UNOnLoadResponse<UNACHOnLoadData>) => { console.log(response) }}    />  );}

Multiple Cards Component#

UNMultipleCardsComponent props:#

Name	Type	Required	Description
customerToken	string	YES	A Unit Customer token.
theme	string	NO	A URL that specifies the UI configuration.
language	string	NO	A URL that specifies the language configuration.
paginationType	UNMultipleCardsComponentPaginationType	NO	Defines how more content is loaded. Possible values: `infiniteScroll` (default), `pagination`
cardsPerPage	number	NO	Number of cards to fetch on each page or scroll to bottom. Also acts as initial number of cards to fetch. The default is `8` for pagination and `15` for infinite scroll
hideTitle	boolean	NO	Hide title in case value is `true`
disableCardClick	boolean	NO	When true, will not publish a `onCardClicked` event when a row is clicked. Possible values: `true` / `false` (default)
queryFilter	string	NO	Query for filtering Cards
onLoad	`(response: UNOnLoadResponse<UNMultipleCardsOnLoadData>) => void`	NO	Callback for a loaded component
onCardClicked	(card: UNCardData) => void	NO	Occurs when a card row is clicked

Example:#

import React from 'react';import {  UNMultipleCardsComponent,  UNCardData,  UNMultipleCardsComponentPaginationType,  UNMultipleCardsOnLoadData} from 'react-native-unit-components';

export default function YourComponent() {  return (    <UNMultipleCardsComponent      customerToken={/*Customer token here*/}      paginationType={UNMultipleCardsComponentPaginationType.pagination}      cardsPerPage={4}      onCardClicked={(card: UNCardData) => { console.log(card) }}      onLoad={(response: UNOnLoadResponse<UNMultipleCardsOnLoadData>) => { console.log(response) }}    />  );}

Flows#

Add card to wallet flow#

Start by following the Add card to wallet instructions to use this flow.

Call UnitSDK.setPushProvisioningModule(PushProvisioningModule) with your PushProvisioningModule Native Module.

After that, you can add a card to Apple or Google Wallet by calling the Unit SDK's startPushProvisioning(cardId: string, customerToken: string).

Example:#

UnitSDK.ui.flows.startPushProvisioning(YOUR_CARD_ID, YOUR_CUSTOMER_TOKEN);

Additional Capabilities#

Add card to wallet#

This capability can be used with the Card Component or without it, as a separate flow. Complete the add to wallet guide for React Native, skipping the last module access from javascript, to use this capability.

Error Handling#

By using unitOnLoad callback you can get a result of type UNOnLoadResponse for the requested component. OnError - you will get an enum UNError that consist of several cases.

UNError:#

fields	Description
errors: UNErrorData[]	Report UNError on errors that happen in loading time

UNErrorData:#

Name	Type	Description
status	String	A Unit-specific code, uniquely identifying the error type
title	String?	The title of the error type
detail	String?	Additional information about the error.
details	String?	Additional information about the error.
meta	{ supportId: String }?	meta.supportId unique error identifier to be used for further investigation

Note: An "error object" MUST contain a title and the HTTP status code members.

Example:#

    import { UNCardComponent, UNCardData, UNOnLoadResponse } from 'react-native-unit-components';    ....    const handleCardOnLoad = (response: UNOnLoadResponse<UNCardData>) => {      if ('errors' in response) {        console.error('ERROR unitOnLoad: ', response.errors);        return;      }      if ('data' in response) {        const cardData: UNCardData = response.data;        console.log('Success, data:', cardData)        return;      }      return;    }    ....    return (      ...      <UNCardComponent        cardId={'632197'}        customerToken={''}        onLoad={handleCardOnLoad}      />      ...    )

Components working together#

Unit components within the same app can effectively communicate with each other. They can automatically exchange messages and trigger events to update relevant data in other components.

For instance, the Payment components and Activity components can work together such that, after a payment has been processed, the new transactions are automatically displayed on the Activity component.

Similarly, the Payment components and Account components can communicate such that, after a payment has been made, the account balance is updated on the Account component.

In some cases, a component may need to be updated in response to an event that is triggered by another component.

For example, if a customer has multiple accounts, the app may have an Account component and an Activity component that displays the activity of a selected account.

import React from 'react';import { View } from 'react-native';import { UNAccountComponent, UNActivityComponent } from 'react-native-unit-components';
export default function YourComponent() {    const [activityAccountId, setActivityAccountId] = useState("475891")
    return (        <View>            <UNAccountComponent                customerToken={/*Customer token here*/}                accountId={"475891"}                onAccountChanged={(account) => {                  console.log("account changed to", account)                  setActivityAccountId(account.id)                }}            />
          <UNActivityComponent                customerToken={/*Customer token here*/}                accountId={activityAccountId}          />        </View>    )}