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 VersioningFor 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
npm i [email protected]
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: |
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. |
5. Define postMessage events
Parameter | Type | Required | Description |
---|---|---|---|
onLoad | function(response) | Yes | Triggered after the widget has fully loaded. Useful for initializing logic or tracking page views. |
onSuccess | function(response) | Yes | Triggered 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. |
onError | function(response) | Yes | Triggered when AeroSync-UI encounters and dispatches an error event. |
onClose | function() | Yes | Triggered when the user manually closes the AeroSync-UI window. |
onEvent | function(response) | Yes | Triggered on every page load within AeroSync-UI. Useful for tracking user navigation or progress. |
Updated 4 days ago