React Native SDK (v4.0+)

This version of the React Native SDK is intended for use with the network user identifier aeroPassUserUuid.

Introduction

This React Native SDK provides an interface to load Aerosync-UI in a React Native application. Securely link your bank account through your bank's website. Log in with a fast, secure, and tokenized connection. Your information is never shared or sold.

1. Create a User

The Aerosync + Aeronetwork SDKs require a user identifier, aeroPassUserUuid, to be passed to the widget on launch. Follow the guide here to create a new user and access the user's aeroPassUserUuid.

2. Install Aerosync React Native SDK

Install the SDK together with its required peer dependency, react-native-webview (v13.6.2+):

npm install aerosync-react-native-sdk react-native-webview

iOS

cd ios && pod install

Android

Autolinking handles the native setup. Make sure your AndroidManifest.xml includes the internet permission:

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

3. Minimal example

import { useState } from 'react';
import { Button, Modal, SafeAreaView, useColorScheme } from 'react-native';
import {
  AeroSyncWidget,
  type SuccessPayload,
  type WidgetEventType,
} from 'aerosync-react-native-sdk';

export default function AddBankScreen() {
  const [isWidgetOpen, setIsWidgetOpen] = useState(false);
  const isDarkTheme = useColorScheme() === 'dark';

  // Values from your backend (see section 4)
  const token = 'AEROSYNC_TOKEN';
  const aeroPassUserUuid = 'AEROPASS_USER_UUID';
  const configurationId = 'CONFIGURATION_ID'; // optional

  const onLoad = () => console.log('onLoad');

  const onClose = () => {
    console.log('onClose');
    setIsWidgetOpen(false);
  };

  const onSuccess = (event: SuccessPayload) => {
    if ('accounts' in event) {
      // Multi-account response (see section 6)
      event.accounts.forEach(({ connectionId }) => console.log(connectionId));
    } else {
      // Single-account response
      console.log(event.connectionId);
    }
    setIsWidgetOpen(false);
  };

  const onEvent = (event: WidgetEventType) => console.log('onEvent', event);

  const onError = (event: string) => console.log('onError', event);

  return (
    <SafeAreaView style={{ flex: 1 }}>
      <Button title="Link bank" onPress={() => setIsWidgetOpen(true)} />

      <Modal visible={isWidgetOpen} animationType="slide">
        <SafeAreaView style={{ flex: 1 }}>
          <AeroSyncWidget
            token={token}
            environment="sandbox" // 'sandbox' | 'production'
            aeroPassUserUuid={aeroPassUserUuid}
            configurationId={configurationId}
            deeplink="yourapp://aerosync"
            theme={isDarkTheme ? 'dark' : 'light'}
            customWebViewProps={{
              style: { backgroundColor: isDarkTheme ? '#0E0E15' : '#FFFFFF' },
            }}
            onLoad={onLoad}
            onClose={onClose}
            onSuccess={onSuccess}
            onEvent={onEvent}
            onError={onError}
          />
        </SafeAreaView>
      </Modal>
    </SafeAreaView>
  );
}
📘

Upgrading from v3 or earlier

AeroSyncWidget is a named export. The default BankLink export was removed in v3.0.2, so import BankLink from 'aerosync-react-native-sdk' no longer works. Replace it with import { AeroSyncWidget } from 'aerosync-react-native-sdk'.

4. Aerosync SDK configuration

ParameterTypeRequiredDescription
tokenstringYesRequest an Aerosync token using the POST /token_widget endpoint. Reference: https://sync.dev.aero.inc/reference/post_v2-token-widget
environmentstringYesPermitted values are sandbox and production.
deeplinkstringYesAerosync redirects to this link in your mobile app after authentication to resume the workflow.
aeroPassUserUuidstringYesAeronetwork user id.
configurationIdstringNoUnique ID that represents the client, used to apply customization.
theme'light' | 'dark'NoWidget theme. Defaults to light. See 4.1.
customWebViewPropsobjectNoAdditional props passed to the underlying react-native-webview component. Use style.backgroundColor to set the background color while the widget loads.
manualLinkOnlybooleanNoIf true, the user can only link their bank manually. Defaults to false.
handleMFAbooleanNoHandle the additional MFA for the balance refresh workflow.
jobIdstringNoUnique identifier for the current job. Required if handleMFA is true.
connectionIdstringNoUnique identifier for the current Aerosync connection. Required if handleMFA is true.

4.1 Dark mode configuration

Dark mode uses two props:

  • theme sets the widget's theme (light or dark).
  • customWebViewProps.style.backgroundColor sets the WebView background shown while the widget loads. Set the hex value to match your app's root background for a seamless experience.
🚧

Theme set on the configuration takes priority

If a default theme is set on the configuration for your configurationId, it overrides the theme prop. To control the theme from your app, ask the Aerosync support team to leave the default theme unset, or use a separate configurationId per theme.

5. Define postMessage events

ParameterTypeRequiredDescription
onSuccessfunction(event: SuccessPayload)YesTriggered when the bank is linked successfully and the user clicks "Continue" on the final Aerosync-UI page. See 5.1 and section 6.
onErrorfunction(event: string)YesCalled if Aerosync-UI dispatches an error event.
onClosefunction()YesTriggered when the user closes the Aerosync-UI window.
onEventfunction(event: WidgetEventType)YesTriggered by Aerosync-UI on each page load.
onLoadfunction()YesTriggered after the widget's web content has loaded.

5.1 SuccessEventType (single-account response)

PropertyTypeDescription
connectionIdstringThe unique identifier for the Aerosync connection.
clientNamestringThe name of the client associated with the session.
aeroPassUserUuidstringUUID of the authenticated AeroPass user.

5.2 WidgetEventType

PropertyTypeDescription
pageTitlestringThe identifier of the page.
onLoadApistringThe identifier of the API.

6. Multi-account linking (v4.1.0+)

Multi-account linking lets a user link multiple accounts in a single session. One connection is returned for each selected account.

🚧

Opt-in feature: disabled by default

Multi-account linking is off by default. To enable it for your configurationId, reach out to the Aerosync support team. It requires Aerosync React Native SDK v4.1.0+.

Behavior

  • When the widget is launched with a configurationId that has multi-account linking enabled, onSuccess returns the multi-account response with an accounts array. This shape is used even when the user links only one account.
  • Otherwise, onSuccess returns the single-account response (5.1).
📘

Result handling in multi-account

Every account that connects successfully is returned through onSuccess in the accounts array. If an account fails to connect, the widget reports it through onError.

To integrate

  1. Update Aerosync React Native SDK to v4.1.0+.
  2. Pass your configurationId, with multi-account linking enabled, to <AeroSyncWidget>.
  3. Update your onSuccess handler to read the accounts array. Each connectionId is a separate connection; process each one the same way you would a single-account connectionId.
  4. Use 'accounts' in event to tell the multi-account response apart from the single-account response.
  5. Handle onError, because individual accounts can fail while other accounts in the same session connect successfully.
import { AeroSyncWidget, type SuccessPayload } from 'aerosync-react-native-sdk'; // v4.1.0+

const onSuccess = (event: SuccessPayload) => {
  if ('accounts' in event) {
    // Multi-account response: successfully connected accounts
    event.accounts.forEach(({ connectionId, accountType, accountNumberDisplay }) => {
      console.log(connectionId, accountType, accountNumberDisplay);
    });
    return;
  }

  // Single-account response (default)
  console.log(event.connectionId);
};

const onError = (event: string) => {
  // In multi-account linking, a failed account is reported here.
  console.log('onError', event);
};

// ...

<AeroSyncWidget
  token={token}
  environment="sandbox"
  deeplink="yourapp://aerosync"
  configurationId={configurationId} // Required to receive the multi-account response
  aeroPassUserUuid={aeroPassUserUuid}
  onSuccess={onSuccess}
  onError={onError}
  onClose={onClose}
  onEvent={onEvent}
  onLoad={onLoad}
/>;

6.1 SuccessPayload

From v4.1.0, onSuccess receives SuccessPayload, which has one of two shapes:

TypeDescription
SuccessEventTypeSingle-account response (default). See 5.1.
MultiAccountSuccessEventTypeMulti-account response, returned when multi-account linking is enabled for the configurationId.

6.2 MultiAccountSuccessEventType

PropertyTypeDescription
accountsSuccessAccountType[]One entry for each linked account.
clientNamestringThe name of the client associated with the session.
aeroPassUserUuidstringUUID of the authenticated AeroPass user.

6.3 SuccessAccountType

PropertyTypeDescription
connectionIdstringThe unique identifier for the Aerosync connection.
accountTypestringThe account type, such as CHECKING or SAVINGS.
accountNumberDisplaystringThe masked account number, showing the last four digits.

7. Common issues

Invariant Violation: Native component for "RNCWebView" does not exist

react-native-webview is missing or was not linked. Install it in your app's root project, then reinstall pods and rebuild the app:

npm install react-native-webview
cd ios && pod install

If autolinking still fails on Android, link the module manually: https://engineering.brigad.co/demystifying-react-native-modules-linking-964399ec731b


Did this page help you?