Programmatische API des Feedback-Widgets

Neben der visuellen Oberfläche mit dem schwebenden Button kannst du das Widget vollständig per Code steuern. Dadurch kannst du das Formular über deine eigenen Buttons öffnen, Feedback ohne visuelle Oberfläche senden oder auf Widget-Ereignisse reagieren.

Hook useFeedbackWidget (React)

Das Paket @almirant/feedback-react enthält einen Hook, der vollständigen Zugriff auf die API des Widgets bietet.

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

function MiComponente() {
  const {
    open,       // Öffnet das Formular
    close,      // Schließt das Formular
    submit,     // Sendet Feedback programmatisch
    isReady,    // true, wenn das Widget initialisiert ist
    isOpen,     // true, wenn das Formular sichtbar ist
    error,      // Letzter Fehler oder null
  } = useFeedbackWidget();

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

Wichtig

Der Hook useFeedbackWidget setzt voraus, dass die Komponente <FeedbackWidget> an einer Stelle im Komponentenbaum eingebunden ist. Wenn kein Widget eingebunden ist, gibt der Hook No-Op-Funktionen zurück und isReady ist false.

Hook-Eigenschaften

Eigenschaft	Typ	Beschreibung
open()	() => void	Öffnet das Feedback-Formular
close()	() => void	Schließt das Formular
submit(data)	(data: FeedbackData) => Promise<void>	Sendet Feedback programmatisch
isReady	boolean	true, wenn das Widget vollständig initialisiert ist
isOpen	boolean	true, wenn das Formular sichtbar ist
error	string | null	Meldung des letzten Fehlers oder null, wenn kein Fehler vorliegt

Beispiel: Benutzerdefinierter Button

Blende den standardmäßigen schwebenden Button aus und verwende deinen eigenen Button:

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

Beispiel: Feedback programmatisch senden

Sende Feedback, ohne das visuelle Formular anzuzeigen. Das ist nützlich, um kontextbezogenes Feedback zu erfassen (nach dem Abschließen einer Aktion, beim Schließen eines Modals usw.).

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

Typ FeedbackData

interface FeedbackData {
  message: string;            // Feedback-Text (erforderlich)
  category?: string;          // Kategorie: 'bug', 'feature', 'improvement', 'other'
  metadata?: Record<string, unknown>;  // Zusätzliche Daten
}

Globale API (JavaScript)

Wenn du den Script-Tag verwendest, ist die API im globalen Objekt FeedbackWidget verfügbar.

Methoden

// Formular öffnen
FeedbackWidget.open();

// Formular schließen
FeedbackWidget.close();

// Feedback ohne visuelle Oberfläche senden
FeedbackWidget.submit({
  message: 'El boton de pago no responde en Safari',
  category: 'bug',
  metadata: {
    browser: navigator.userAgent,
    page: window.location.href,
  },
});

// Prüfen, ob das Widget bereit ist
if (FeedbackWidget.isReady()) {
  FeedbackWidget.open();
}

Methodenreferenz

Methode	Parameter	Rückgabewert	Beschreibung
init(options)	WidgetOptions	void	Initialisiert das Widget mit der angegebenen Konfiguration
open()	--	void	Öffnet das Formular
close()	--	void	Schließt das Formular
submit(data)	FeedbackData	Promise<void>	Sendet Feedback programmatisch
isReady()	--	boolean	Gibt true zurück, wenn das Widget initialisiert ist
isOpen()	--	boolean	Gibt true zurück, wenn das Formular sichtbar ist
destroy()	--	void	Entfernt das Widget aus dem DOM und gibt Ressourcen frei

Ereignisse und Callbacks

Du kannst Widget-Ereignisse abonnieren, um auf Nutzeraktionen zu reagieren.

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);
    // Du kannst Daten an deine eigene Analytics-Lösung senden
    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);
  }}
/>

Callback-Liste

Callback	Parameter	Wird ausgelöst, wenn ...
onOpen	--	Das Formular geöffnet wird
onClose	--	Das Formular geschlossen wird
onSubmit	{ message, category, metadata }	Feedback erfolgreich gesendet wird
onError	{ message: string }	Beim Senden ein Fehler auftritt

Feedback ohne visuelle Oberfläche senden

Wenn du das visuelle Formular nicht benötigst und eine eigene Benutzeroberfläche erstellen möchtest, kannst du nur die Funktion submit verwenden:

JavaScript

// Ohne sichtbaren Button initialisieren
FeedbackWidget.init({
  publicKey: 'pk_tu_clave_publica',
  // Beim direkten Einsatz von submit wird kein schwebender Button angezeigt
});

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

// Vergiss nicht, das Widget einzubinden (es kann ausgeblendet sein)
function App() {
  return (
    <>
      <CustomFeedbackForm />
      <FeedbackWidget publicKey="pk_tu_clave_publica" />
    </>
  );
}

Tipp

Auch wenn du deine eigene Benutzeroberfläche erstellst, musst du das Widget mit FeedbackWidget.init() initialisieren oder <FeedbackWidget> einbinden, damit die Funktion submit Zugriff auf die Almirant-API hat. Das Widget übernimmt die Authentifizierung und das Senden.

Widget entfernen

Wenn du das Widget vollständig entfernen musst (zum Beispiel beim Wechseln eines Bereichs in einer SPA):

// JavaScript
FeedbackWidget.destroy();

In React wird das Widget automatisch entfernt, wenn die Komponente <FeedbackWidget> ausgehängt wird.