Web NPM SDK (old versions // no longer supported)

Introduction

This NPM package 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.

๐Ÿ“˜

Web NPM SDK Versioning

For all new Aeropay integrations, please use the latest version of our web npm SDK.

Any versions 1.0 and earlier will no longer be supported.

1. Install Aerosync Web NPM SDK

2. 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>

3. Import and Configure the AeroSync Widget

/**
 * Step-by-step integration of AeroSync AddBank widget
 */
import type {
  AerosyncWidget,
  WidgetEventSuccessType,
  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
    theme: "light", // ๐ŸŽจ Choose between 'light' or 'dark' theme

    // ๐Ÿ“ฆ 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: WidgetEventSuccessType) {
      console.log("onSuccess", event);
      // ...
      // 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();
}

4. Widget configuration

Configure your environment for sandbox (https://www.sandbox.aerosync.com/) or production (https://www.aerosync.com). Additionally configure an id, iframeTitle, width, and height of the window.

Parameter

Type

Required

Description

token

string

Yes

Request AeroSync Token using POST /token_widget endpoint. Reference: https://api-aerosync.readme.io/reference/post_token-widget

elementId

string

Yes

Specifies a unique id for an HTML element. The default value is "widget".

iframeTitle

string

Yes

Adds title text to the iframe.

environment

string

Yes

Permitted values are [sandbox, sandbox, production]

deeplink

string

Conditional

Aerosync will redirect to this link on mobile app after authentication to resume the workflow for OAuth bank experiences Required for mobile applications. Not required for web applications. You can send the deeplink as empty string. Eg: let deeplink:string = ""

consumerId

string

No

Unique ID assigned to you to apply widget customizations.

handleMFA

boolean

No

handle the additional MFA for balance refresh workflow

jobId

string

No

unique identifier for current job

userId

string

No

unique identifier for current user

targetDocument

ShadowRoot

No

The widget will be rendered inside the shadow dom instead of root document

zIndex

string

No

To override the stacking order of the widget elements provide the appropriate value. The default value is 1.

manualLinkOnly

boolean

No

User will only be able to link their bank manually.

embeddedBankView

object (embeddedBankViewType)

No

Enables embedding the bank view directly inside a custom container. Requires an elementId. Optional properties include width, height, and a callback onEmbedded() that is triggered when the embedded view is ready. Example: { elementId: 'embeddedId', width: '572px', height: '348px', onEmbedded: () => { //onEmbedded ready} }

For more information, click here: https://api-aerosync.readme.io/docs/embedded-view#/

style

object

No

Allows you to customize the widgetโ€™s appearance. You can set width, height, bgColor, and opacity.
Example: { width: '375px', height: '688px', bgColor: '#000000', opacity: 0.7 }

5. Define postMessage events

ParameterTypeRequiredDescription
onLoadfunction(response)YesTriggered after the widget has fully loaded. Useful for initializing logic or tracking page views.
onSuccessfunction(response)YesTriggered when a bank is successfully added and the widget is closed. This is the final step, where you can update the UI or navigate to another screen.
onErrorfunction(response)YesTriggered when AeroSync-UI encounters and dispatches an error event.
onClosefunction()YesTriggered when the user manually closes the AeroSync-UI window.
onEventfunction(response)YesTriggered on every page load within AeroSync-UI. Useful for tracking user navigation or progress.