Installa chiavi basate sul punteggio sui siti web

Questa pagina spiega come installare una chiave basata sul punteggio senza richiesta di verifica sul tuo sito web. Con una chiave basata sul punteggio, puoi includere reCAPTCHA in tutto il sito senza richiedere agli utenti di risolvere le verifiche CAPTCHA.

Quando viene installata una chiave basata sul punteggio, reCAPTCHA invia una risposta criptata, il token di risposta reCAPTCHA (noto anche come token), quando un utente finale attiva un'interazione. Dopo aver generato il token, devi creare una valutazione entro due minuti per ricevere un punteggio per ogni richiesta. In base al punteggio, puoi comprendere il livello di rischio delle interazioni degli utenti e configurare una o più risposte appropriate. Inoltre, la chiave basata sul punteggio può raccogliere la telemetria dell'attività dei bot per l'allerta precoce contro nuovi attacchi o target.

Per migliorare il modello di rischio di reCAPTCHA, ti consigliamo di includerlo in ogni pagina del tuo sito, perché aiuta a capire come gli utenti reali e i bot passano da una pagina all'altra e da un'azione all'altra.

Prima di iniziare

  1. Prepara l'ambiente per reCAPTCHA.

  2. Crea una chiave basata sul punteggio.

    In alternativa, puoi copiare l'ID di una chiave esistente basata sul punteggio eseguendo uno dei seguenti passaggi:

    • Per copiare l'ID di una chiave esistente dalla consoleGoogle Cloud , segui questi passaggi:

      1. Vai alla pagina reCAPTCHA.

        Vai a reCAPTCHA

      2. Seleziona la scheda Chiavi.
      3. Nell'elenco delle chiavi reCAPTCHA, individua la chiave che vuoi copiare e fai clic su .
    • Per copiare l'ID di una chiave esistente utilizzando l'API REST, utilizza il metodo projects.keys.list.
    • Per copiare l'ID di una chiave esistente utilizzando gcloud CLI, utilizza il comando gcloud recaptcha keys list.

Inserisci la chiave sul tuo sito web

reCAPTCHA funziona al meglio quando ha il contesto delle interazioni sul tuo sito. reCAPTCHA monitora il comportamento legittimo e il comportamento illecito per conoscere le interazioni sul tuo sito.

Per ottenere risultati ottimali, installa le chiavi basate sul punteggio nei seguenti punti del tuo sito web:

  • Moduli
  • Azioni (interazioni utente)
  • Sullo sfondo di tutte le pagine web

Le chiavi basate sul punteggio non interrompono gli utenti, quindi puoi eseguire reCAPTCHA con le chiavi basate sul punteggio ogni volta che è necessario senza influire sulla conversione.

Integra la chiave con il frontend

Ti consigliamo di aggiungere la verifica reCAPTCHA a un'interazione dell'utente che deve essere verificata. Ad esempio, se vuoi verificare l'azione di invio di un modulo, devi aggiungere la verifica reCAPTCHA all'azione di invio.

A seconda di dove vuoi aggiungere la verifica reCAPTCHA, scegli l'opzione appropriata:

Puoi vedere un esempio di ogni opzione nel codice sorgente del sito web demo.

Aggiungere la verifica a un'interazione utente

  1. Per caricare reCAPTCHA sulla tua pagina web, aggiungi l'API JavaScript con la tua chiave basata sul punteggio all'interno dell'elemento <head></head> della tua pagina web.

        <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

    reCAPTCHA utilizza la lingua del browser per impostazione predefinita. Se vuoi specificare una lingua diversa, utilizza l'attributo hl=LANG nello script. Ad esempio, per utilizzare il francese, specifica quanto segue: <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>. Per scoprire quali sono le lingue supportate, consulta la sezione Codici lingua per reCAPTCHA.

    Se vuoi specificare una posizione per il badge, utilizza badge=LOCATION come parametro di query nel tag di script. Ad esempio, www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. Per impostazione predefinita, la posizione è impostata su bottomright. Gli altri valori possibili sono inline e bottomleft.

  2. Per aggiungere la verifica reCAPTCHA a un'interazione utente, procedi nel seguente modo:

    1. Per assicurarti che grecaptcha.enterprise.execute() venga eseguito dopo il caricamento della libreria reCAPTCHA, utilizza grecaptcha.enterprise.ready().

    2. Chiama grecaptcha.enterprise.execute() su ogni interazione che vuoi proteggere con la chiave basata sul punteggio. Specifica un nome significativo per un'interazione utente nel parametro action. Per ulteriori indicazioni, vedi Azioni.

      L'esempio seguente mostra come chiamare grecaptcha.enterprise.execute() in un'azione di accesso:

      <script>
function onClick(e) {
  e.preventDefault();
  grecaptcha.enterprise.ready(async () => {
    const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'LOGIN'});
    // IMPORTANT: The 'token' that results from execute is an encrypted response sent by
    // reCAPTCHA to the end user's browser.
    // This token must be validated by creating an assessment.
    // See https://cloud.google.com/recaptcha/docs/create-assessment
  });
}
</script>

      grecaptcha.enterprise.execute() genera un token come mostrato nell'esempio seguente: 

      03AGdBq27tvcDrfiRuxQnyKs-SarXVzPODXLlpiwNsLqdm9BSQQRtxhkD-Wv6l2vBSnL_JQd80FZp3IeeF_TxNMrqhyQchk7hmg_ypDctt_F5RTr9zNO9TSDX3Fy0qHQTuaM9E3hrAkA1v1l7D-fCreg7uq8zoudfh1ZRmN49-2iAMAn4E8_ff-nmlLTNGVZmCSyeze-5xM24pM_JhhUVcCMIDKYtDUnr2imxg2ubIqMscCZGUtdXNUO_LRSzuwWDlLyAr3V2nVn29Z48PQa2QzbymEXzO9pCtoGQmY7kiZ8ILfD9DAJSSyUTMwJXVJptUeBmLM341fq_STYZBbPQJ0zYOEDvJoFsIwGMfuphkDet0nK56b0mkzaL8RCRy2oK31Mcx6n3PhGkCnQ6QIhiV5ZVmV1Hz9M3w99zYw6ekc3wPCNMZ6V6x1ApVpIk3reFfByRQ0C0_pRWwbKZHLXQ_oSTI1UI7kyH1VeXngsJAx2l7zcp0hQNipajC4YwL7Jb8X4cCD0NeiaY1YCrI5j87mK5axcMikq460I4niIFeDBlHGF-ndqu3CJstosAur-C_x827f-dPPjA9Vrw8MDb3x4KUb0vbA8xE9mJxPYGY0rPCR27vJ38Voa7DjEBGX9c-iufv5_wfj-yIfIAHy0iijnRLI0CVkWF2-iPdWv7LnkTwL3WKbF_MrEGZXmtyLX9dEZArfxmToeMuSdYkfikkgR2-k4Xzxlz15RbHJuWSAYqEyTTnpUXmOvDuTN92b0kYqbRelcLUI_Shm-8dq9e-L7K6YWQv32gV6NukZKY15dyrJaW10frBgTOGSTTpIyB7MNEL8S27WjWtOb-zWsgimIhoRNfS8BiJWkmK4gTj51m7Wur-qsDbHgV6gXlMvjJs_B7oXX-mKsKhY9ACtwukotBelGYQOvf1RDHjH3Yi1RDfELBY6AkwUK4tq8cACVGpCwa0gKUo-sbORTsGu_r7VTzYo1AaZD5HV4XUm8yoqszel6DmIfkJcI7PfzzvfUJuvMQ1itZSzpzuth3glbKBYsIjbKqG-q8cxtZ7u0l32j46ASo2zlCJWUjwP3W1P7MUenEoIZtjlyTB_tT6Fk8RxGgRv3oLP7NPFJGs9ZGOAl6tBHpZF8Y_FqEOCMKtBl2JYOE5h6_Es3buSdiMm7mtLr64pboGiEColF1vbVvYpyaaqGFPXBM6ekZSXEXLAI0_7rj_fCLgnB21KXfac95vZbM9vyJCASvDcWKwqajQwy5aGMNe9GtbMogYbZfz5UGWAIi24Vd8KSv3qKOOwvzbcw4H0HYdsBXA

  3. Dopo che è stato generato, invia il token reCAPTCHA al backend e crea un test entro due minuti.

    Per le integrazioni WAF, se stai integrando una chiave di token di azione, devi allegare il token a un'intestazione della richiesta predefinita e non devi creare una valutazione. Per informazioni dettagliate, consulta Implementa i token di azione reCAPTCHA.

Aggiungere reCAPTCHA a un pulsante HTML

  1. Per caricare reCAPTCHA sulla tua pagina web, aggiungi l'API JavaScript con la tua chiave basata sul punteggio all'interno dell'elemento <head></head> della tua pagina web.

        <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

    reCAPTCHA utilizza la lingua del browser per impostazione predefinita. Se vuoi specificare una lingua diversa, utilizza l'attributo hl=LANG nello script. Ad esempio, per utilizzare il francese, specifica quanto segue: <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>. Per scoprire quali sono le lingue supportate, consulta la sezione Codici lingua per reCAPTCHA.

  2. Per aggiungere reCAPTCHA a un semplice pulsante HTML:

    1. Definisci una funzione di callback per gestire il token.

      <script>
   function onSubmit(token) {
     document.getElementById("demo-form").submit();
   } // Use `requestSubmit()` for extra features like browser input validation.
</script>

      Per saperne di più, consulta la sezione Metodo requestSubmit().

    2. Aggiungi attributi al pulsante HTML.

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

      Se vuoi specificare una posizione per il badge, utilizza l'attributo data-badge=LOCATION sull'elemento che contiene class=g-recaptcha. Per impostazione predefinita, la posizione è impostata su bottomright. Gli altri valori possibili sono inline e bottomleft.

    3. Quando questo pulsante viene utilizzato per inviare un modulo sul tuo sito, il parametro POST g-recaptcha-response contiene il token di risposta.

  3. Dopo che è stato generato, invia il token reCAPTCHA al backend e crea un test entro due minuti.

    Per le integrazioni WAF, se stai integrando una chiave di token di azione, devi allegare il token a un'intestazione della richiesta predefinita e non devi creare una valutazione. Per informazioni dettagliate, consulta Implementa i token di azione reCAPTCHA.

Passaggi successivi