API programática do Feedback Widget

Além da interface visual com o botão flutuante, você pode controlar o widget inteiramente por código. Isso permite abrir o formulário a partir dos seus próprios botões, enviar feedback sem uma interface visual ou reagir aos eventos do widget.

Hook useFeedbackWidget (React)

O pacote @almirant/feedback-react inclui um hook que dá acesso completo à API do 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

O hook useFeedbackWidget exige que o componente <FeedbackWidget> esteja montado em algum lugar da árvore de componentes. Se não houver widget montado, o hook retorna funções no-op e isReady será false.

Propriedades do hook

Propriedade	Tipo	Descrição
open()	() => void	Abre o formulário de feedback
close()	() => void	Fecha o formulário
submit(data)	(data: FeedbackData) => Promise<void>	Envia feedback programaticamente
isReady	boolean	true quando o widget está completamente inicializado
isOpen	boolean	true quando o formulário está visível
error	string | null	Mensagem do último erro, ou null se não houver erros

Exemplo: botão personalizado

Oculte o botão flutuante padrão e use o seu próprio botão:

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}
      />
    </>
  );
}

Exemplo: enviar feedback programaticamente

Envie feedback sem exibir o formulário visual. Isso é útil para coletar feedback contextual, depois de concluir uma ação, ao fechar um 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)

Quando você usa a tag de script, a API fica disponível no objeto global FeedbackWidget.

Métodos

// 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();
}

Referência dos métodos

Método	Parâmetros	Retorno	Descrição
init(options)	WidgetOptions	void	Inicializa o widget com a configuração informada
open()	--	void	Abre o formulário
close()	--	void	Fecha o formulário
submit(data)	FeedbackData	Promise<void>	Envia feedback programaticamente
isReady()	--	boolean	Retorna true se o widget estiver inicializado
isOpen()	--	boolean	Retorna true se o formulário estiver visível
destroy()	--	void	Remove o widget do DOM e libera recursos

Eventos e callbacks

Você pode assinar os eventos do widget para reagir às ações do usuário.

Tag de script

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	Parâmetros	É acionado quando...
onOpen	--	O formulário é aberto
onClose	--	O formulário é fechado
onSubmit	{ message, category, metadata }	O feedback é enviado com sucesso
onError	{ message: string }	Ocorre um erro no envio

Enviar feedback sem interface visual

Se não precisar do formulário visual e quiser criar sua própria UI, você pode usar apenas a função 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" />
    </>
  );
}

Dica

Mesmo que você crie sua própria interface, precisa inicializar o widget com FeedbackWidget.init() ou montar <FeedbackWidget> para que a função submit tenha acesso à API do Almirant. O widget cuida da autenticação e do envio.

Destruir o widget

Se você precisar remover o widget completamente, por exemplo ao mudar de seção em uma SPA:

// JavaScript
FeedbackWidget.destroy();

No React, o widget é destruído automaticamente quando o componente <FeedbackWidget> é desmontado.