Lindungi Web Traffic dengan AI CAPTCHA Click-and-Pass Verification - Edge Security Acceleration

Anda dapat mengintegrasikan AI CAPTCHA dalam dua langkah. Misalnya, tambahkan verifikasi Click-and-pass ke halaman logon di test.example.com/login.

Langkah 1: Konfigurasikan aturan CAPTCHA

Konfigurasikan informasi dasar, seperti URI yang akan diverifikasi dan jenis CAPTCHA.

Masuk ke Konsol ESA dan buka halaman konfigurasi AI CAPTCHA.
Pada halaman Configuration, klik Add Rule.
Pada halaman Add Rule, konfigurasikan parameter berikut:
- Rule Name: Masukkan nama kustom, misalnya login.
- API to Be Verified: Masukkan URI untuk integrasi CAPTCHA. Contohnya, masukkan test.example.com/login.
- Methods for Verification: Pilih metode permintaan yang memerlukan verifikasi CAPTCHA, seperti GET dan POST.
- Type: Pilih Click-and-Pass.
  Untuk informasi selengkapnya tentang jenis lainnya, lihat Jenis CAPTCHA dan Saran Pemilihan.

Langkah 2: Integrasikan kode frontend

Setelah menambahkan aturan validasi di Konsol, integrasikan kode inisialisasi CAPTCHA ke halaman web atau H5 yang memerlukan verifikasi. Hal ini menyelesaikan integrasi sisi klien.

Dapatkan informasi verifikasi identitas

ESA menggunakan Identity dan Scene ID untuk verifikasi identitas. Sebelum menambahkan kode frontend, dapatkan informasi berikut:

Identity: Nilai ini terletak di pojok kanan atas halaman Configuration.
Scene ID: ID ini terletak di kolom Scene ID untuk aturan yang sesuai pada halaman Configuration.

Tambahkan skrip

Pada kode frontend tempat Anda ingin menambahkan CAPTCHA, misalnya login.html, tambahkan tiga segmen skrip berikut:

Tambahkan variabel global AliyunCAPTCHAConfig: Tambahkan skrip yang mendefinisikan variabel global AliyunCAPTCHAConfig, yang berisi parameter region dan prefix. Tempatkan skrip ini sebelum menyertakan skrip JS CAPTCHA atau di bagian atas tag HTML head. Untuk informasi selengkapnya tentang parameter, lihat dokumen referensi.

<script>
  window.AliyunCaptchaConfig = {
    region: "cn",  // Wajib diisi. Menentukan wilayah tempat contoh Captcha diterapkan. Wilayah yang didukung meliputi Tiongkok daratan (cn) dan Singapura (sgp).
    prefix: "<span class="var-span" contenteditable="true" data-var="IDENTITY">IDENTITY"</span>,   // Wajib diisi. Token identitas. Ganti IDENTITY dengan token identitas yang Anda peroleh pada langkah sebelumnya, misalnya esa-q2*****cqb.
  };
</script>

Impor CAPTCHA JS secara dinamis: Setelah skrip variabel AliyunCAPTCHAConfig, tambahkan skrip JS untuk mengimpor CAPTCHA secara dinamis. Hal ini memungkinkan Anda memanggil CAPTCHA untuk verifikasi saat layanan Anda memerlukannya.
Catatan
Anda harus mengimpor CAPTCHA JS secara dinamis. Jika Anda menggunakan metode lain untuk menghindari pemuatan dinamis, seperti menarik kode JS untuk penerapan lokal, CAPTCHA tidak dapat diperbarui. Hal ini mengompromikan keamanan dan dapat menyebabkan pemblokiran salah atau masalah kompatibilitas.
```
<script
  type="text/javascript"
  src="https://o.alicdn.com/CAPTCHA-frontend/aliyunCAPTCHA/AliyunCAPTCHA.js"
></script>
```
Tambahkan metode inisialisasi CAPTCHA: Panggil metode inisialisasi initAliyunCAPTCHA untuk menginisialisasi CAPTCHA. Untuk informasi selengkapnya, lihat parameter initAliyunCAPTCHA.
Catatan
Jangan memanggil fungsi inisialisasi initAliyunCAPTCHA berulang kali, kecuali dalam skenario yang diperlukan, seperti ketika parameter inisialisasi berubah. Jika inisialisasi gagal, lihat kesalahan inisialisasi sisi klien untuk troubleshooting.
```
<script type="text/javascript">
  var CAPTCHA;
  window.initAliyunCAPTCHA({...});
</script>
```

Kode Contoh

Gunakan kode contoh berikut sebagai referensi untuk menambahkan CAPTCHA ke kode frontend Anda.

Catatan

Muat CAPTCHA JS sedini mungkin. Hal ini memungkinkan skrip mengumpulkan informasi lingkungan dan perangkat yang lebih lengkap. Interval antara pemuatan CAPTCHA JS dan permintaan verifikasi harus lebih dari 2 detik.
Untuk memastikan resource gambar dimuat lebih cepat, inisialisasi CAPTCHA sedini mungkin. Interval antara inisialisasi dan permintaan verifikasi harus lebih dari 2 detik. Hal ini memungkinkan resource CAPTCHA terkait dimuat terlebih dahulu, sehingga mempercepat pemuatan gambar.
Dalam kode sumber klien, buat elemen placeholder untuk CAPTCHA. Ini adalah elemen Model Objek Dokumen (DOM) yang ditentukan oleh parameter element dan button, seperti <div id="CAPTCHA-element"></div> pada contoh berikut.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="data-spm" />
    <!--1. Sebelum skrip yang mengimpor JS Alibaba Cloud CAPTCHA, atau di awal tag head HTML, tambahkan skrip. Skrip ini menyimpan variabel global bernama AliyunCAPTCHAConfig yang berisi parameter region dan prefix.-->
    <script>
      window.AliyunCAPTCHAConfig = {
        region: "cn",
        prefix: "{{IDENTITY}}",
      };
    </script>
    <!--2. Integrasikan JS utama.-->
    <script
      type="text/javascript"
      src="https://o.alicdn.com/CAPTCHA-frontend/aliyunCAPTCHA/AliyunCAPTCHA.js"
    ></script>
  </head>

  <body>
    <div id="CAPTCHA-element"></div>
    <!--Elemen placeholder untuk CAPTCHA. Digunakan untuk mengonfigurasi parameter element pada fungsi inisialisasi.-->
    <button id="button" class="btn">Log on</button>
    <!--Dalam mode pop-up, ini adalah elemen yang memicu jendela pop-up CAPTCHA.-->
    <!--3. Buat tag <script> baru untuk memanggil fungsi inisialisasi CAPTCHA initAliyunCAPTCHA.-->
    <script type="text/javascript">
      var CAPTCHA;
      window.initAliyunCAPTCHA({
        SceneId: "{{SCENE_ID}}",  // Scene ID. Setelah membuat skenario verifikasi di Langkah 2, Anda dapat memperoleh scene ID dari daftar skenario CAPTCHA.
        mode: "popup",  // Mode CAPTCHA. popup menunjukkan mode pop-up. embed menunjukkan mode embedded. Anda tidak perlu mengubah ini.
        // Elemen placeholder pada halaman untuk rendering CAPTCHA. Harus konsisten dengan elemen placeholder pada kode asli.
        element: "#CAPTCHA-element", 
        button: "#button",  // ID elemen yang memicu jendela pop-up CAPTCHA atau verifikasi tanpa-CAPTCHA.
        // Fungsi callback untuk verifikasi CAPTCHA yang berhasil.
        success: function (CAPTCHAVerifyParam) {
          // Parameter input adalah CAPTCHAVerifyParam untuk verifikasi signature.
          // 1. Kirim permintaan layanan ke backend (yaitu ESA) untuk melakukan verifikasi signature pada CAPTCHAVerifyParam.
          // 2. Proses layanan berdasarkan hasil verifikasi.
          // 3. Jika layanan memerlukan verifikasi ulang, panggil fungsi inisialisasi initAliyunCAPTCHA untuk menginisialisasi ulang CAPTCHA.
          console.log('SUCCESS'); // Cetak SUCCESS ke konsol.
        },
        // Fungsi callback untuk verifikasi CAPTCHA yang gagal.
        fail: function (result) {
          // Parameter input berisi informasi kegagalan.
          // Dalam periode validitas normal, tidak diperlukan tindakan apa pun. CAPTCHA akan otomatis refresh untuk verifikasi ulang.
          console.error(result);
        },
        // Fungsi callback untuk melampirkan instans CAPTCHA. Callback ini dipanggil setelah CAPTCHA berhasil diinisialisasi.
        getInstance: function (instance) {
          CAPTCHA = instance;
        },
        // Menentukan nama domain layanan untuk ESA. Anda tidak perlu mengubah ini.
        server: ['CAPTCHA-esa-open.aliyuncs.com', 'CAPTCHA-esa-open-b.aliyuncs.com'],
        // Gaya kotak pemicu untuk jenis verifikasi Slider dan Click-and-pass. Anda dapat menyesuaikan lebar dan tinggi dalam satuan px.
        slideStyle: {
          width: 360,
          height: 40,
        },
        // ...Untuk parameter lainnya, lihat deskripsi parameter initAliyunCAPTCHA.
      });
    </script>
  </body>
</html>

Saat Anda memanggil callback success: function (CAPTCHAVerifyParam), klien mengirim permintaan ke ESA yang mencakup parameter verifikasi signature CAPTCHAVerifyParam. Anda dapat menempatkan CAPTCHAVerifyParam dalam parameter permintaan atau header permintaan. Untuk informasi selengkapnya, lihat contoh berikut:

Parameter verifikasi signature sebagai parameter URI

async function CAPTCHAVerifyCallback(CAPTCHAVerifyParam) {
    // 1. Kirim permintaan layanan ke ESA untuk memperoleh hasil verifikasi CAPTCHA dan hasil bisnis.
    const result = await fetch('${URI verifikasi bisnis (URI yang dikonfigurasi untuk CAPTCHA di Konsol ESA)}?CAPTCHA_verify_param=' + CAPTCHAVerifyParam, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json'},
        body: JSON.stringify({
            // Parameter bisnis kustom
            //BizParam:
        }),
        credentials: 'include'
    });
    const verify_code = result.headers.get('X-CAPTCHA-Verify-Code')
    if (verify_code === 'T001') {
        alert('Verifikasi CAPTCHA berhasil!');
    } else {
        alert('Verifikasi CAPTCHA gagal: ', verify_code)
    }
    CAPTCHA.refresh()
    const data = await result.json()
    return data
}

Parameter verifikasi signature sebagai nilai Header

async function CAPTCHAVerifyCallback(CAPTCHAVerifyParam) {
    // 1. Kirim permintaan layanan ke ESA untuk memperoleh hasil verifikasi CAPTCHA dan hasil bisnis.
    const result = await fetch('${URI verifikasi bisnis (URI yang dikonfigurasi untuk CAPTCHA di Konsol ESA)}', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'CAPTCHA-verify-param': CAPTCHAVerifyParam},
        body: JSON.stringify({
            BizParam: document.getElementById('biz_result').value
        }),
        credentials: 'include'
    });
    const verify_code = result.headers.get('X-CAPTCHA-Verify-Code')
    if (verify_code === 'T001') {
        alert('Verifikasi CAPTCHA berhasil!');
    } else {
        alert('Verifikasi CAPTCHA gagal: ', verify_code)
    }
    CAPTCHA.refresh()
    const data = await result.json()
    return data
}

Setelah verifikasi signature di sisi server, ESA mengembalikan kode alasan x-CAPTCHA-verify-code dalam header respons. Klien Anda dapat memproses permintaan berdasarkan apakah verifikasi berhasil atau gagal:

Kode Alasan	Penyebab
T001	Verifikasi berhasil.
F003	Gagal mengurai `CAPTCHAVerifyParam`.
F005	Scene ID (`SceneId`) tidak ada.
F017	Konten `VerifyToken` telah dimodifikasi.
F018	Data verifikasi signature digunakan kembali.
F019	Verifikasi signature timeout (berlaku selama 90 detik) atau dilakukan sebelum verifikasi dimulai.
F020	Tiket verifikasi signature tidak sesuai dengan Scene ID atau pengguna.
F021	`SceneId` yang digunakan untuk verifikasi tidak sesuai dengan `SceneId` yang digunakan untuk verifikasi tanda tangan.

Referensi

`AliyunCAPTCHAConfig` Deskripsi Parameter

Parameter

Type

Wajib

Bawaan

Deskripsi

region

String

Didukung

cn

Wilayah tempat instans CAPTCHA berada. Nilai yang valid:

cn: Tiongkok daratan.
sgp: Singapura.

Produk CAPTCHA memiliki lapisan kontrol di Tiongkok daratan (Tiongkok (Shanghai)) dan Singapura. Berdasarkan parameter panggilan yang Anda konfigurasi, data perilaku, data perangkat, dan data lain yang dikumpulkan oleh klien dikirim ke pusat yang sesuai untuk diproses. Hal ini terutama untuk otentikasi keamanan.

prefix

String

Didukung

Tidak ada

Identitas CAPTCHA.

`initAliyunCAPTCHA` Deskripsi Parameter

Parameter	Tipe	Wajib	Bawaan	Deskripsi
SceneId	String	Didukung	Tidak ada	Scene ID CAPTCHA.
mode	String	Didukung	Tidak ada	Mode CAPTCHA. Opsi: `popup`: Menentukan mode pop-up. `embed`: Menentukan mode embedded (tidak berlaku untuk verifikasi tanpa-CAPTCHA).
element	String	Didukung	Tidak ada	Elemen placeholder pada halaman untuk rendering CAPTCHA. Harus konsisten dengan elemen placeholder pada kode sumber.
button	String	Didukung	Tidak ada	Elemen yang memicu jendela pop-up CAPTCHA atau verifikasi tanpa-CAPTCHA. Saat diklik, elemen ini menampilkan CAPTCHA atau memicu verifikasi tanpa-CAPTCHA. Nilainya harus sama dengan nilai parameter `button` pada `body` klien.
success	Function	Didukung	Tidak ada	Fungsi callback untuk verifikasi CAPTCHA yang berhasil. Fungsi ini mengekspos parameter verifikasi. Dalam fungsi callback ini, klien dapat memperoleh `CAPTCHAVerifyParam` dan meminta server klien untuk memverifikasi `CAPTCHAVerifyParam`.
fail	Function	Tidak didukung	Tidak ada	Fungsi callback untuk verifikasi CAPTCHA yang gagal. Fungsi ini mengekspos kode kesalahan kegagalan.
getInstance	Function	Didukung	`getInstance`	Fungsi callback untuk melampirkan instans CAPTCHA. Callback ini dipanggil setelah CAPTCHA berhasil diinisialisasi. Harus ditulis sebagai berikut: `function getInstance(instance) { CAPTCHA = instance; }`
slideStyle	Object	Tidak didukung	`{ width: 360, height: 40 }`	Gaya kotak pemicu untuk jenis verifikasi Slider dan Click-and-pass. Anda dapat menyesuaikan lebar dan tinggi dalam satuan px. Parameter ini kompatibel dengan nama parameter historis. Catatan: Karena CAPTCHA perlu mengumpulkan informasi yang cukup selama penggeseran agar model kebijakan dapat membuat penilaian, atur lebar minimum slider menjadi 320 px. Jika lebarnya kurang dari 320 px, sistem akan mengonfigurasinya menjadi 320 px. Parameter ini tidak berlaku untuk verifikasi Puzzle atau Image Restore. Jika Anda menggunakan CAPTCHA Puzzle, jangan mengganti CSS untuk memaksa mengubah gaya. Ukuran gambar dan jawaban verifikasi untuk CAPTCHA Puzzle telah ditentukan sebelumnya. Memaksa mengubah gaya akan menyebabkan verifikasi gagal.
language	String	Tidak didukung	`cn`	Bahasa yang didukung oleh CAPTCHA: `cn`: Bahasa Tionghoa Sederhana `tw`: Bahasa Tionghoa Tradisional `en`: Bahasa Inggris `ar`: Bahasa Arab `de`: Bahasa Jerman `es`: Bahasa Spanyol `fr`: Bahasa Prancis `in`: Bahasa Indonesia `it`: Bahasa Italia `ja`: Bahasa Jepang `ko`: Bahasa Korea `pt`: Bahasa Portugis `ru`: Bahasa Rusia `ms`: Malaysia `th`: Bahasa Thailand `tr`: Türkiye `vi`: Bahasa Vietnam
timeout	Number	Tidak didukung	`5000`	Periode timeout untuk satu permintaan inisialisasi CAPTCHA, dalam milidetik.
rem	Number	Tidak	`1`	Skala seluruh UI CAPTCHA. Masukkan angka positif. Misalnya, `0.5` memperkecil ukuran menjadi separuhnya, dan `2` memperbesar ukuran menjadi dua kali lipat. rem parameter terutama ditujukan untuk browser seluler.
onError	Function	Tidak didukung	Tidak ada	Fungsi callback kesalahan untuk permintaan inisialisasi CAPTCHA yang gagal atau timeout serta pemuatan resource. Harus ditulis sebagai berikut: `function onError(errorInfo) { const {code, msg} = errorInfo; console.log(code, msg); }`
onClose	Function	Tidak didukung	Tidak ada	Fungsi callback yang dipicu saat jendela pop-up CAPTCHA ditutup.
showErrorTip	Boolean	Tidak didukung	true	Menentukan apakah akan menampilkan tip kesalahan untuk pengecualian akses saat kualitas jaringan buruk.
delayBeforeSuccess	Boolean	Tidak	true	Menentukan apakah akan menunda pemicuan fungsi callback `success` selama 1 detik setelah verifikasi berhasil.

Contoh kode untuk parameter rem

const customWidth = 360;
function initCAPTCHA(rem) {
  window.initAliyunCAPTCHA({
    SceneId: "xxxxxx",
    mode: "popup",
    element: "#CAPTCHA-element",
    button: "#CAPTCHA-button",
    success: success,
    fail: fail,
    getInstance: getInstance,
    slideStyle: {
      width: customWidth,
      height: 40,
    },
    language: "cn",
    rem: rem,
  });
}

const pageWidth = window.innerWidth;
if (pageWidth <= customWidth) {
  const rem = Math.floor(pageWidth / customWidth * 100) / 100;
  initCAPTCHA(rem);
}

Catatan tentang Pemanggilan CAPTCHA dalam Mode Tanpa-CAPTCHA

Anda dapat memanggil metode yang sesuai untuk instans CAPTCHA. Metode berikut tidak didukung untuk verifikasi awal dalam mode penyamaran.

Nama Metode	Deskripsi	Contoh	Skenario
show	Menampilkan elemen CAPTCHA dan mask.	`CAPTCHA.show()`	Gunakan ini saat Anda memerlukan jendela pop-up CAPTCHA muncul secara otomatis tanpa klik tombol.
hide	Menyembunyikan atau menutup elemen CAPTCHA dan mask.	`CAPTCHA.hide()`	Gunakan ini saat Anda memerlukan jendela pop-up CAPTCHA ditutup secara otomatis tanpa klik tombol.