Migre do hCaptcha
O Caputchin usa o mesmo modelo em duas partes do hCaptcha, 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 o formato siteverify que o próprio hCaptcha segue. 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 hCaptcha.
O modelo mental não muda
Tudo o que você já construiu em torno do hCaptcha, 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
| hCaptcha | Caputchin | |
|---|---|---|
| Script | <script src="https://js.hcaptcha.com/1/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| Elemento | <div class="h-captcha" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| Campo de token em um formulário | h-captcha-response (autoinjetado) | caputchin-token (autoinjetado) |
| Ler o token em JS | hcaptcha.getResponse() | o detail.token do evento pass |
Como o hCaptcha, 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.
| hCaptcha | Caputchin | |
|---|---|---|
| Endpoint | POST https://api.hcaptcha.com/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", score? } | { success, challenge_ts, hostname, error-codes, score? } |
| Regra de confiança | aja só se success === true | aja só se success === true (idêntico) |
Uma nota de formato: o endpoint de verificação do hCaptcha espera application/x-www-form-urlencoded, enquanto o do Caputchin aceita JSON. Se o seu código existente enviava campos codificados como formulário, troque o corpo para JSON ({"secret":"...","response":"..."}) com Content-Type: application/json. Os campos em si não mudam. A referência completa de requisição/resposta está em verificar um token no seu backend; trechos por framework estão em exemplos de backend.
3. Largue o score, se você usava o hCaptcha Enterprise
O hCaptcha Enterprise retorna um score de risco (onde um número maior significa mais risco) e pede que você escolha um limiar. 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 estimativa de risco.
Se o seu código tinha if (data.score < 0.7), troque por if (data.success). O campo score do Caputchin não tem relação: ele existe só para rodadas de jogo e é a pontuação do jogo (informativa, para os seus próprios placares), nunca um risco ou probabilidade de bot, então não condicione o acesso a ele. (Repare que a direção também é oposta, o score do hCaptcha sobe com o risco; o do Caputchin sobe com o desempenho no jogo.)
O que se mantém, e o que melhora
- A postura de privacidade pela qual você escolheu o hCaptcha, mantida. 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, então não há nada para vazar ou vender. Veja a filosofia.
- Um jogo opcional. Em vez de um desafio de seleção de imagens, você pode transformar a verificação em um jogo curto que seus visitantes de fato jogam, e é a parte que resiste a solucionadores de IA. 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 hCaptcha. Não envie o segredo ao navegador. - O token é de uso único. Como no hCaptcha, 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ãoh-captcha-response, um deslize comum de uma linha. - Formato do corpo. Envie a requisição de verificação como JSON, não codificada como formulário.
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.