API programatica del Feedback Widget

Ademas de la interfaz visual con el boton flotante, puedes controlar el widget completamente desde codigo. Esto te permite abrir el formulario desde tus propios botones, enviar feedback sin interfaz visual, o reaccionar a eventos del widget.

Hook useFeedbackWidget (React)

El paquete @almirant/feedback-react incluye un hook que da acceso completo a la API del widget.

import { useFeedbackWidget } from '@almirant/feedback-react';

function MiComponente() {
  const {
    open,       // Abre el formulario
    close,      // Cierra el formulario
    submit,     // Envia feedback programaticamente
    isReady,    // true cuando el widget esta inicializado
    isOpen,     // true cuando el formulario esta visible
    error,      // Ultimo error o null
  } = useFeedbackWidget();

  return (
    <button onClick={open}>
      Enviar feedback
    </button>
  );
}

Importante

El hook useFeedbackWidget requiere que el componente <FeedbackWidget> este montado en algun lugar del arbol de componentes. Si no hay widget montado, el hook devuelve funciones no-op y isReady sera false.

Propiedades del hook

Propiedad	Tipo	Descripcion
open()	() => void	Abre el formulario de feedback
close()	() => void	Cierra el formulario
submit(data)	(data: FeedbackData) => Promise<void>	Envia feedback programaticamente
isReady	boolean	true cuando el widget esta completamente inicializado
isOpen	boolean	true cuando el formulario esta visible
error	string | null	Mensaje del ultimo error, o null si no hay errores

Ejemplo: boton personalizado

Oculta el boton flotante por defecto y usa tu propio boton:

import { FeedbackWidget, useFeedbackWidget } from '@almirant/feedback-react';

function FeedbackButton() {
  const { open, isReady } = useFeedbackWidget();

  return (
    <button
      onClick={open}
      disabled={!isReady}
      className="mi-boton-feedback"
    >
      Dejar feedback
    </button>
  );
}

function App() {
  return (
    <>
      <nav>
        <FeedbackButton />
      </nav>

      <FeedbackWidget
        publicKey="pk_tu_clave_publica"
        showTriggerLabel={false}
      />
    </>
  );
}

Ejemplo: enviar feedback programaticamente

Envia feedback sin mostrar el formulario visual. Util para recopilar feedback contextual (despues de completar una accion, al cerrar un modal, etc.).

import { useFeedbackWidget } from '@almirant/feedback-react';

function PostCompraFeedback() {
  const { submit, error } = useFeedbackWidget();

  const handleRating = async (rating: number) => {
    await submit({
      message: `Valoracion post-compra: ${rating}/5`,
      metadata: {
        type: 'rating',
        rating,
        orderId: 'order_123',
      },
    });
  };

  return (
    <div>
      <p>Como fue tu experiencia de compra?</p>
      {[1, 2, 3, 4, 5].map((n) => (
        <button key={n} onClick={() => handleRating(n)}>
          {n}
        </button>
      ))}
      {error && <p className="error">{error}</p>}
    </div>
  );
}

Tipo FeedbackData

interface FeedbackData {
  message: string;            // Texto del feedback (requerido)
  category?: string;          // Categoria: 'bug', 'feature', 'improvement', 'other'
  metadata?: Record<string, unknown>;  // Datos adicionales
}

API global (JavaScript)

Cuando usas el script tag, la API esta disponible en el objeto global FeedbackWidget.

Metodos

// Abrir el formulario
FeedbackWidget.open();

// Cerrar el formulario
FeedbackWidget.close();

// Enviar feedback sin interfaz visual
FeedbackWidget.submit({
  message: 'El boton de pago no responde en Safari',
  category: 'bug',
  metadata: {
    browser: navigator.userAgent,
    page: window.location.href,
  },
});

// Verificar si el widget esta listo
if (FeedbackWidget.isReady()) {
  FeedbackWidget.open();
}

Referencia de metodos

Metodo	Parametros	Retorno	Descripcion
init(options)	WidgetOptions	void	Inicializa el widget con la configuracion dada
open()	--	void	Abre el formulario
close()	--	void	Cierra el formulario
submit(data)	FeedbackData	Promise<void>	Envia feedback programaticamente
isReady()	--	boolean	Devuelve true si el widget esta inicializado
isOpen()	--	boolean	Devuelve true si el formulario esta visible
destroy()	--	void	Elimina el widget del DOM y libera recursos

Eventos y callbacks

Puedes suscribirte a eventos del widget para reaccionar a acciones del usuario.

Script tag

FeedbackWidget.init({
  publicKey: 'pk_tu_clave_publica',
  onOpen: () => {
    console.log('El formulario se abrio');
  },
  onClose: () => {
    console.log('El formulario se cerro');
  },
  onSubmit: (data) => {
    console.log('Feedback enviado:', data.message);
    // Puedes enviar a tu propio analytics
    analytics.track('feedback_submitted', {
      category: data.category,
    });
  },
  onError: (error) => {
    console.error('Error al enviar feedback:', error);
  },
});

React

<FeedbackWidget
  publicKey="pk_tu_clave_publica"
  onOpen={() => console.log('Abierto')}
  onClose={() => console.log('Cerrado')}
  onSubmit={(data) => {
    analytics.track('feedback_submitted', {
      category: data.category,
    });
  }}
  onError={(error) => {
    console.error('Error:', error);
  }}
/>

Lista de callbacks

Callback	Parametros	Se dispara cuando...
onOpen	--	El formulario se abre
onClose	--	El formulario se cierra
onSubmit	{ message, category, metadata }	Se envia feedback exitosamente
onError	{ message: string }	Ocurre un error al enviar

Enviar feedback sin interfaz visual

Si no necesitas el formulario visual y quieres construir tu propia UI, puedes usar solo la funcion submit:

JavaScript

// Inicializa sin boton visible
FeedbackWidget.init({
  publicKey: 'pk_tu_clave_publica',
  // No se muestra boton flotante al usar submit directamente
});

// Tu formulario personalizado
document.getElementById('mi-formulario').addEventListener('submit', async (e) => {
  e.preventDefault();
  const mensaje = document.getElementById('mensaje').value;

  try {
    await FeedbackWidget.submit({
      message: mensaje,
      category: 'feature',
      metadata: {
        source: 'custom-form',
        page: window.location.pathname,
      },
    });
    alert('Feedback enviado');
  } catch (error) {
    alert('Error al enviar: ' + error.message);
  }
});

React

import { FeedbackWidget, useFeedbackWidget } from '@almirant/feedback-react';

function CustomFeedbackForm() {
  const { submit, error } = useFeedbackWidget();
  const [message, setMessage] = useState('');
  const [sending, setSending] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setSending(true);

    try {
      await submit({
        message,
        category: 'feature',
        metadata: { source: 'custom-form' },
      });
      setMessage('');
    } finally {
      setSending(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <textarea
        value={message}
        onChange={(e) => setMessage(e.target.value)}
        placeholder="Tu feedback..."
        required
      />
      <button type="submit" disabled={sending}>
        {sending ? 'Enviando...' : 'Enviar'}
      </button>
      {error && <p className="error">{error}</p>}
    </form>
  );
}

// No olvides montar el widget (puede estar oculto)
function App() {
  return (
    <>
      <CustomFeedbackForm />
      <FeedbackWidget publicKey="pk_tu_clave_publica" />
    </>
  );
}

Consejo

Aunque construyas tu propia interfaz, necesitas inicializar el widget con FeedbackWidget.init() o montar <FeedbackWidget> para que la funcion submit tenga acceso a la API de Almirant. El widget se encarga de la autenticacion y el envio.

Destruir el widget

Si necesitas eliminar el widget completamente (por ejemplo, al cambiar de seccion en una SPA):

// JavaScript
FeedbackWidget.destroy();

En React, el widget se destruye automaticamente cuando se desmonta el componente <FeedbackWidget>.