Ajouter le widget à ton site

Tu as la clé publique de BananaSeed de la leçon précédente. Maintenant on pose le widget sur le formulaire de contact React, on voit dans le tableau de bord un vrai visiteur le résoudre, puis on ajoute l'unique appel serveur qui en fait une vraie protection.

Ce que tu auras à la fin

• Le widget sur ton formulaire de contact, vérifiant les visiteurs dans le navigateur.
• Ton tableau de bord, montrant ces vérifications.
• Ton backend Node, rejetant chaque envoi sans token valide.

1. Ajouter le widget à ton formulaire React

Installe le paquet. Il enregistre l'élément <caputchin-widget> (et l'élément <caputchin-game> pour la prochaine leçon) :

npm install @caputchin/widget

Importe-le une fois au démarrage, par exemple au point d'entrée de ton app (main.jsx) :

import "@caputchin/widget";

Maintenant pose le widget dans le formulaire de contact de BananaSeed. Quand la case à cocher est résolue, le widget ajoute au formulaire un champ caché caputchin-token que tu lis à l'envoi, exactement comme tes propres champs. Remplace cpt_pub_... par ta clé publique :

export function ContactForm() {
  async function handleSubmit(e) {
    e.preventDefault();
    const data = new FormData(e.currentTarget);
    await fetch("/api/contact", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        email: data.get("email"),
        message: data.get("message"),
        token: data.get("caputchin-token"),
      }),
    });
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" required />
      <textarea name="message" required />
      <caputchin-widget sitekey="cpt_pub_..." />
      <button type="submit">Send</button>
    </form>
  );
}

Sur une page HTML pure sans étape de build, ou dans une app mobile native ? Vois l'intégration par balise script (CDN) et le guide des apps mobiles.

2. Vois-le vérifier

Lance ton app et ouvre le formulaire de contact. La case à cocher Caputchin apparaît et se ferme d'elle-même, sans le moindre clic. Tu n'as même pas encore besoin d'envoyer le formulaire : c'est déjà une vraie vérification, et elle a atteint Caputchin.

3. Confirme-le dans ton tableau de bord

De retour dans le tableau de bord, ouvre ton équipe et clique dans ta clé de site. Ses statistiques montrent un entonnoir : Sessions démarrées, Réussies dans le navigateur, Vérifiées côté serveur et Menaces bloquées. Actualise la page ; Sessions démarrées et Réussies dans le navigateur affichent maintenant toutes deux au moins 1. C'est ta visite : le widget a chargé (démarrée) et l'épreuve a été résolue dans le navigateur (réussie dans le navigateur), sans aucun backend.

Vérifiées côté serveur est encore à 0, parce que rien sur ton serveur n'a encore vérifié de token. Cet écart est la prochaine étape.

Ton widget est en ligne, et le tableau de bord journalise déjà de vraies vérifications avant que tu aies écrit une ligne de code backend. 🎉

4. Vérifie le token sur ton backend

Réussie dans le navigateur veut dire que le visiteur a résolu l'épreuve, mais ton formulaire n'est pas protégé tant que ton serveur ne confirme pas le token. Un bot peut ignorer le widget complètement et POSTer directement vers ton endpoint. Donc ton backend vérifie chaque token auprès de Caputchin avant de faire confiance à la requête. Ton secret (cpt_sec_...) vit dans une variable d'environnement, jamais dans le navigateur :

import express from "express";

const app = express();
app.use(express.json());

app.post("/api/contact", async (req, res) => {
  const { email, message, token } = req.body;

  const verdict = await fetch("https://caputchin.com/api/v1/siteverify", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      secret: process.env.CAPUTCHIN_SECRET,
      response: token,
    }),
  }).then((r) => r.json());

  if (!verdict.success) {
    return res.status(400).json({ error: "Could not verify you are human." });
  }

  // Verified. Handle the real message: store it, email it, whatever you do.
  res.json({ ok: true });
});

app.listen(3001);

Cette vérification verdict.success est le point clé : un bot qui poste directement vers /api/contact ne porte aucun token, success revient à false, et le message est rejeté avant que tu n'y touches jamais.

Pas de backend ? Pas de souci. Active la vérification hébergée, et Caputchin exécute cette vérification pour toi et ne relaie que les envois vérifiés vers un webhook ou ta boîte de réception.

5. Confirme la vérification serveur

Envoie de nouveau le formulaire de contact, maintenant que ton endpoint vérifie. Retourne aux statistiques de ta clé de site et actualise : Vérifiées côté serveur affiche maintenant aussi au moins 1, à côté de Démarrées et Réussies dans le navigateur. Tout l'entonnoir est couvert, du navigateur jusqu'au serveur.

Pour lire cet entonnoir à l'envers (ce que les écarts entre les compteurs te disent sur l'abandon des visiteurs et les erreurs d'intégration), vois Statistiques et sessions.

Ton formulaire de contact est maintenant vraiment protégé : chaque envoi est vérifié sur ton serveur, et les bots sans token sont refusés. 🎉

Ce qui vient de se passer

Suite

La case à cocher fonctionne. Maintenant la partie amusante : échange-la contre un vrai jeu jouable, sans changer ton backend.

Continue vers Ajouter un jeu depuis le Marketplace.