Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Installare le chiavi universali sulle pagine web

Questo documento descrive come installare e integrare una chiave universale nelle tue pagine web.

Prima di iniziare

Installare le chiavi universali sul sito web

Per installare la chiave universale e proteggere le tue pagine web, scegli la configurazione AutoExecute di Google Cloud Fraud Defense o l'installazione JavaScript standard:

Configurazione AutoExecute

Fraud Defense AutoExecute può aiutarti a semplificare l'integrazione JavaScript del frontend intercettando le richieste di rete sulle tue pagine web, eliminando la necessità di chiamare manualmente grecaptcha.enterprise.execute() per ogni azione del frontend.

AutoExecute intercetta solo le richieste di rete asincrone avviate con l' API Fetch o XMLHttpRequest, incluse le richieste di framework come AJAX che utilizzano queste API.

AutoExecute non è supportato per le risorse che vengono caricate automaticamente al momento del caricamento della pagina. Applica invece AutoExecute alle richieste di rete attivate dalle azioni dell'utente sulla pagina, ad esempio un pulsante di accesso.

Per evitare che le verifiche di Fraud Defense causino timeout di rete, applica i timeout direttamente alle richieste. Utilizza AbortSignal.timeout(n) per l' API Fetch e la XMLHttpRequest.timeout proprietà per XMLHttpRequest.

Aggiungere il tag di script alle pagine web

Per caricare reCAPTCHA sulla tua pagina web, aggiungi l'API JavaScript con la chiave universale 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>

Per impostazione predefinita, Fraud Defense utilizza la lingua del browser. Se vuoi specificare una lingua diversa, utilizza l' hl=LANG attributo nello script. Ad esempio, per utilizzare il francese, specifica quanto segue:

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

Per scoprire di più sulle lingue supportate, consulta i codici lingua per Fraud Defense.

Configurare gli endpoint protetti

Lo script Fraud Defense si integra automaticamente con le azioni di rete definite nella configurazione delle policy della chiave universale. Questa sezione definisce un mapping dei percorsi URL (path) ai nomi delle azioni (action).

Se lo script Fraud Defense rileva una richiesta di rete asincrona a un percorso mappato, intercetta la richiesta, attiva una valutazione del rischio e, prima che la richiesta originale continui, potrebbe mostrare all'utente una verifica CAPTCHA. Il token di risposta generato viene allegato automaticamente all'intestazione X-Recaptcha-Token nella richiesta.

gcloud

Per esaminare la configurazione delle policy corrente per la chiave universale, utilizza il gcloud alpha recaptcha policies describe comando:

gcloud alpha recaptcha policies describe --key=KEY_ID

Per aggiornare la configurazione delle policy con gli endpoint protetti, crea un file YAML (ad esempio, POLICY.yaml) che definisca i percorsi e le azioni protetti:

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

Aggiorna la configurazione della chiave con il file YAML utilizzando il gcloud alpha recaptcha policies update comando:

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

API REST

Per aggiornare la configurazione delle policy in modo da definire gli endpoint protetti utilizzando l' API REST, utilizza il projects.keys.updatePolicy metodo.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

PROJECT_ID: l'ID del tuo Google Cloud progetto
KEY_ID: l'ID della chiave universale

Metodo HTTP e URL:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup

Corpo JSON della richiesta:

{
"clientSettings": {
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup"

PowerShell (Windows)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, e quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup" | Select-Object -Expand Content

In caso di esito positivo, la richiesta restituisce la configurazione delle policy aggiornata.

Il parametro path supporta i pattern glob con le seguenti regole:

Deve iniziare con / e non può essere vuoto.
Non può essere un /* o /** autonomo, in quanto l'attivazione di Fraud Defense su ogni singola richiesta al backend può influire negativamente sulle prestazioni.
I caratteri jolly * (che corrispondono a un singolo segmento di percorso) e ** (che corrispondono a più segmenti di percorso) devono occupare l'intero segmento di percorso (ad esempio, /api/*/login o /api/* sono validi, mentre /api/login* non è valido).
Il carattere jolly ** deve occupare solo l'ultimo segmento di percorso (ad esempio, /api/** è valido, mentre /api/**/login non è valido).

Richieste di terze parti: se gli strumenti di terze parti in esecuzione sulla tua pagina (ad esempio script di analisi o partner) inviano richieste a percorsi che corrispondono agli endpoint protetti (ad esempio, https://analytics.example.net/login che corrisponde a /login), AutoExecute li intercetterà. Ciò può causare una latenza di rete aggiuntiva, metriche distorte o verifiche CAPTCHA impreviste. Per evitare conflitti, assicurati che i percorsi protetti siano distintivi (ad esempio, /auth/v1/login) o utilizza l'installazione standard se si verificano collisioni di percorso.
API cross-domain: se l'API di backend è ospitata su un dominio diverso dal tuo sito web (ad esempio, examplecdn.net anziché www.example.com), AutoExecute funziona automaticamente senza una configurazione di dominio aggiuntiva.

Se la corrispondenza con domini di destinazione specifici è importante per la tua integrazione, invia una richiesta di funzionalità.

Nel backend, recupera il token di risposta dall'X-Recaptcha-Tokenintestazione della richiesta e crea una valutazione entro due minuti.

Installazione standard

Ti consigliamo di aggiungere la verifica di Fraud Defense 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 di Fraud Defense all'azione di invio.

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

Aggiungere la verifica a un'interazione dell'utente
Aggiungere Fraud Defense a un pulsante HTML

Aggiungere la verifica a un'interazione dell'utente

Per caricare reCAPTCHA sulla tua pagina web, aggiungi l'API JavaScript con la chiave universale 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>
```
Per impostazione predefinita, Fraud Defense utilizza la lingua del browser. Se vuoi specificare una lingua diversa, utilizza l' hl=LANG attributo nello script. Ad esempio, per utilizzare il francese, specifica quanto segue:

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

Per scoprire di più sulle lingue supportate, consulta i codici lingua per Fraud Defense.

Se vuoi specificare una località per il badge, utilizza badge=LOCATION come parametro di query nel tag di script. Ad esempio, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. Per impostazione predefinita, la località è impostata su bottomright. Altri valori possibili sono inline e bottomleft.
Per aggiungere la verifica di Fraud Defense a un'interazione dell'utente:
1. Per assicurarti che grecaptcha.enterprise.execute() venga eseguito dopo il caricamento della libreria Fraud Defense, utilizza grecaptcha.enterprise.ready().
2. Chiama grecaptcha.enterprise.execute() su ogni interazione che vuoi proteggere con la chiave universale. Specifica un nome significativo per un'interazione dell'utente nel parametro action. Per ulteriori indicazioni, consulta la sezione Azioni.
  
  Suggerimento: aggiungi la chiamata execute ad azioni sensibili come LOGIN, SIGNUP, PASSWORD_RESET, o PURCHASE.
  
  L'esempio seguente mostra come chiamare grecaptcha.enterprise.execute() su un'azione di accesso:
```
<script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  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 Fraud Defense 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>
```
  s
Dopo che è stato generato, invia il token reCAPTCHA al backend e crea una valutazione entro due minuti.

Importante: il backend deve specificare assessment.event.expected_action (o expectedAction in JSON) in CreateAssessmentRequest, e deve corrispondere all'azione configurata nella chiamata execute(). Ad esempio, se configuri l'azione del frontend in modo che sia LOGIN, il backend deve impostare expected_action su LOGIN quando crea una valutazione per quella richiesta. In caso di mancata corrispondenza, ciò indica che un utente malintenzionato sta tentando di falsificare le azioni.

Aggiungere Fraud Defense a un pulsante HTML

Per caricare reCAPTCHA sulla tua pagina web, aggiungi l'API JavaScript con la chiave universale 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>
```
Per impostazione predefinita, Fraud Defense utilizza la lingua del browser. Se vuoi specificare una lingua diversa, utilizza l' hl=LANG attributo nello script. Ad esempio, per utilizzare il francese, specifica quanto segue:

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

Per scoprire di più sulle lingue supportate, consulta i codici lingua per Fraud Defense.
Per aggiungere Fraud Defense a un 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 il metodo requestSubmit().
1. 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 località per il badge, utilizza l' data-badge="LOCATION" attributo nell' elemento con class="g-recaptcha". Per impostazione predefinita, la località è impostata su bottomright. Altri valori possibili sono inline e bottomleft.
1. Quando questo pulsante viene utilizzato per inviare un modulo sul tuo sito, il parametro POST g-recaptcha-response contiene il token di risposta.
Nota: se imposti il pulsante g-recaptcha su disabled, il pulsante viene attivato quando viene caricato Fraud Defense.
Dopo che è stato generato, invia il token reCAPTCHA al backend e crea una valutazione entro due minuti.

Importante: il backend deve specificare assessment.event.expected_action (o expectedAction in JSON) in CreateAssessmentRequest, e deve corrispondere all'azione configurata sul pulsante. Ad esempio, se configuri l'azione del pulsante in modo che sia submit, il backend deve impostare expected_action su submit quando crea una valutazione per quella richiesta. In caso di mancata corrispondenza, ciò indica che un utente malintenzionato sta tentando di falsificare le azioni.

Passaggi successivi

Per attivare le verifiche CAPTCHA in base a regole personalizzate, configura le policy di verifica.
Per valutare il token di risposta reCAPTCHA, crea una valutazione.