Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Halaman ini menjelaskan cara memberikan masukan tentang akurasi
penilaian yang dibuat oleh reCAPTCHA. Dengan informasi ini, reCAPTCHA dapat menyesuaikan model khusus situs Anda dan memberikan performa yang lebih baik untuk situs Anda dari waktu ke waktu.
Kapan harus menganotasi penilaian
reCAPTCHA memberikan skor saat membuat penilaian yang membantu Anda memahami tingkat risiko yang ditimbulkan oleh interaksi pengguna.
Kemudian, saat situs Anda memiliki lebih banyak informasi tentang interaksi pengguna untuk menentukan apakah interaksi tersebut sah atau menipu, Anda dapat mengonfirmasi atau memperbaiki penilaian reCAPTCHA. Untuk melakukannya, Anda mengirimkan
ID penilaian reCAPTCHA kembali ke Google yang diberi label sebagai LEGITIMATE
atau FRAUDULENT.
Mengonfirmasi atau memperbaiki penilaian reCAPTCHA akan meningkatkan performa reCAPTCHA untuk situs Anda.
Untuk meningkatkan performa reCAPTCHA, Anda dapat mengonfirmasi
anotasi untuk positif benar dan negatif benar selain
anotasi untuk potensi error penilaian.
Misalnya, untuk pengguna yang berhasil diautentikasi menggunakan
metode autentikasi 2 faktor dan menerima skor reCAPTCHA yang tinggi, Anda dapat
menambahkan anotasi pada penilaian sebagai LEGITIMATE. Atau, jika skor reCAPTCHA rendah dan situs Anda menentukan bahwa interaksi tersebut bersifat menipu atau melanggar, Anda dapat menganotasi penilaian sebagai FRAUDULENT.
Daftar berikut menunjukkan informasi tambahan tentang beberapa contoh interaksi
pengguna yang menunjukkan apakah interaksi pengguna tersebut sah atau
menipu:
Penagihan balik kartu kredit atau bukti konkret penipuan lainnya menunjukkan bahwa
transaksi keuangan sebelumnya bersifat menipu.
Akun baru yang mengirim pesan yang ditandai sebagai spam oleh pengguna lain
mungkin menunjukkan bahwa pembuatan akun tersebut bersifat menipu.
Kasus dukungan yang diajukan jika pengguna mengalami kesulitan login ke akunnya
mungkin menunjukkan bahwa upaya login tersebut sah.
Pembelian atau pemesanan di situs yang menggunakan reCAPTCHA untuk
melawan scraping dapat menunjukkan bahwa pengguna tersebut sah.
Sebelum memulai
Pastikan Anda memiliki peran Identity and Access Management berikut: reCAPTCHA Enterprise Agent (roles/recaptchaenterprise.agent).
Bergantung pada tempat Anda menyiapkan reCAPTCHA, selesaikan langkah yang sesuai:
Untuk integrasi WAF, Anda dapat mengambil ID penilaian unik dari
token reCAPTCHA. ID penilaian unik adalah
string alfanumerik unik yang terdiri dari 16 karakter yang muncul di akhir
token reCAPTCHA setelah :U=. Misalnya, jika token reCAPTCHA adalah
.................U=6ZZZZe73fZZZZZZ0, ID penilaiannya adalah 6ZZZZe73fZZZZZZ0.
Membuat anotasi penilaian
Tentukan informasi dan label yang akan ditambahkan dalam isi JSON permintaan,
bergantung pada kasus penggunaan Anda.
Tabel berikut mencantumkan label dan nilai yang dapat Anda gunakan untuk menganotasi peristiwa:
Label
Deskripsi
Contoh permintaan
reasons
Opsional. Label untuk mendukung
penilaian Anda.
Berikan detail peristiwa real-time di label reasons dalam beberapa detik atau menit setelah peristiwa karena hal ini memengaruhi deteksi real-time.
Untuk mengetahui daftar
nilai yang memungkinkan,
lihat nilai alasan.
Contoh: Untuk mendeteksi pengambilalihan akun, anotasikan apakah sandi yang dimasukkan
sudah benar dengan nilai CORRECT_PASSWORD atau
INCORRECT_PASSWORD. Jika men-deploy MFA Anda sendiri,
Anda dapat menambahkan nilai berikut: INITIATED_TWO_FACTOR, dan
PASSED_TWO_FACTOR atau FAILED_TWO_FACTOR.
{
"reasons": ["INCORRECT_PASSWORD"]
}
annotation
Opsional. Label untuk menunjukkan
legitimasi penilaian.
Berikan fakta tentang peristiwa login dan
pendaftaran untuk memvalidasi atau memperbaiki penilaian risiko Anda di
label annotation.
Kemungkinan nilai: LEGITIMATE
atau FRAUDULENT.
Anda dapat mengirimkan informasi ini kapan saja atau sebagai bagian dari tugas batch.
Namun, sebaiknya kirim informasi ini dalam beberapa detik atau menit
setelah peristiwa karena informasi ini memengaruhi deteksi real-time.
Sebelum menggunakan salah satu data permintaan,
lakukan penggantian berikut:
ASSESSMENT_ID: Nilai kolom name yang ditampilkan dari panggilan projects.assessments.create.
ANNOTATION_LABEL: Label untuk menunjukkan apakah penilaian tersebut sah atau menipu.
Kemungkinan nilainya adalah LEGITIMATE atau FRAUDULENT.
ANNOTATION_REASON: Menjelaskan konteks untuk anotasi yang dipilih untuk penilaian ini.
Untuk mempelajari kemungkinan nilai, lihat alasan menganotasi penilaian.
Metode HTTP dan URL:
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
Anda akan menerima kode status yang menandakan proses berhasil (2xx), dan sebuah respons kosong.
Kunci API
Sebelum menggunakan salah satu data permintaan,
lakukan penggantian berikut:
ASSESSMENT_ID: Nilai kolom name yang ditampilkan dari panggilan projects.assessments.create
ANNOTATION_LABEL: Label untuk menunjukkan apakah penilaian tersebut sah atau menipu.
Kemungkinan nilainya adalah LEGITIMATE atau FRAUDULENT.
ANNOTATION_REASON: Menjelaskan konteks untuk anotasi yang dipilih untuk penilaian ini.
Untuk mempelajari kemungkinan nilai, lihat alasan menganotasi penilaian.
Metode HTTP dan URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 2025-09-04 UTC."],[],[],null,["# Annotate assessments\n\nThis page explains how you can provide feedback on the accuracy of the\nassessments created by reCAPTCHA. With this information,\nreCAPTCHA can tune your site-specific model and provide\nimproved performance for your site over time.\n\nWhen to annotate assessments\n----------------------------\n\nreCAPTCHA provides a score when creating an assessment that\nhelps you understand the level of risk user interactions pose.\nLater, when your site has more information about user interactions\nto determine if the interaction was legitimate or fraudulent, you can confirm or\ncorrect reCAPTCHA's assessment. To do this, you send the\nreCAPTCHA assessment IDs back to Google labeled as `LEGITIMATE`\nor `FRAUDULENT`.\nConfirming or correcting\nreCAPTCHA's assessment improves the performance of\nreCAPTCHA for your site.\n\nTo improve the performance of reCAPTCHA, you can confirm the\nannotations for **true positives** and **true negatives** in addition to the\nannotations for potential assessment errors.\nFor example, for a user who successfully authenticated using\na 2-factor-authentication method and received a high reCAPTCHA score, you can\nannotate the assessment as `LEGITIMATE`. Alternatively, if reCAPTCHA\nscore was low and your site determined that the interaction was fraudulent or\nabusive, you can annotate the assessment as `FRAUDULENT`.\n\nThe following list shows additional information about some sample user\ninteractions that indicate whether a user interaction is legitimate or\nfraudulent:\n\n- Credit card chargebacks or other concrete evidence of fraud indicate that an earlier financial transaction was fraudulent.\n- A new account that sends messages that are flagged as spam by other users might indicate that the account creation was fraudulent.\n- A support case filed if a user has difficulty logging in to their account might indicate that the login attempt is legitimate.\n- A purchase or booking on a site that uses reCAPTCHA to defend against scraping might indicate that the user is legitimate.\n\nBefore you begin\n----------------\n\n- Ensure that you have the following Identity and Access Management role:\n reCAPTCHA Enterprise Agent (`roles/recaptchaenterprise.agent`).\n\n- Depending on where you have set up reCAPTCHA, complete the\n appropriate step:\n\n - [Create an assessment for your website](/recaptcha/docs/create-assessment-website).\n - [Create an assessment for your mobile application](/recaptcha/docs/create-assessment-mobile).\n - [Set up your WAF integration](/recaptcha/docs/setup-overview-waf).\n\nRetrieve the assessment ID\n--------------------------\n\nTo annotate an assessment, retrieve the unique assessment ID in the\nfollowing ways:\n\n- For web and mobile integrations, you can retrieve the unique assessment ID\n from the assessment response.\n\n After you create an assessment, you receive a JSON response as shown in the\n following example.\n\n Retrieve the unique assessment ID from the `name` field in the JSON response. \n\n ```bash\n {\n 'tokenProperties': {\n 'valid': True,\n 'hostname': 'www.google.com',\n 'action': 'homepage',\n 'createTime': u'2019-03-28T12:24:17.894Z'\n },\n 'riskAnalysis': {\n 'score': 0.1,\n 'reasons': ['AUTOMATION']\n },\n 'event': {\n 'token': 'RESPONSE_TOKEN',\n 'siteKey': 'KEY_ID'\n },\n 'name': 'ASSESSMENT_ID'\n }\n ```\n- For WAF integrations, you can retrieve the unique assessment ID from the\n reCAPTCHA token. The unique assessment ID is the\n unique alphanumeric string of 16 characters that appears at the end of the\n reCAPTCHA token after `:U=`. For example, if the reCAPTCHA token is\n `.................U=6ZZZZe73fZZZZZZ0`, then the assessment ID is `6ZZZZe73fZZZZZZ0`.\n\nAnnotate an assessment\n----------------------\n\n1.\n\n Determine the information and labels to add in the request JSON body\n depending on your use case.\n\n The following table lists the labels and values that you can use to annotate\n events:\n\n \u003cbr /\u003e\n\n2. Annotate an assessment using the\n [`projects.assessments.annotate`](/recaptcha/docs/reference/rest/v1/projects.assessments/annotate)\n method with the gcloud CLI or an API key.\n\n **Note:** If you are using the `v1beta1` version of the API, we recommend using the `v1` version because the new features, such as reCAPTCHA account defender are available only on `v1` version. For migrating from `v1beta1` to `v1`, see [Migrate from v1beta API to v1 API](/recaptcha/docs/migration-v1). \n\n ### gcloud CLI\n\n\n Before using any of the request data,\n make the following replacements:\n - \u003cvar translate=\"no\"\u003eASSESSMENT_ID\u003c/var\u003e: Value of the `name` field returned from the `projects.assessments.create` call.\n - \u003cvar translate=\"no\"\u003eANNOTATION_LABEL\u003c/var\u003e: The label to indicate whether the assessment is legitimate or fraudulent. Possible values are `LEGITIMATE` or `FRAUDULENT`.\n - \u003cvar translate=\"no\"\u003eANNOTATION_REASON\u003c/var\u003e: Describes the context for the annotation that was chosen for this assessment. To learn about possible values, see [reasons for annotating an assessment](https://cloud.google.com/recaptcha/docs/reference/rest/v1/projects.assessments/annotate#reason).\n\n\n HTTP method and URL:\n\n ```\n POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate\n ```\n\n\n Request JSON body:\n\n ```\n {\n \"annotation\": \"ANNOTATION_LABEL\"\n \"reasons\": \"ANNOTATION_REASON\"\n }\n ```\n\n To send your request, choose one of these options: \n\n #### curl\n\n | **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) , or by using [Cloud Shell](/shell/docs), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n curl -X POST \\\n -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n -d @request.json \\\n \"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate\"\n ```\n\n #### PowerShell\n\n | **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n $cred = gcloud auth print-access-token\n $headers = @{ \"Authorization\" = \"Bearer $cred\" }\n\n Invoke-WebRequest `\n -Method POST `\n -Headers $headers `\n -ContentType: \"application/json; charset=utf-8\" `\n -InFile request.json `\n -Uri \"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate\" | Select-Object -Expand Content\n ```\n\n You should receive a successful status code (2xx) and an empty response.\n\n \u003cbr /\u003e\n\n ### API key\n\n\n Before using any of the request data,\n make the following replacements:\n - \u003cvar translate=\"no\"\u003eASSESSMENT_ID\u003c/var\u003e: Value of the `name` field returned from the `projects.assessments.create` call\n - \u003cvar translate=\"no\"\u003eANNOTATION_LABEL\u003c/var\u003e: The label to indicate whether the assessment is legitimate or fraudulent. Possible values are `LEGITIMATE` or `FRAUDULENT`.\n - \u003cvar translate=\"no\"\u003eANNOTATION_REASON\u003c/var\u003e: Describes the context for the annotation that was chosen for this assessment. To learn about possible values, see [reasons for annotating an assessment](https://cloud.google.com/recaptcha/docs/reference/rest/v1/projects.assessments/annotate#reason).\n\n\n HTTP method and URL:\n\n ```\n POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY\n ```\n\n\n Request JSON body:\n\n ```\n {\n \"annotation\": \"ANNOTATION_LABEL\"\n \"reasons\": \"ANNOTATION_REASON\"\n }\n ```\n\n To send your request, choose one of these options: \n\n #### curl\n\n | **Note:** Create an [API key](https://cloud.google.com/docs/authentication/api-keys#creating_an_api_key) to authenticate with the API.\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n curl -X POST \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n -d @request.json \\\n \"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY\"\n ```\n\n #### PowerShell\n\n | **Note:** Create an [API key](https://cloud.google.com/docs/authentication/api-keys#creating_an_api_key) to authenticate with the API.\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n $headers = @{ }\n\n Invoke-WebRequest `\n -Method POST `\n -Headers $headers `\n -ContentType: \"application/json; charset=utf-8\" `\n -InFile request.json `\n -Uri \"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY\" | Select-Object -Expand Content\n ```\n\n You should receive a successful status code (2xx) and an empty response.\n\n \u003cbr /\u003e\n\nWhat's next\n-----------\n\n- Learn about the [user accounts protection features of reCAPTCHA](/recaptcha/docs/protect-accounts-overview)."]]
