React Native SDK (v4.0+)

This react native sdk version is intended for use with the network user identifier: aeropassuuid.

Introduction

This React Native SDK provides an interface to load Aerosync-UI in 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 (v4.0+)

Add latest verion of aerosync-react-native-sdk library to your project dependencies.

npm install aerosync-react-native-sdk

3. Minimal example to implement Aerosync React Native Sdk

AddBank.js

/**
 * Integrate AeroSync UI AddBank
 */
/**
 * Sample App
 * https://github.com/Aeropay-inc/aerosync-react-native-sdk/blob/main/sample/App.tsx
 *
 * @format
 */

import React, {useState} from 'react';
import BankLink, {
  SuccessEventType,
  WidgetEventType,
  Environment,
} from 'aerosync-react-native-sdk';
import DropDownPicker from 'react-native-dropdown-picker';
import {
  StyleSheet,
  SafeAreaView,
  Text,
  View,
  Alert,
  TextInput,
  TouchableOpacity,
} from 'react-native';

function App(): React.JSX.Element {
  const [token, settoken] = useState('');
  const [isSubmitted, setIsSubmitted] = useState(false);
  const [configurationId, setConfigurationId] = useState('');
  const [aeroPassUserUuid, setAeroPassUserUuid] = useState('');
  const [isDarkTheme, setIsDarkTheme] = useState(false);
  const [open, setOpen] = useState(false);
  const [value, setValue] = useState('sandbox' as Environment);
  const [output, setoutput] = useState('');
  const [items, setItems] = useState([
    {label: 'DEV', value: 'dev'},
    {label: 'SANDBOX', value: 'sandbox'},
    {label: 'PRODUCTION', value: 'production'},
  ]);

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

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

  const onSuccess = (event: SuccessEventType) => {
    setoutput(JSON.stringify(event));
    console.log('onSuccess', event);
    setIsSubmitted(false);
  };

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

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

  if (isSubmitted) {
    return (
      <SafeAreaView>
        <BankLink
          token={token}
          environment={value}
          onError={onError}
          onClose={onClose}
          onEvent={onEvent}
          onSuccess={onSuccess}
          onLoad={onLoad}
          deeplink="testaerosyncsample://"
          configurationId={configurationId}
          aeroPassUserUuid={aeroPassUserUuid}
          customWebViewProps={{
            style: { backgroundColor: isDarkTheme ? '#0E0E15' : '#FFFFFF' }
          }}
          style={{
            width: '100%',
            height: '100%',
            opacity: 1,
            bgColor: '#FFFFFF',
          }}></BankLink>
      </SafeAreaView>
    );
  } else {
    return (
      <SafeAreaView>
        <View style={styles.container}>
          <TouchableOpacity>
            <Text style={styles.OutputTitle}>{output}</Text>
          </TouchableOpacity>
          <View style={styles.dropdownView}>
            <DropDownPicker
              open={open}
              value={value}
              items={items}
              setOpen={setOpen}
              setValue={setValue}
              setItems={setItems}
              placeholder="select environment*"
            />
          </View>
          <View style={styles.inputView}>
            <TextInput
              style={styles.TextInput}
              placeholder="Enter Aerosync token*"
              onChangeText={token => settoken(token)}
              placeholderTextColor="#003f5c"
            />
          </View>
          <View style={styles.inputView}>
            <TextInput
              style={styles.TextInput}
              placeholder="Enter  configurationId (optional)"
              onChangeText={configurationId =>
                setConfigurationId(configurationId)
              }
              placeholderTextColor="#003f5c"
            />
          </View>
          <View style={styles.inputView}>
            <TextInput
              style={styles.TextInput}
              placeholder="Enter aeroPassUserUuid (optional)"
              onChangeText={aeroPassUserUuid =>
                setAeroPassUserUuid(aeroPassUserUuid)
              }
              placeholderTextColor="#003f5c"
            />
          </View>
          <TouchableOpacity
            style={styles.loginBtn}
            onPress={() => setIsSubmitted(true)}>
            <Text style={styles.loginText}>Launch Aerosync widget</Text>
          </TouchableOpacity>
        </View>
      </SafeAreaView>
    );
  }
}

const styles = StyleSheet.create({
  container: {
    alignItems: 'center',
    justifyContent: 'center',
    backgroundColor: 'white',
    height: '100%',
  },
  image: {
    marginBottom: 40,
    width: '25%',
    height: '15%',
  },
  inputView: {
    borderWidth: 1,
    borderRadius: 5,
    width: '70%',
    height: 45,
    marginBottom: 20,
  },
  dropdownView: {
    width: '70%',
    height: 45,
    marginBottom: 20,
    zIndex: 100,
  },
  TextInput: {
    color: 'black',
    height: 50,
    flex: 1,
    marginLeft: 20,
  },
  forgot_button: {
    height: 30,
    marginBottom: 30,
  },
  OutputTitle: {
    color: 'black',
    height: 100,
  },
  loginBtn: {
    width: '80%',
    borderRadius: 25,
    height: 50,
    alignItems: 'center',
    justifyContent: 'center',
    marginTop: 40,
    backgroundColor: '#24c3d2',
  },
  loginText: {
    color: 'black',
    fontWeight: 'bold',
    fontSize: 20,
  },
});
export default App;

4. Aerosync Sdk configuration

ParameterTypeRequiredDescription
tokenstringYes

Request AeroSync Token using POST /token_widget endpoint. Reference:

https://api-aerosync.readme.io/reference/post_token-widget

environmentstringYesPermitted values are [sandbox, production]
deeplinkstringYesAerosync will redirect to this link on mobile app after authentication to resume the workflow.
aeropassUserUuidstringYesAeronetwork user id
configurationIdstringNoUnique ID that represents the client to apply the customization.
handleMFAbooleanNohandle the additional MFA for balance refresh workflow
jobIdstringNounique identifier for current job Required if handleMFA is true.
connectionIdstringNounique identifier for current Aerosync user Required if handleMFA is true.
manualLinkOnlybooleanNoUser will only be able to link their bank manually.

4.1 Dark Mode Configuration

Use customWebViewProps to control the widget's background color during load, as shown in the example above. Set the hex values to match your app's root background for a seamless experience.

5. Define postMessage events

ParameterTypeRequiredDescription
onLoadfunction()NoThis method will be triggered after the contents of a webpage have been loaded.
onSuccessfunction(event: WidgetEventSuccessType)YesThis method will be triggered when a bank is added successfully and the user clicks on "continue" button in the final AeroSync-UI page.
onErrorfunction(event: string)YesThe method is called if AeroSync-UI dispatches any error events.
onClosefunction()YesThis event will be triggered if the user closes the AeroSync-UI window.
onEventfunction(event: WidgetEventType)NoAeroSync-UI will trigger event on each page load.

5.1 WidgetEventSuccessType

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

5.2 WidgetEventType

PropertyTypeDescription
payloadWidgetEventPayloadTypeThe payload of the event.
typestringThe type of the event.

5.3 WidgetEventPayloadType

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, returning one connection per 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 is available in 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.
  • Otherwise, onSuccess returns the regular single-account response.
📘

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 <BankLink>.
  3. Update your onSuccess handler to read the accounts array.
  4. Use "accounts" in event to distinguish the multi-account response from the single-account response.
  5. Handle onError because individual accounts can fail while other accounts in the same session connect successfully.
import BankLink, { 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);
};

// ...

<BankLink
  token={token}
  environment={value}
  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:

PropertyTypeDescription
SuccessEventTypeobjectSingle-account response (default). See 5.1.
MultiAccountSuccessEventTypeobjectMulti-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 or display account number, showing the last four digits.

7. Common Issues:

If you're getting Invariant Violation: Native component for "RNCWebView does not exist", it means react native autolinking did not work. Try linking it manually using below resources:

Android (link edits 3 files):
Resource: https://engineering.brigad.co/demystifying-react-native-modules-linking-964399ec731b

IOS (link manually)
Explicitly install in the Root project:\

npm i react-native-webview 
cd ios; pod install

Did this page help you?