@finodigital/uba-widget

@finodigital/uba-widget

A standalone web component that embeds the fino Universal Bank Access (UBA) experience via a hardened iframe integration. It exposes a declarative HTML API, a small JavaScript controller, and utilities for lazy loading the bundle from a CDN.

Features

• Registers <fino-uba> custom element with shadow-dom encapsulated iframe
• Attribute / property sync for session, user, tenant, and visual toggles
• Hardened postMessage bridge with origin + source validation
• Promise-based readiness via element.ready
• Programmatic API through UbaWidgetController
• Optional loader helper for dynamic injection

Getting Started

npm install @finodigital/uba-widget

import { createUbaWidget } from "@finodigital/uba-widget";

const controller = createUbaWidget({
  sessionId: "<jwt>",
  userIdentifier: "<hash>",
  hideHeader: true
});

document.querySelector("#uba-container")?.append(controller.element);

controller.on("ready", ({ payload }) => {
  console.log("UBA ready", payload.version);
});

Declarative markup

<fino-uba
  session-id="<jwt>"
  user-identifier="<hash>"
  tenant="none"
  embedded="true"
  hide-header
></fino-uba>
<script type="module">
  import "@finodigital/uba-widget";

  const widget = document.querySelector("fino-uba");
  widget?.addEventListener("bank-connect", event => {
    console.log("Bank connected", event.detail.payload);
  });
</script>

Loader helper

import { loadUbaWidget } from "@finodigital/uba-widget/loader";

await loadUbaWidget({ version: "0.1.0" });

Native apps (iOS / Android)

Inside a native WebView the bank login usually has to run in the system browser, which cannot hand its result back to the widget directly. Declare that before importing the widget:

<script>
  window.UBA_NATIVE = { platform: "ios", transport: "session-pull", supportsSharedPopup: false };
</script>
<script type="module" src="/path/to/@finodigital/uba-widget"></script>

Set the global from a classic script, or with a dynamic await import(…). A static import declaration is hoisted and runs before any statement next to it, so window.UBA_NATIVE = …; import "…" in one module block assigns the global too late — the element upgrades and reads the contract first.

The widget forwards this contract onto the iframe URL — no other change is needed on the web side. UBA then polls the backend session for the bank result and keeps the account selection inside the widget.

Your native shell still has to do two things: intercept the bank URL (the widget's iframe opens it with window.open) and open it in the system browser, then bring the user back when the widget emits handle-redirect:

widget.addEventListener("handle-redirect", () => nativeBridge.dismissExternalBrowser());

The full guide, including per-platform interception examples, is published at uba.fino.run/public/docs/native-integration.

Scripts

• npm run build – generates ESM and CJS outputs plus type declarations in dist/
• npm run clean – removes build artifacts

Publishing

• Bump the version in package.json
• npm run build
• Publish to your npm registry (public or private)