API programmatique du widget de feedback

En plus de l'interface visuelle avec le bouton flottant, vous pouvez contrôler entièrement le widget depuis le code. Cela vous permet d'ouvrir le formulaire depuis vos propres boutons, d'envoyer des retours sans interface visuelle ou de réagir aux événements du widget.

Hook useFeedbackWidget (React)

Le package @almirant/feedback-react comprend un hook qui donne un accès complet à l'API du widget.

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

function MiComponente() {
  const {
    open,       // Ouvre le formulaire
    close,      // Ferme le formulaire
    submit,     // Envoie des retours par programmation
    isReady,    // true lorsque le widget est initialisé
    isOpen,     // true lorsque le formulaire est visible
    error,      // Dernière erreur ou null
  } = useFeedbackWidget();

  return (
    <button onClick={open}>
      Envoyer des retours
    </button>
  );
}

Important

Le hook useFeedbackWidget exige que le composant <FeedbackWidget> soit monté quelque part dans l'arbre des composants. Si aucun widget n'est monté, le hook renvoie des fonctions no-op et isReady vaut false.

Propriétés du hook

Propriété	Type	Description
open()	() => void	Ouvre le formulaire de feedback
close()	() => void	Ferme le formulaire
submit(data)	(data: FeedbackData) => Promise<void>	Envoie des retours par programmation
isReady	boolean	true lorsque le widget est entièrement initialisé
isOpen	boolean	true lorsque le formulaire est visible
error	string | null	Message de la dernière erreur, ou null en l'absence d'erreur

Exemple : bouton personnalisé

Masquez le bouton flottant par défaut et utilisez votre propre bouton :

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

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

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

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

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

Exemple : envoyer des retours par programmation

Envoyez des retours sans afficher le formulaire visuel. Cette approche est utile pour recueillir des retours contextuels (après avoir effectué une action, à la fermeture d'une modale, etc.).

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

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

  const handleRating = async (rating: number) => {
    await submit({
      message: `Évaluation après achat : ${rating}/5`,
      metadata: {
        type: 'rating',
        rating,
        orderId: 'order_123',
      },
    });
  };

  return (
    <div>
      <p>Comment s'est passée votre expérience d'achat ?</p>
      {[1, 2, 3, 4, 5].map((n) => (
        <button key={n} onClick={() => handleRating(n)}>
          {n}
        </button>
      ))}
      {error && <p className="error">{error}</p>}
    </div>
  );
}

Type FeedbackData

interface FeedbackData {
  message: string;            // Texte du retour (obligatoire)
  category?: string;          // Catégorie : 'bug', 'feature', 'improvement', 'other'
  metadata?: Record<string, unknown>;  // Données supplémentaires
}

API globale (JavaScript)

Lorsque vous utilisez la balise script, l'API est disponible sur l'objet global FeedbackWidget.

Méthodes

// Ouvrir le formulaire
FeedbackWidget.open();

// Fermer le formulaire
FeedbackWidget.close();

// Envoyer des retours sans interface visuelle
FeedbackWidget.submit({
  message: 'Le bouton de paiement ne répond pas dans Safari',
  category: 'bug',
  metadata: {
    browser: navigator.userAgent,
    page: window.location.href,
  },
});

// Vérifier si le widget est prêt
if (FeedbackWidget.isReady()) {
  FeedbackWidget.open();
}

Référence des méthodes

Méthode	Paramètres	Retour	Description
init(options)	WidgetOptions	void	Initialise le widget avec la configuration fournie
open()	--	void	Ouvre le formulaire
close()	--	void	Ferme le formulaire
submit(data)	FeedbackData	Promise<void>	Envoie des retours par programmation
isReady()	--	boolean	Renvoie true si le widget est initialisé
isOpen()	--	boolean	Renvoie true si le formulaire est visible
destroy()	--	void	Supprime le widget du DOM et libère les ressources

Événements et callbacks

Vous pouvez vous abonner aux événements du widget pour réagir aux actions de l'utilisateur.

Balise script

FeedbackWidget.init({
  publicKey: 'pk_tu_clave_publica',
  onOpen: () => {
    console.log('Le formulaire est ouvert');
  },
  onClose: () => {
    console.log('Le formulaire est fermé');
  },
  onSubmit: (data) => {
    console.log('Retour envoyé :', data.message);
    // Vous pouvez envoyer ces données à votre propre analytics
    analytics.track('feedback_submitted', {
      category: data.category,
    });
  },
  onError: (error) => {
    console.error('Erreur lors de l\'envoi du retour :', error);
  },
});

React

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

Liste des callbacks

Callback	Paramètres	Se déclenche lorsque...
onOpen	--	Le formulaire s'ouvre
onClose	--	Le formulaire se ferme
onSubmit	{ message, category, metadata }	Les retours sont envoyés avec succès
onError	{ message: string }	Une erreur survient lors de l'envoi

Envoyer des retours sans interface visuelle

Si vous n'avez pas besoin du formulaire visuel et souhaitez créer votre propre interface, vous pouvez utiliser uniquement la fonction submit :

JavaScript

// Initialise sans bouton visible
FeedbackWidget.init({
  publicKey: 'pk_tu_clave_publica',
  // Aucun bouton flottant n'est affiché lors de l'utilisation directe de submit
});

// Votre formulaire personnalisé
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('Retour envoyé');
  } catch (error) {
    alert('Erreur lors de l\'envoi : ' + 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="Vos retours..."
        required
      />
      <button type="submit" disabled={sending}>
        {sending ? 'Envoi...' : 'Envoyer'}
      </button>
      {error && <p className="error">{error}</p>}
    </form>
  );
}

// N'oubliez pas de monter le widget (il peut être masqué)
function App() {
  return (
    <>
      <CustomFeedbackForm />
      <FeedbackWidget publicKey="pk_tu_clave_publica" />
    </>
  );
}

Conseil

Même si vous créez votre propre interface, vous devez initialiser le widget avec FeedbackWidget.init() ou monter <FeedbackWidget> afin que la fonction submit ait accès à l'API Almirant. Le widget gère l'authentification et l'envoi.

Détruire le widget

Si vous devez supprimer complètement le widget (par exemple, lors d'un changement de section dans une SPA) :

// JavaScript
FeedbackWidget.destroy();

Dans React, le widget est détruit automatiquement lorsque le composant <FeedbackWidget> est démonté.