reCAPTCHA v3
e CapMonster Cloud

Trabalhar com o CapMonster Cloud através da API normalmente envolve os passos seguintes:

1. Aceda à página do painel de administração do reCAPTCHA.

2. Registe um novo site e escolha o tipo de captcha — reCAPTCHA v3

3. Obtenha duas chaves:

• Site key — chave pública (utilizada no frontend);
• Secret key — chave privada (utilizada no servidor para verificação)

Pode abrir as definições, onde, por exemplo, é possível indicar domínios adicionais para utilização do reCAPTCHA ou configurar alertas sobre problemas no site ou aumento de tráfego suspeito.

4. Exemplos de código para o lado do cliente

A forma mais simples de utilizar o reCAPTCHA v3 é ligar a API JavaScript e adicionar atributos a um botão.

Ligação à API:

<script src="https://www.google.com/recaptcha/api.js"></script>

Função de callback para o formulário:

<script>
  function onSubmit(token) {
    document.getElementById("form").submit();
  }
</script>

Botão com atributos do reCAPTCHA:

<button class="g-recaptcha" 
        data-sitekey="reCAPTCHA_sitekey" 
        data-callback='onSubmit' 
        data-action='submit'>Submit</button>

Para controlo total, utilize grecaptcha.execute com o parâmetro render:

Ligação à API com a chave:

<script src="https://www.google.com/recaptcha/api.js?render=reCAPTCHA_site_key"></script>

Chamada programática:

<script>
  function onClick(e) {
    e.preventDefault();
    grecaptcha.ready(function() {
      grecaptcha.execute('reCAPTCHA_sitekey', {action: 'submit'}).then(function(token) {
          // Envie o token para o servidor para verificação
      });
    });
  }
</script>

O token deve ser enviado de imediato para o servidor para verificação.

Notas importantes:

• Validade do token: o token recebido do reCAPTCHA v3 é válido durante 2 minutos. Certifique-se de que o envia para o servidor dentro desse período.
• Verificação no servidor: após receber o token no servidor, envie um pedido POST para https://www.google.com/recaptcha/api/siteverify com os parâmetros:
  – secret: a sua chave secreta
  – response: o token recebido do cliente
  – remoteip (opcional): endereço IP do utilizador
• O servidor da Google irá devolver uma resposta JSON com informações sobre o resultado da verificação.

Pode encontrar informações mais detalhadas na documentação oficial do captcha.

5. Agora, do lado do servidor, efetue a verificação da resposta

Exemplo em PHP

<?php
// A sua Secret Key do reCAPTCHA v3
$secret = 'YOUR_SECRET_KEY';

// Obter o token do formulário
$token = $_POST['recaptcha-token'] ?? '';

// Enviar o pedido para a Google para verificar o token
$response = file_get_contents(
    "https://www.google.com/recaptcha/api/siteverify?secret={$secret}&response={$token}"
);

$result = json_decode($response, true);

// Verificar o sucesso e a pontuação de confiança
if ($result['success'] && $result['score'] >= 0.5 && $result['action'] === 'submit') {
    echo "Verificação aprovada";
} else {
    http_response_code(403);
    echo "Verificação reprovada";
}
?>

Notas:

• Certifique-se de que, no cliente, o token é enviado num campo oculto do formulário com o nome recaptcha-token:

<input type="hidden" name="recaptcha-token" id="recaptcha-token">


• O limite de score pode ser ajustado consoante o nível de rigor desejado (por exemplo, 0,3–0,7).
• A verificação de action === 'submit' aumenta a segurança, garantindo que o token foi emitido para a ação correta na página.