Ionix Widget

Widget React para gestionar alias y cuentas en una ventana modal responsive, con comunicación segura y soporte para ambientes de desarrollo (snapshot) y producción (release).

Instalación

Producción (release)

npm install ionix-widget

Desarrollo (snapshot)

npm install ionix-widget@snapshot

Configuración Inicial

Antes de usar el widget, configura la URL del widget en tu aplicación:

import { configureWidgetUrls } from "ionix-widget";

configureWidgetUrls({
  widgetUrl: "https://tu-widget-url.com",
});

Uso Básico

import { useWidget } from "ionix-widget";

function MyComponent() {
  const { initWidget, closeWidget, isLoading, isReady, error, widgetModal } =
    useWidget();

  const handleOpenWidget = async () => {
    try {
      await initWidget(initWidgetOptions, widgetUserDataProps); // Abajo se explica la estructura de ambos parametros
    } catch (error) {
      console.error("Error al abrir el widget:", error);
    }
  };

  return (
    <div>
      <button onClick={handleOpenWidget}>Abrir Widget</button>
      <button onClick={closeWidget} disabled={!isReady}>
        Cerrar Widget
      </button>
      {isLoading && <div>Cargando widget...</div>}
      {error && <div>Error: {error.message}</div>}
      {isReady && <div>Widget listo</div>}
      {/* Renderiza SIEMPRE el modal aquí */}
      {widgetModal}
    </div>
  );
}

API

configureWidgetUrls(config)

Configura la URL base del widget.

• widgetUrl: URL del widget (obligatorio)

useWidget()

Hook principal que provee la funcionalidad del widget.

Retorna

• initWidget(options?: InitWidgetOptions, data?: WidgetUserDataProps): Promise<boolean>
• closeWidget(): void
• isLoading: boolean
• isReady: boolean
• error: Error | null
• widgetModal: React.ReactNode
  Debes renderizar {widgetModal} en tu JSX para mostrar el modal.

InitWidgetOptions

interface InitWidgetOptions {
  token: string; // Ionix token JWT (Obligatorio)
  window?: {
    width?: number; // Default: 600 (solo desktop)
  };
  barColor?: string; // Color hexadecimal de la barra superior (opcional)
  loadTimeout?: number; // Default: 15000 (15s)
  initTimeout?: number; // Default: 30000 (30s)
}

WidgetUserDataProps

interface WidgetUserDataProps {
  UserData: {
    UserSession: string;
    HolderFirstName: string;
    HolderSecondName: string;
    HolderLastName: string;
    HolderSecLastName: string;
    AliasData: Array<{
      AliasValue: string;
      AliasType: string;
    }>;
  };
  AccountData: {
    BankID: string;
    data: Array<{
      AccountID: string;
      AccountType: string;
      OriginalNameAccountHolder: string;
      AccountHolderType: string;
      SecondaryIdentificationType: string;
      SecondaryIdentificationValue: string;
    }>;
  };
}

Modal Responsive

• Desktop: El modal se centra horizontalmente, el ancho es configurable (window.width), la altura siempre es 100% de la pantalla.
• Mobile: El modal ocupa el 100% del ancho y alto de la pantalla, sin bordes ni sombra.
• Barra superior: Personalizable con barColor (hexadecimal).
• Botón de cerrar: Siempre visible en la barra superior.
• Scroll: El contenido embebido muestra scroll si es necesario.

Manejo de Errores

El widget puede lanzar los siguientes errores:

• LOAD_TIMEOUT: Tiempo de espera agotado al cargar el widget
• INIT_TIMEOUT: Tiempo de espera agotado en la inicialización
• WIDGET_CLOSED: El modal fue cerrado antes de completar la inicialización
• INVALID_ORIGIN: Mensaje recibido de un origen no válido
• UNKNOWN_ERROR: Error desconocido

Configuración por Defecto

const WIDGET_DEFAULTS = {
  WINDOW: {
    WIDTH: 600,
    TITLE: "Widget",
  },
  TIMEOUTS: {
    LOAD: 15000, // 15 segundos
    INIT: 30000, // 30 segundos
    POLLING: 1000, // 1 segundo
  },
};

Licencia

MIT