CapMonster Cloud API
Estensione per browser
In questo articolo abbiamo cercato di rispondere a tutte le domande principali. Il primo passo per risolvere il problema è capire quale sistema di protezione viene utilizzato. A questo scopo puoi consultare l’elenco dei captcha e dei sistemi di protezione antibot più diffusi, dove trovi esempi visivi e caratteristiche chiave che ti aiutano a identificare rapidamente con cosa hai a che fare.
Se scopri che sul tuo sito viene utilizzato reCAPTCHA v2 Enterprise, il passo successivo è analizzarne più nel dettaglio le proprietà e il funzionamento. In questo stesso articolo puoi anche studiare la guida all’integrazione di reCAPTCHA v2 Enterprise, per comprendere a fondo come opera sul tuo sito. Questo ti permetterà non solo di capire la protezione attuale, ma anche di pianificarne correttamente la manutenzione.
Quando testi form che includono reCAPTCHA v2 Enterprise devi spesso verificare che la captcha funzioni e sia integrata correttamente.
Puoi verificare manualmente la captcha inserita nel tuo sito.
Per la risoluzione automatica puoi usare strumenti come CapMonster Cloud, che accetta i parametri della captcha, li elabora sui propri server e restituisce un token pronto all'uso. Inserisci quel token nel form per superare il controllo senza intervento dell'utente.
Lavorare con CapMonster Cloud via API di solito prevede i seguenti passaggi:
Creazione della task
Invio della richiesta APILa richiesta di soluzione deve includere:
type - RecaptchaV2EnterpriseTask;
websiteURL - l’indirizzo della pagina dove appare la captcha;
websiteKey - il sitekey mostrato sulla pagina;
enterprisePayload - inviarlo se il widget reCAPTCHA Enterprise aggiunge un campo s all’oggetto passato a grecaptcha.enterprise.render con il sitekey;
pageAction - il valore action che il widget manda a Google. Predefinito: verify.
https://api.capmonster.cloud/createTask{
"clientKey": "API_KEY",
"task": {
"type": "RecaptchaV2EnterpriseTask",
"websiteURL": "https://mydomain.com/page-with-recaptcha-enterprise",
"websiteKey": "6Lcg7CMUAAAAANphynKgn9YAgA4tQ2KI_iqRyTwd",
"pageAction": "verify",
"enterprisePayload": {
"s": "SOME_ADDITIONAL_TOKEN"
}
}
}
{
"errorId":0,
"taskId":407533072
}
Ricezione del risultatohttps://api.capmonster.cloud/getTaskResult{
"clientKey":"API_KEY",
"taskId": 407533072
}
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AFcWeA66ZARdA5te7acD9vSwWE2hEQ2-B2aqFxm455iMA-g-Jis..."
}
}
Inserimento del token nella paginaimport { chromium } from 'playwright';
import { CapMonsterCloudClientFactory, ClientOptions, RecaptchaV2EnterpriseRequest } from '@zennolab_com/capmonstercloud-client';
(async () => {
const browser = await chromium.launch({ headless: false });
const context = await browser.newContext();
const page = await context.newPage();
// 2. Apri la pagina con la captcha
await page.goto('https://example.com');
// 3. Crea il client CapMonster Cloud
const cmcClient = CapMonsterCloudClientFactory.Create(
new ClientOptions({ clientKey: '<your_capmonster_cloud_api_key>' })
);
// 4. Configura la richiesta di soluzione
const recaptchaRequest = new RecaptchaV2EnterpriseRequest({
websiteURL: page.url(),
websiteKey: '6Lf76sUnAAAAAIKLuWNyegRsFUfmI-3Lex3xT5N'
// enterprisePayload: { s: 'SOME_ADDITIONAL_TOKEN' } // Parametro enterprise opzionale
});
// 5. Risolvi la captcha tramite CapMonster
const solution = await cmcClient.Solve(recaptchaRequest);
const token = solution.solution.gRecaptchaResponse;
console.log('Token del captcha:', token);
// 6. Inserisci il token in un campo nascosto
await page.evaluate((t) => {
const el = document.getElementById('g-recaptcha-response');
if (el) el.value = t;
}, token);
// 7. (Opzionale) Invia il form — adegua il selettore
await page.click('button[data-action="submit"]');
await page.waitForTimeout(5000);
await browser.close();
})();Poiché reCAPTCHA Enterprise viene eseguito su Google Cloud, devi prima creare un progetto nella console:
1. Vai alla Google Cloud Console.
2. Nel menu in alto scegli un progetto esistente oppure fai clic su Nuovo progetto.
3. Inserisci un nome per il progetto, specifica la tua organizzazione e conferma la creazione.
4. Apri la pagina dell’API: reCAPTCHA Enterprise API e fai clic su Abilita.
5. Vai a Crea chiave nella console e fai clic su Crea chiave.
6. Configura le impostazioni di base:
Poi apri Impostazioni aggiuntive, attiva Utilizzerai le challenge? e abilita Checkbox Challenge.
7. Fai clic su Crea. Riceverai una chiave che dovrai aggiungere al tuo sito per attivare la protezione.
8. Aggiungi lo script alla tua pagina.
Esempio di snippet HTML che puoi incorporare nel tuo sito<html>
<head>
<title>reCAPTCHA demo: Simple page</title>
<script src="https://www.google.com/recaptcha/enterprise.js" async defer></script>
</head>
<body>
<form action="" method="POST">
<div class="g-recaptcha" data-sitekey="YOUR_SITEKEY" data-action="LOGIN"></div>
<br/>
<input type="submit" value="Submit">
</form>
</body>
</html>9. Valida la risposta sul server.
Esempio in PHPIl token (g-recaptcha-response) viene inviato al backend.
È valido per 2 minuti, quindi verificalo appena lo ricevi! Per una comunicazione sicura con l’API consigliamo le librerie ufficiali di Google Cloud:
<?php
require 'vendor/autoload.php';
// Installa le librerie Google Cloud tramite Composer
use Google/Cloud/RecaptchaEnterprise/V1/RecaptchaEnterpriseServiceClient;
use Google/Cloud/RecaptchaEnterprise/V1/Event;
use Google/Cloud/RecaptchaEnterprise/V1/Assessment;
use Google/Cloud/RecaptchaEnterprise/V1/CreateAssessmentRequest;
use Google/Cloud/RecaptchaEnterprise/V1/TokenProperties/InvalidReason;
/**
* Valida il token di reCAPTCHA Enterprise e ottieni il punteggio di rischio.
*
* @param string $recaptchaKey Chiave reCAPTCHA del tuo sito/app
* @param string $token Token ricevuto dal client
* @param string $projectId ID del progetto Google Cloud
* @param string $action Nome dell’azione associata al token
*/
function create_assessment(string $recaptchaKey, string $token, string $projectId, string $action): void {
$client = new RecaptchaEnterpriseServiceClient();
$projectName = $client->projectName($projectId);
// Crea l’evento di valutazione (assessment)
$event = (new Event())->setSiteKey($recaptchaKey)->setToken($token);
$assessment = (new Assessment())->setEvent($event);
$request = (new CreateAssessmentRequest())->setParent($projectName)->setAssessment($assessment);
try {
$response = $client->createAssessment($request);
if (!$response->getTokenProperties()->getValid()) {
echo 'Token non valido: ' . InvalidReason::name($response->getTokenProperties()->getInvalidReason());
return;
}
if ($response->getTokenProperties()->getAction() === $action) {
echo 'Punteggio di rischio: ' . $response->getRiskAnalysis()->getScore();
} else {
echo 'L’azione nel tag reCAPTCHA non corrisponde al valore atteso';
}
} catch (Exception $e) {
echo 'Errore durante il controllo di reCAPTCHA: ' . $e->getMessage();
}
}
// Chiama la funzione con le variabili
create_assessment(
'YOUR_SITE_KEY',
'YOUR_USER_RESPONSE_TOKEN',
'YOUR_PROJECT_ID',
'YOUR_RECAPTCHA_ACTION'
);
?>
Se ti è capitato un sito con un captcha o un altro sistema di protezione già installato e senza accesso al codice, nessun problema! È piuttosto facile capire quale tecnologia viene utilizzata. Per verificare che tutto funzioni correttamente, puoi usare il servizio di riconoscimento CapMonster Cloud in un ambiente di test isolato, così da assicurarti che il meccanismo di elaborazione dei token e la logica di verifica funzionino correttamente.
Nel caso di reCAPTCHA v2 Enterprise, è sufficiente individuare il sistema, analizzarne il comportamento e assicurarsi che la protezione funzioni correttamente. Nell’articolo abbiamo mostrato come riconoscere reCAPTCHA v2 Enterprise e dove trovare le istruzioni per la sua integrazione o riconfigurazione, in modo da poter mantenere la protezione in modo affidabile e controllarne il funzionamento.
