Membuat anotasi penilaian

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

Mengambil ID penilaian

Untuk menganotasi penilaian, ambil ID penilaian unik dengan cara berikut:

  • Untuk integrasi web dan seluler, Anda dapat mengambil ID penilaian unik dari respons penilaian.

    Setelah membuat penilaian, Anda akan menerima respons JSON seperti yang ditunjukkan dalam contoh berikut.

    Ambil ID penilaian unik dari kolom name dalam respons JSON.

    {
'tokenProperties': {
  'valid': True,
  'hostname': 'www.google.com',
  'action': 'homepage',
  'createTime': u'2019-03-28T12:24:17.894Z'
},
'riskAnalysis': {
  'score': 0.1,
  'reasons': ['AUTOMATION']
},
'event': {
  'token': 'RESPONSE_TOKEN',
  'siteKey': 'KEY_ID'
},
'name': 'ASSESSMENT_ID'
}

  • 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

  1. 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.

    		 
          {
       "annotation": "LEGITIMATE"
      }

  2. Anotasikan penilaian menggunakan metode projects.assessments.annotate dengan gcloud CLI atau kunci API.

    gcloud CLI

    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

    Isi JSON permintaan: 

    {
"annotation": "ANNOTATION_LABEL"
"reasons": "ANNOTATION_REASON"
}

    Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

    curl

    Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate"

    PowerShell

    Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate" | Select-Object -Expand Content

    Anda akan menerima kode status yang berhasil (2xx) dan 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

    Isi JSON permintaan: 

    {
"annotation": "ANNOTATION_LABEL"
"reasons": "ANNOTATION_REASON"
}

    Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

    curl

    Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

    curl -X POST \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY"

    PowerShell

    Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

    $headers = @{  }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY" | Select-Object -Expand Content

    Anda akan menerima kode status yang berhasil (2xx) dan respons kosong.

Langkah selanjutnya