Adicione o widget ao seu site

Você tem a chave pública da BananaSeed da lição anterior. Agora colocamos o widget no formulário de contato em React, vemos o painel confirmar que um visitante real o resolveu e depois adicionamos a única chamada de servidor que transforma isso em proteção de verdade.

O que você terá no final

• O widget no seu formulário de contato, verificando visitantes no navegador.
• Seu painel mostrando essas verificações.
• Seu backend Node descartando qualquer envio que não tenha um token válido.

1. Adicione o widget ao seu formulário React

Instale o pacote. Ele registra o elemento <caputchin-widget> (e o elemento <caputchin-game> para a próxima lição):

npm install @caputchin/widget

Importe-o uma vez na inicialização, como no ponto de entrada do seu app (main.jsx):

import "@caputchin/widget";

Agora solte o widget no formulário de contato da BananaSeed. Quando a checkbox é resolvida, o widget adiciona um campo oculto caputchin-token ao formulário, então você o lê no envio exatamente como os seus próprios campos. Substitua cpt_pub_... pela sua chave 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>
  );
}

Numa página HTML pura sem etapa de build, ou dentro de um app móvel nativo? Veja a integração via tag de script (CDN) e o guia de apps móveis.

2. Veja-o verificar

Rode seu app e abra o formulário de contato. A checkbox do Caputchin aparece e se completa sozinha, sem clique nenhum. Você nem precisa enviar o formulário ainda: isso já é uma verificação real, e ela chegou ao Caputchin.

3. Confirme no seu painel

De volta ao painel, abra sua equipe e clique na sua chave de site. As estatísticas dela mostram um funil: Sessões iniciadas, Concluídas no cliente, Verificadas no servidor e Ameaças bloqueadas. Atualize a página; Sessões iniciadas e Concluídas no cliente agora marcam ambas pelo menos 1. Essa é a sua visita: o widget carregou (iniciou) e o desafio foi resolvido no navegador (concluído no cliente), sem nenhum backend envolvido.

Verificadas no servidor ainda está em 0, porque nada no seu servidor conferiu um token ainda. Essa lacuna é o próximo passo.

Seu widget está no ar, e o painel já está registrando verificações reais, antes de você ter escrito uma linha de código de backend. 🎉

4. Verifique o token no seu backend

Concluído no cliente significa que o visitante resolveu o desafio, mas seu formulário não está protegido até que seu servidor confirme o token. Um bot pode ignorar o widget por completo e fazer POST direto no seu endpoint. Então seu backend confere cada token com o Caputchin antes de confiar na requisição. Seu segredo (cpt_sec_...) vive em uma variável de ambiente, nunca no 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);

Essa verificação de verdict.success é o ponto: um bot que posta direto em /api/contact não carrega token, success volta como false, e a mensagem é descartada antes de você sequer tocá-la.

Sem backend? Sem problema. Ligue a verificação hospedada e o Caputchin roda essa conferência por você, encaminhando só os envios verificados para um webhook ou sua caixa de entrada.

5. Confirme a conferência no servidor

Envie o formulário de contato mais uma vez, agora que seu endpoint está verificando. Volte às estatísticas da sua chave de site e atualize: Verificadas no servidor agora marca pelo menos 1 também, ao lado de Iniciadas e Concluídas no cliente. O funil inteiro está coberto, do navegador ao servidor.

Para ler esse funil ao contrário (o que as lacunas entre os contadores dizem sobre desistência de visitantes e erros de integração), veja estatísticas e sessões.

Seu formulário de contato está genuinamente protegido agora: cada envio é conferido no seu servidor, e bots sem token são recusados. 🎉

O que acabou de acontecer

A seguir

A checkbox funciona. Agora a parte divertida: troque-a por um jogo jogável de verdade, sem mudar nada no seu backend.

Continue para Adicionar um jogo do marketplace.