Acciones de UI

Las acciones de UI permiten que tu plugin interactúe con el shell del admin de Whatalo — mostrando retroalimentación al comerciante sin que tu plugin deba gestionar su propio sistema de notificaciones.

Todas las acciones devuelven Promise<ActionAck> y están sujetas a límites de tasa.

Notificaciones Toast

import { useAppBridge } from "@whatalo/plugin-sdk/bridge";

function BotonGuardar() {
  const bridge = useAppBridge();

  async function handleSave() {
    await guardarDatos();

    bridge.toast.show("Cambios guardados!", {
      description: "Tu configuración ha sido actualizada.",
      variant: "success", // "success" | "error" | "warning" | "info"
    });
  }

  return <button onClick={handleSave}>Guardar</button>;
}

La description es opcional. Cuando se omite, solo se muestra el mensaje principal.

Modales

Abre una URL de tu plugin dentro de un overlay modal en el admin. Útil para confirmaciones, vistas de detalle y flujos secundarios que no deben reemplazar el iframe principal.

const bridge = useAppBridge();

// Abrir un modal
await bridge.modal.open({
  title: "Detalles del Pedido",
  url: "https://tu-plugin.ejemplo.com/modal/pedido/123",
  width: 600,
  height: 400,
});

// Cerrar el modal actual desde dentro del iframe modal
await bridge.modal.close();

Reglas de Seguridad de Modales

• Solo se permiten URLs del origen registrado de tu plugin. La plataforma valida contra el dominio de appUrl.
• Los siguientes protocolos de URL están bloqueados: javascript:, data:, blob:, file:, vbscript:
• Las URLs de localhost solo están permitidas en modo de desarrollo.
• Los iframes de modal usan una política sandbox más estricta que el iframe principal del plugin — allow-same-origin no está incluido, por lo que el modal no puede acceder a las cookies o almacenamiento de la página padre.

Redimensionar

Controla la altura del iframe de tu plugin. El admin no redimensiona automáticamente el iframe — tu plugin es responsable de reportar su altura de contenido.

const bridge = useAppBridge();

// Establecer una altura específica en píxeles
await bridge.resize(800);

Límites de altura: mínimo 200px, máximo 15000px, por defecto 400px. Los valores fuera de este rango se limitan silenciosamente.

Auto-Redimensión con useAutoResize

La plantilla del plugin incluye un hook useAutoResize en ./components/whatalo-ui que observa la altura renderizada de tu contenido y llama a bridge.resize() automáticamente:

import { useAutoResize } from "./components/whatalo-ui";

function App() {
  // Reporta automáticamente la altura del contenido en cada cambio de renderizado
  useAutoResize();

  return <div>Contenido de tu plugin</div>;
}

Este es el enfoque recomendado para plugins con contenido de altura variable.

Tipo ActionAck

Cada método de acción devuelve una promesa que resuelve a este tipo:

interface ActionAck {
  type: "whatalo:ack";
  actionId: string;
  success: boolean;
  error?: string; // Presente solo cuando success es false
}

Valores comunes de error: "timeout" (sin ack en 5s), "rate_limited", "invalid_url" (modal), "invalid_path" (navegar), "out_of_bounds" (resize).