Pilote la vérification toi-même avec le mode manuel

À la fin de ce tutoriel, tu auras piloté le cycle de vie de vérification Caputchin depuis ton propre code au lieu de l'UI intégrée, sur celui des deux éléments qui convient à ton cas. Le mode manuel (trigger="manual") existe sur deux éléments différents, et ils font véritablement des rôles différents :

Choisis selon la question à laquelle tu réponds :

• « Je veux la vérification normale invisible/case à cocher, mais déclenchée par mon propre geste et sans la case à cocher par défaut. » → le widget à case à cocher, ci-dessous.
• « Je veux ma propre épreuve interactive rendue dans mon propre DOM, pas un jeu en iframe, et je décide réussite/échec. » → l'hôte de jeu, ci-dessous.

Lis exécute ton propre jeu pour savoir où le chemin du jeu s'insère. Il te faut déjà le widget sur ta page ; sinon, fais d'abord ajouter le widget.

Une limite partagée par les deux : une manche en mode manuel ne peut pas satisfaire un gate de jeu. L'élément à case à cocher ne gate jamais une clé du tout (seul <caputchin-game> le peut), et une manche <caputchin-game> manuelle n'a pas de trace rejouable, donc une clé gatée la refuse. Le mode manuel est pour les clés non gatées (vérification par proof of work) ou l'usage jeu-seul.

Chemin A : le widget à case à cocher, ton propre déclencheur

Utilise ceci quand tu veux la vérification standard mais veux la déclencher toi-même, par exemple pour lancer la résolution seulement quand le visiteur envoie un formulaire, ou derrière ton propre bouton au lieu de la case à cocher intégrée.

1. Marque l'élément manuel

<caputchin-widget id="cap" sitekey="cpt_pub_..." trigger="manual"></caputchin-widget>
<button id="go" type="button">Verify and continue</button>

Avec trigger="manual", l'UI de case à cocher intégrée est masquée ; l'élément attend que tu démarres la résolution.

2. Démarre la résolution depuis ton geste

L'élément à case à cocher en mode manuel expose une seule méthode, start() :

• start() lance la résolution du proof of work, remplaçant le clic sur la case à cocher. Valide avec trigger="manual".

Le widget à case à cocher n'a pas de pass() / fail() ; une fois que tu appelles start(), la résolution se règle d'elle-même et émet l'événement pass. (Les poignées de libération/abandon vivent sur l'hôte de jeu, couvertes au Chemin B.)

const widget = document.getElementById("cap");

document.getElementById("go").addEventListener("click", () => {
  widget.start(); // begin verification now
});

widget.addEventListener("pass", () => {
  // token issued; submit your form / continue
});

Quand la résolution se règle, l'élément achève la vérification et (dans un formulaire) injecte le champ caputchin-token comme n'importe quel autre widget. Ton backend vérifie ce token exactement comme d'habitude ; le mode manuel ne change rien côté serveur.

Chemin B : l'hôte de jeu, ton propre DOM

Utilise ceci quand tu veux rendre ta propre épreuve interactive dans ton propre balisage, au lieu de charger un jeu en iframe, et décider le résultat toi-même.

1. Marque l'élément manuel et place ton balisage

Mets trigger="manual" sur <caputchin-game> et place ton propre balisage dedans. Dans tout autre mode, le widget ignore les enfants du light-DOM ; le mode manuel est le seul mode où il les projette dans son shell de mise en page via un <slot>.

<caputchin-game id="cap" sitekey="cpt_pub_..." trigger="manual">
  <!-- Your own markup. The widget renders it inside its shell. -->
  <div id="my-game">
    <p>Tap the banana three times.</p>
    <button id="banana" type="button">🍌</button>
  </div>
</caputchin-game>

Avec un sitekey présent et la clé non gatée, le widget exécute sa vérification de proof of work en arrière-plan ; ton interaction est la partie visible. Sans sitekey (ou no-verify), c'est jeu-seul : ton interaction tourne sans rien à vérifier.

2. Pilote le résultat depuis ton code

L'hôte de jeu en mode manuel expose pass() et fail(). Il n'y a pas de start() : la manche est active dès que l'élément se monte (la fabrique montée est le signal de départ).

• pass(payload?) libère la vérification : le visiteur a réussi. Appelle-le une fois ; les appels ultérieurs sont ignorés (le verdict est verrouillé).
• fail(payload?) abandonne la manche. Optionnel ; une manche inachevée est de toute façon traitée comme un non-pass.

Les charges :

• pass({ trace }) : trace est l'enregistrement opaque de manche que ton interaction produit. Sur une manche gatée, le serveur la rejoue pour le verdict ; sur une clé non gatée ou jeu-seul, elle est acceptée telle quelle, donc passe une chaîne vide (ou un simple marqueur) quand il n'y a rien à rejouer. Il n'y a pas de score fourni par le client ici.
• fail({ code?, message? }) : un code et un message de diagnostic optionnels, tous deux des métadonnées client, jamais un signal de confiance.

const widget = document.getElementById("cap");
let taps = 0;

document.getElementById("banana").addEventListener("click", () => {
  taps += 1;
  if (taps >= 3) {
    widget.pass({ trace: `banana:${taps}` }); // visitor won
  }
});

// Optional: give up explicitly.
// widget.fail({ code: "gave-up", message: "closed the prompt" });

Comme pour le chemin de la case à cocher, pass() achève la vérification et injecte le token ; ton backend le vérifie de la même façon.

Réagis au résultat (les deux chemins)

Écoute les événements du widget pour mettre à jour ta propre UI :

widget.addEventListener("pass", () => {
  // verification released
});
widget.addEventListener("error", (e) => {
  console.warn("verification error", e.detail);
});

La décision de confiance est toujours ton backend confirmant le token, pas l'événement ; l'événement est pour l'UX.

Ce que le mode manuel ne peut pas faire

• Gater une clé de site. Une clé avec exiger un jeu activé ne peut pas être satisfaite par l'élément à case à cocher du tout, et refuse un <caputchin-game> manuel (il lève une erreur de configuration à la mise en place) parce qu'il n'y a pas de trace rejouable. Le mode manuel est pour les clés non gatées ou jeu-seul.
• Rejouer la manche d'un jeu personnalisé. Si tu as besoin d'un jeu qui gate, rends-le comme un jeu auto-hébergé en iframe et produis une trace, pas en mode manuel.

Voir aussi

• Méthodes et événements du widget : la référence complète de start() / pass() / fail() et de chaque événement qu'ils émettent.
• Jeu auto-hébergé en iframe : un jeu en bac à sable, rejouable, qui peut gater.
• Exécute ton propre jeu : les deux modes de livraison comparés.
• Vérifier sur ton backend : confirmer le token qu'un pass produit.