Migre do reCAPTCHA
O Caputchin usa o mesmo modelo em duas partes do reCAPTCHA, um widget na página que produz um token e uma conferência no servidor que o confirma, então migrar é em boa parte uma troca mecânica, não uma reescrita. A troca no servidor, em especial, espelha de propósito o formato siteverify do reCAPTCHA. Este guia dá o antes e depois de cada peça.
Se você ainda não criou uma conta e uma chave de site no Caputchin, crie sua conta primeiro; você vai precisar de uma chave pública (cpt_pub_...) para a página e de um segredo (cpt_sec_...) para o seu backend, a mesma divisão da chave de site e da chave secreta do reCAPTCHA.
O modelo mental não muda
Tudo o que você já construiu em torno do reCAPTCHA, renderizar um widget, coletar um token, fazer POST dele no seu servidor, verificá-lo antes de confiar na requisição, permanece. Só os nomes e os endpoints mudam.
1. Troque o trecho do cliente
| reCAPTCHA (checkbox v2) | Caputchin | |
|---|---|---|
| Script | <script src="https://www.google.com/recaptcha/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| Elemento | <div class="g-recaptcha" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| Campo de token em um formulário | g-recaptcha-response (autoinjetado) | caputchin-token (autoinjetado) |
| Ler o token em JS | grecaptcha.getResponse() | o detail.token do evento pass |
Como o reCAPTCHA, o widget do Caputchin autoinjeta um campo de token oculto no formulário em que fica, então se o seu formulário já fazia um POST normal, você só muda o elemento e o nome do campo que seu backend lê. Veja adicionar o widget para a configuração completa do cliente e a escolha entre CDN e npm.
2. Troque a verificação no servidor
É aqui que os dois ficam mais próximos, os formatos de requisição e resposta se alinham quase campo a campo.
| reCAPTCHA | Caputchin | |
|---|---|---|
| Endpoint | POST https://www.google.com/recaptcha/api/siteverify | POST https://caputchin.com/api/v1/siteverify |
| Campos da requisição | secret, response | secret, response (idêntico) |
| Resposta | { success, challenge_ts, hostname, "error-codes" } | { success, challenge_ts, hostname, error-codes, score? } |
| Regra de confiança | aja só se success === true | aja só se success === true (idêntico) |
Na maioria dos stacks, a única mudança no seu código de verificação é a URL e o valor do segredo. A referência completa de requisição/resposta, incluindo os códigos de erro, está em verificar um token no seu backend; trechos por framework estão em exemplos de backend.
3. Mapeie o score, se você usava o reCAPTCHA v3
O reCAPTCHA v3 retorna um score (de 0.0 a 1.0) e pede que você escolha um limiar, você está adivinhando o quão humana uma requisição parecia. O Caputchin não funciona assim: success é um aprova/reprova autoritativo, porque a verificação foi de fato resolvida (uma conferência de proof-of-work, ou uma rodada de jogo rederivada no servidor), não uma probabilidade.
Se o seu código tinha if (data.score >= 0.5), troque por if (data.success). O campo score do Caputchin existe só para rodadas de jogo e é a pontuação do jogo (informativa, para os seus próprios placares), nunca uma probabilidade de bot, então não condicione o acesso a ela.
O que melhora na mudança
- Sem coleta de dados de visitantes. O reCAPTCHA traça o perfil dos seus visitantes; o Caputchin não coleta IP, User-Agent, impressão digital nem telemetria comportamental, o protocolo não tem onde pôr um identificador de visitante. Veja a filosofia.
- Um widget, não v2 contra v3. Não há um produto invisível/de score separado entre os quais escolher; um elemento cobre a checkbox e o jogo opcional.
- Um jogo opcional. Em vez de uma grade de semáforos, você pode transformar a verificação em um jogo curto que seus visitantes de fato jogam. Veja adicionar um jogo.
- Uma CSP estrita continua estrita. O Caputchin roda sob uma Content-Security-Policy apertada; você permite algumas origens em vez de afrouxar sua política. Veja como o Caputchin coloca os jogos em sandbox.
Pegadinhas
- Duas chaves, dois lares. A chave pública (
cpt_pub_...) vai na página; o segredo (cpt_sec_...) fica só no servidor, exatamente a disciplina do reCAPTCHA. Não envie o segredo ao navegador. - O token é de uso único. Como no reCAPTCHA, um token verifica uma vez. Não o cacheie nem o reenvie.
- Mude o nome do campo que seu backend lê. O campo oculto é
caputchin-token, nãog-recaptcha-response, um deslize comum de uma linha.
Veja também
- Adicionar o widget: a configuração completa do cliente.
- Verificar um token no seu backend: a referência autoritativa do
siteverify. - Exemplos de backend: a chamada de verificação em cada linguagem.
- Adicionar um jogo: transforme a verificação em um jogo.