Añade el widget a tu sitio

Tienes la clave pública de BananaSeed de la lección anterior. Ahora ponemos el widget en el formulario de contacto de React, vemos en el dashboard cómo un visitante real lo supera, y luego añadimos la única llamada de servidor que convierte eso en protección de verdad.

Lo que tendrás al final

• El widget en tu formulario de contacto, verificando visitantes en el navegador.
• Tu dashboard mostrando esas verificaciones.
• Tu backend de Node descartando cualquier envío que no tenga un token válido.

1. Añade el widget a tu formulario de React

Instala el paquete. Registra el elemento <caputchin-widget> (y el elemento <caputchin-game> para la siguiente lección):

npm install @caputchin/widget

Impórtalo una vez al arranque, por ejemplo en el punto de entrada de tu app (main.jsx):

import "@caputchin/widget";

Ahora suelta el widget en el formulario de contacto de BananaSeed. Cuando la checkbox se supera, el widget añade al formulario un campo oculto caputchin-token, así que lo lees al enviar exactamente igual que tus propios campos. Reemplaza cpt_pub_... por tu clave pública:

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

¿En una página HTML plana sin paso de build, o dentro de una app móvil nativa? Mira la integración con script-tag (CDN) y la guía de apps móviles.

2. Mírala verificar

Ejecuta tu app y abre el formulario de contacto. La checkbox de Caputchin aparece y se completa sola, sin clic alguno. Ni siquiera necesitas enviar el formulario todavía: eso ya es una verificación real, y ha llegado a Caputchin.

3. Confírmalo en tu dashboard

De vuelta en el dashboard, abre tu equipo y entra en tu clave de sitio. Su estadística muestra un embudo: Sesiones iniciadas, Completadas en el cliente, Verificadas en el servidor y Amenazas bloqueadas. Actualiza la página; Sesiones iniciadas y Completadas en el cliente marcan ahora ambas al menos 1. Esa es tu visita: el widget cargó (iniciada) y el reto se resolvió en el navegador (completada en el cliente), sin backend implicado en absoluto.

Verificadas en el servidor sigue en 0, porque nada en tu servidor ha comprobado todavía un token. Esa brecha es el siguiente paso.

Tu widget está en producción, y el dashboard ya registra verificaciones reales, antes de que hayas escrito una línea de código de backend. 🎉

4. Verifica el token en tu backend

Completada en el cliente significa que el visitante superó el reto, pero tu formulario no está protegido hasta que tu servidor confirma el token. Un bot puede ignorar el widget por completo y hacer POST directo a tu endpoint. Así que tu backend comprueba cada token con Caputchin antes de fiarse de la petición. Tu secreto (cpt_sec_...) vive en una variable de entorno, nunca en el navegador:

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

Esa comprobación verdict.success es el quid: un bot que postea directo a /api/contact no lleva token, success vuelve como false, y el mensaje se descarta antes de que lo toques siquiera.

¿Sin backend? Sin problema. Activa la verificación alojada y Caputchin ejecuta esta comprobación por ti, reenviando solo los envíos verificados a un webhook o a tu bandeja de entrada.

5. Confirma la comprobación del servidor

Envía el formulario de contacto una vez más, ahora que tu endpoint está verificando. Vuelve a la estadística de tu clave de sitio y actualiza: Verificadas en el servidor marca ahora también al menos 1, junto a Iniciadas y Completadas en el cliente. El embudo entero queda cubierto, del navegador al servidor.

Para leer ese embudo al revés (lo que las brechas entre los contadores te dicen sobre el abandono de visitantes y los errores de integración), mira estadística y sesiones.

Tu formulario de contacto está ahora protegido de verdad: cada envío se comprueba en tu servidor, y los bots sin token quedan rechazados. 🎉

Lo que acaba de pasar

Siguiente

La checkbox funciona. Ahora la parte divertida: cámbiala por un juego real y jugable, sin tocar tu backend.

Continúa con Añade un juego del marketplace.