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 con le tue pagine web.

Prima di iniziare

Installare le chiavi universali sul tuo 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 di AutoExecute

Fraud Defense AutoExecute può semplificare l'integrazione di JavaScript nel frontend intercettando le richieste di rete nelle 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 sfide di Fraud Defense causino timeout di rete, applica i timeout direttamente alle richieste. Utilizza AbortSignal.timeout(n) per l'API Fetch e la proprietà XMLHttpRequest.timeout per XMLHttpRequest.

Aggiungere il tag di script alle pagine web

Per caricare reCAPTCHA sulla tua pagina web, aggiungi l'API JavaScript con la tua 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'attributo hl=LANG 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 le lingue supportate, consulta la sezione Codici lingua per Fraud Defense.

Configura endpoint protetti

Lo script Fraud Defense si integra automaticamente con le azioni di rete definite nella configurazione delle policy della tua 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, potenzialmente, mostra all'utente una sfida CAPTCHA prima che la richiesta originale continui. 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 tua chiave universale, utilizza il comando gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

Per aggiornare la configurazione della 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 comando gcloud alpha recaptcha policies update:

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

API REST

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

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

PROJECT_ID: il tuo Google Cloud ID progetto
KEY_ID: l'ID della tua 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, 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

Se l'operazione ha esito positivo, la richiesta restituisce la configurazione della 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 un /** autonomo, in quanto può influire negativamente sulle prestazioni per attivare Fraud Defense su ogni singola richiesta al backend.
I caratteri jolly * (che corrisponde a un singolo segmento di percorso) e ** (che corrisponde a più segmenti di percorso) devono occupare l'intero segmento di percorso (ad esempio, /api/*/login o /api/* sono validi; /api/login* non è valido).
Il carattere jolly ** deve occupare solo l'ultimo segmento del percorso (ad es. /api/** è valido; /api/**/login non è valido).

Richieste di terze parti:se gli strumenti di terze parti in esecuzione sulla tua pagina (come script di analisi o partner) inviano richieste a percorsi che corrispondono ai tuoi endpoint protetti (ad esempio, https://analytics.example.net/login corrispondente a /login), AutoExecute li intercetterà. Ciò può causare una latenza di rete aggiuntiva, metriche distorte o CAPTCHA imprevisti. 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 percorsi.
API multiorigine:se la tua API di backend è ospitata su un dominio diverso da quello del tuo sito web (ad esempio examplecdn.net anziché www.example.com), AutoExecute funziona automaticamente senza configurazione aggiuntiva del dominio.

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'intestazione della richiesta X-Recaptcha-Token e crea una valutazione entro due minuti.

Installazione standard

Ti consigliamo di aggiungere la verifica di Fraud Defense a un'interazione 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 Fraud Defense, scegli l'opzione appropriata:

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

Aggiungere la verifica a un'interazione utente

Per caricare reCAPTCHA sulla tua pagina web, aggiungi l'API JavaScript con la tua 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'attributo hl=LANG 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 le lingue supportate, consulta la sezione Codici lingua per Fraud Defense.

Se vuoi specificare una posizione 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 posizione è impostata su bottomright. Altri valori possibili sono inline e bottomleft.
Per aggiungere la verifica di Fraud Defense a un'interazione utente, segui questi passaggi:
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 tua chiave universale. Specifica un nome significativo per un'interazione utente nel parametro action. Per ulteriori indicazioni, consulta 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() in 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 un test 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 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 nella tua pagina web, aggiungi l'API JavaScript con la tua 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'attributo hl=LANG 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 le lingue supportate, consulta la sezione 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 posizione per il badge, utilizza l'attributo data-badge="LOCATION" sull'elemento che ha class="g-recaptcha". Per impostazione predefinita, la posizione è 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 come disabled, il pulsante viene attivato quando viene caricato Fraud Defense.
Dopo che è stato generato, invia il token reCAPTCHA al backend e crea un test 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.