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-webviewiOS
cd ios && pod installAndroid
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
AeroSyncWidgetis a named export. The defaultBankLinkexport was removed in v3.0.2, soimport BankLink from 'aerosync-react-native-sdk'no longer works. Replace it withimport { AeroSyncWidget } from 'aerosync-react-native-sdk'.
4. Aerosync SDK configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
token | string | Yes | Request an Aerosync token using the POST /token_widget endpoint. Reference: https://sync.dev.aero.inc/reference/post_v2-token-widget |
environment | string | Yes | Permitted values are sandbox and production. |
deeplink | string | Yes | Aerosync redirects to this link in your mobile app after authentication to resume the workflow. |
aeroPassUserUuid | string | Yes | Aeronetwork user id. |
configurationId | string | No | Unique ID that represents the client, used to apply customization. |
theme | 'light' | 'dark' | No | Widget theme. Defaults to light. See 4.1. |
customWebViewProps | object | No | Additional props passed to the underlying react-native-webview component. Use style.backgroundColor to set the background color while the widget loads. |
manualLinkOnly | boolean | No | If true, the user can only link their bank manually. Defaults to false. |
handleMFA | boolean | No | Handle the additional MFA for the balance refresh workflow. |
jobId | string | No | Unique identifier for the current job. Required if handleMFA is true. |
connectionId | string | No | Unique identifier for the current Aerosync connection. Required if handleMFA is true. |
4.1 Dark mode configuration
Dark mode uses two props:
themesets the widget's theme (lightordark).customWebViewProps.style.backgroundColorsets 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 priorityIf a default theme is set on the configuration for your
configurationId, it overrides thethemeprop. To control the theme from your app, ask the Aerosync support team to leave the default theme unset, or use a separateconfigurationIdper theme.
5. Define postMessage events
| Parameter | Type | Required | Description |
|---|---|---|---|
onSuccess | function(event: SuccessPayload) | Yes | Triggered when the bank is linked successfully and the user clicks "Continue" on the final Aerosync-UI page. See 5.1 and section 6. |
onError | function(event: string) | Yes | Called if Aerosync-UI dispatches an error event. |
onClose | function() | Yes | Triggered when the user closes the Aerosync-UI window. |
onEvent | function(event: WidgetEventType) | Yes | Triggered by Aerosync-UI on each page load. |
onLoad | function() | Yes | Triggered after the widget's web content has loaded. |
5.1 SuccessEventType (single-account response)
| Property | Type | Description |
|---|---|---|
connectionId | string | The unique identifier for the Aerosync connection. |
clientName | string | The name of the client associated with the session. |
aeroPassUserUuid | string | UUID of the authenticated AeroPass user. |
5.2 WidgetEventType
| Property | Type | Description |
|---|---|---|
pageTitle | string | The identifier of the page. |
onLoadApi | string | The 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 defaultMulti-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
configurationIdthat has multi-account linking enabled,onSuccessreturns the multi-account response with anaccountsarray. This shape is used even when the user links only one account. - Otherwise,
onSuccessreturns the single-account response (5.1).
Result handling in multi-accountEvery account that connects successfully is returned through
onSuccessin theaccountsarray. If an account fails to connect, the widget reports it throughonError.
To integrate
- Update Aerosync React Native SDK to v4.1.0+.
- Pass your
configurationId, with multi-account linking enabled, to<AeroSyncWidget>. - Update your
onSuccesshandler to read theaccountsarray. EachconnectionIdis a separate connection; process each one the same way you would a single-accountconnectionId. - Use
'accounts' in eventto tell the multi-account response apart from the single-account response. - 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:
| Type | Description |
|---|---|
SuccessEventType | Single-account response (default). See 5.1. |
MultiAccountSuccessEventType | Multi-account response, returned when multi-account linking is enabled for the configurationId. |
6.2 MultiAccountSuccessEventType
| Property | Type | Description |
|---|---|---|
accounts | SuccessAccountType[] | One entry for each linked account. |
clientName | string | The name of the client associated with the session. |
aeroPassUserUuid | string | UUID of the authenticated AeroPass user. |
6.3 SuccessAccountType
| Property | Type | Description |
|---|---|---|
connectionId | string | The unique identifier for the Aerosync connection. |
accountType | string | The account type, such as CHECKING or SAVINGS. |
accountNumberDisplay | string | The 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 installIf autolinking still fails on Android, link the module manually: https://engineering.brigad.co/demystifying-react-native-modules-linking-964399ec731b
Updated 21 days ago