Capacitor Example

Introduction

This guide explains how to integrate the Aerosync UI widget inside a Capacitor-based mobile app. Aerosync allows users to securely link their bank accounts via your app by embedding the Aerosync UI widget (a web-based flow) inside your Capacitor app's web view.

👍

Fetch SDK token GET /aggregatorCredentials

The token for the Aerosync SDK will be returned in the response to GET /aggregatorCredentials. Read the Aerosync guide for details.

1. Installation

Inside the web app of your Capacitor project, install the Aerosync web SDK:

npm i aerosync-web-sdk

2. Setup Aerosync Widget

Follow the guide Aerosync Integration Guide to integrate the Aerosync widget into your Capacitor app.
https://dev.aero.inc/docs/web-npm-sdk#/

Make sure to add the deeplink in the widget configuration. This will help redirect the user back to the main app after authentication.

3. Handle OAuth Bank Authentication (Optional)

Aerosync launches the OAuth URL in the external system browser by default. If you want to manually handle the OAuth URL within the Capacitor in-app browser, you can capture the event as shown below:

3.1 Enable Manual OAuth Handling

Set handleOAuthManually to true in the widget configuration of the Web SDK to prevent Aerosync from automatically launching the OAuth window. This gives you control to trigger the OAuth flow manually when needed.

3.2 Launch OAuth Manually via URL

Listen for the onEvent callback to receive the OAuth URL. Then open it using an in-app browser or system browser, based on your app’s flow.

// 📦 Event listener
async onEvent(event) {
  try {
    // Check if the app is running on a native platform (iOS or Android)
    if (Capacitor.isNativePlatform()) {
      // Verify that the event payload exists, pageTitle equals "launchExternalWindow",
      // and onLoadApi URL is present
      if (
        event?.payload?.pageTitle === "launchExternalWindow" &&
        event?.payload?.onLoadApi
      ) {
        // Open the URL in Capacitor's in-app browser
        await Browser.open({ url: event.payload.onLoadApi });
      }
    }
  } catch (error) {
    console.error("Failed to open URL in Capacitor Browser:", error);
  }
}

4. Demo

You can find a working demo of this integration at:
https://github.com/Aeropay-inc/test-aerosync-capacitor