Installa chiavi basate sul punteggio sui siti web

Questa pagina spiega come installare una chiave basata sul punteggio senza problemi sul tuo sito web. Con una chiave basata sul punteggio, puoi includere reCAPTCHA Enterprise nel tuo sito senza richiedere agli utenti di risolvere problemi CAPTCHA.

Dopo aver installato una chiave basata sul punteggio, devi creare una valutazione e 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'avviso in caso di nuovi attacchi o nuovi obiettivi.

Per migliorare il modello di rischio di reCAPTCHA Enterprise, ti consigliamo di includere reCAPTCHA Enterprise in ogni pagina del tuo sito perché è utile per capire in che modo utenti reali e bot passano da una pagina all'altra e da un'altra all'altra.

Prima di iniziare

  1. Prepara l'ambiente per reCAPTCHA Enterprise.

  2. Crea una chiave basata sul punteggio.

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

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

      1. Vai alla pagina reCAPTCHA Enterprise.

        Vai a reCAPTCHA Enterprise

      2. Nell'elenco delle chiavi reCAPTCHA, tieni il puntatore del mouse sulla chiave che vuoi copiare, quindi fai clic su .
    • Per copiare l'ID di una chiave esistente utilizzando l'API REST, usa il metodo projects.keys.list.
    • Per copiare l'ID di una chiave esistente utilizzando gcloud CLI, utilizza il comando gcloud recaptcha key list.

Posiziona la chiave sul tuo sito web

reCAPTCHA Enterprise funziona al meglio quando dispone di contesto per le interazioni sul tuo sito. reCAPTCHA Enterprise monitora sia il comportamento legittimo che quello illecito per ottenere informazioni sulle interazioni sul tuo sito.

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

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

Le chiavi basate sul punteggio non interrompono gli utenti, quindi puoi eseguire reCAPTCHA Enterprise con chiavi basate sul punteggio quando necessario, senza influire sulla conversione.

Integra la chiave con il frontend

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

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

Aggiungere la verifica a un'interazione utente

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

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

    reCAPTCHA Enterprise utilizza la lingua del browser per impostazione predefinita. Se vuoi specificare un'altra lingua, 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 di più sulle lingue supportate, consulta la pagina relativa ai codici lingua per reCAPTCHA Enterprise.

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

  2. Per aggiungere la verifica reCAPTCHA Enterprise a un'interazione utente, segui questi passaggi:

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

    2. Richiama grecaptcha.enterprise.execute() a ogni interazione che vuoi proteggere con la tua chiave basata sul punteggio. Specifica un nome significativo per un'interazione utente nel parametro action. Per ulteriori indicazioni, consulta la sezione 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 Enterprise to the end user's browser.
    // This token must be validated by creating an assessment.
    // See https://cloud.google.com/recaptcha-enterprise/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 tuo backend e crea una valutazione entro due minuti.

    Per le integrazioni WAF, se si integra una chiave token di azione, è necessario collegare il token a un'intestazione della richiesta predefinita e non è necessario creare una valutazione. Per maggiori dettagli, consulta Implementare i token di azione reCAPTCHA.

Aggiungere reCAPTCHA su un pulsante HTML

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

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

    reCAPTCHA Enterprise utilizza la lingua del browser per impostazione predefinita. Se vuoi specificare un'altra lingua, 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 di più sulle lingue supportate, consulta la pagina relativa ai codici lingua per reCAPTCHA Enterprise.

  2. Per aggiungere reCAPTCHA Enterprise con 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 ulteriori informazioni, consulta la sezione sul metodorequestSubmit().

    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 nell'elemento che presenta class=g-recaptcha. Per impostazione predefinita, la località è 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 tuo backend e crea una valutazione entro due minuti.

    Per le integrazioni WAF, se si integra una chiave token di azione, è necessario collegare il token a un'intestazione della richiesta predefinita e non è necessario creare una valutazione. Per maggiori dettagli, consulta Implementare i token di azione reCAPTCHA.

Passaggi successivi