Aerosync Web SDK

This Web SDK provides an interface to load Aerosync-UI in Javascript/typescript 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.

Installation

npm i aerosync-web-sdk

Usage

1. Create the necessary HTML elements to trigger and host the AeroSync widget.

<!-- Button to launch the AeroSync widget -->
<!-- 'id' is optional but useful for CSS/JS targeting -->
<!-- Vue syntax, replace with onclick="openAerosyncWidget()" if using plain JS -->
<button
  id="openBank"
  class="button"
  role="button"
  @click="openAerosyncWidget()"
>
  Connect Bank
</button>

<!-- This div is where the AeroSync widget iframe will be embedded -->
<!-- Make sure the 'id' here matches the 'elementId' passed during initialization -->
<div id="widget"></div>

2. Import and Configure the AeroSync Widget

/**
 * Step-by-step integration of AeroSync AddBank widget
 */
import type {
  AerosyncWidget,
  WidgetSuccessPayload,
  WidgetEventType,
} from "aerosync-web-sdk";
import { initAeroSyncWidget } from "aerosync-web-sdk";

function openAerosyncWidget() {
  // Initialize the widget with configuration options
  let widgetControls = initAeroSyncWidget({
    elementId: "widget", //  ID of the target div in your HTML
    iframeTitle: "Connect", //  Used for accessibility
    environment: "production", //  Set to 'sandbox' for testing, 'production' for live
    token: "xxxx", //  Your secure AeroSync token
    aeroPassUserUuid: "xxxx", //  Your AeroPass User UUID
    theme: "light", //  Only 'light' or 'dark' are supported

    // Event listener for all widget events
    onEvent(event: WidgetEventType) {
      console.log("event", event);
    },

    // Fires when the widget is fully loaded
    onLoad() {
      console.log("onload");
    },

    // Called after the user successfully connects a bank and closes the widget
    onSuccess(event: WidgetSuccessPayload) {
      console.log("onSuccess", event);
      if ("accounts" in event) {
        // multi-account: event.accounts = [{ connectionId, accountType, accountNumberDisplay }]
      } else {
        // single account: event.connectionId
      }
      // Handle success (e.g., update UI, send data to backend, etc.)
    },

    // Fires when the widget is closed manually by the user
    onClose() {
      console.log("widget closed");
    },

    // Catch and handle widget errors
    onError(event: string) {
      console.log("onError", event);
    },
  });

  // Launch the widget
  widgetControls.launch();
}

Widget methods

initAeroSyncWidget(...) returns a controller with the following methods:

| Method | Description | | --- | --- | | launch() | Opens the widget. | | exit() | Closes the widget programmatically (removes the iframe / closes the popup) and fires onClose. | | toggleTheme(value) | Switches the theme at runtime. value must be 'light' or 'dark'. | | destroy() | Tears down the widget and removes its event listeners. Call this when your component unmounts (see Lifecycle & cleanup). |

widgetControls.launch();
widgetControls.toggleTheme("dark");
widgetControls.exit();
widgetControls.destroy();

Lifecycle & cleanup (React / Vue / SPA)

In single-page apps, always call destroy() when the host component unmounts. Otherwise the widget's message event listener (and any mounted iframe) leaks across navigations and re-mounts.

// React
useEffect(() => {
  const widget = initAeroSyncWidget({ /* ...config */ });
  widget.launch();
  return () => widget.destroy(); // cleanup on unmount
}, []);

// Vue
onUnmounted(() => {
  widgetControls?.destroy();
});

Configuration options

In addition to the required fields shown above (elementId, iframeTitle, environment, token, aeroPassUserUuid, and the on* callbacks), the following optional fields are supported:

| Option | Type | Description | | --- | --- | --- | | theme | 'light' \| 'dark' | Widget theme. Defaults to 'light'. | | style | { bgColor?, opacity?, width?, height? } | Visual overrides for the widget container, including custom width / height. | | embeddedBankView | { elementId, width?, height?, onEmbedded } | Renders the bank-selection list embedded in your page instead of in the modal. | | deeplink | string | Deep link into a specific step/flow of the widget. | | handleOAuthManually | boolean | Lets your app handle the OAuth redirect instead of the SDK. | | handleMFA | boolean | Enables manual handling of MFA flows. | | jobId | string | Resume / relink an existing job. | | connectionId | string | Resume / relink an existing connection. | | configurationId | string | Server-side configuration profile to apply. | | manualLinkOnly | boolean | Restricts the flow to manual (non-OAuth) linking only. | | targetDocument | ShadowRoot | Mounts the widget inside a Shadow DOM root instead of the main document. |

Event payloads

The on* callbacks receive typed payloads:

// onSuccess - fired after the user successfully links account(s).
// The payload is a union: single-account, or multi-account when the client
// has multi-account linking enabled. Narrow with `"accounts" in event`.
type WidgetSuccessPayload =
  | WidgetEventSuccessType
  | WidgetEventMultiAccountSuccessType;

// single account (AeroPass returning user + AeroPass link-new-bank)
interface WidgetEventSuccessType {
  connectionId: string;
  clientName: string;
  aeroPassUserUuid: string;
}

// multi-account (enable_multiple_account_linking)
interface WidgetEventMultiAccountSuccessType {
  accounts: {
    connectionId: string;
    accountType: string;
    accountNumberDisplay: string;
  }[];
  clientName: string;
  aeroPassUserUuid: string;
}

// onEvent - fired for general widget lifecycle events
interface WidgetEventType {
  type: string;
  payload: {
    pageTitle: string;
    onLoadApi: string;
  };
}

// onError receives an error message string
// onLoad and onClose receive no arguments

Readme.io document

For more information check the complete guide here: https://sync.dev.aero.inc/docs/npm-aeronetwork