Integrasi klien Web dan H5 V3 - Captcha - Alibaba Cloud Documentation Center

Captcha 2.0 menggunakan dua entri konfigurasi yang harus diatur dalam urutan tertentu. Sebelum halaman dimuat, definisikan variabel global AliyunCaptchaConfig untuk mengidentifikasi instans Anda. Setelah halaman dimuat, panggil initAliyunCaptcha untuk merender widget CAPTCHA dan menangani hasil verifikasi. Topik ini menjelaskan cara menyelesaikan kedua langkah tersebut.

Catatan

Arsitektur V3 tidak didukung untuk mini program WeChat. Jika layanan Anda menggunakan arsitektur V2, lihat Integrasikan dengan klien Web dan H5 menggunakan arsitektur V2.

Prasyarat

Sebelum memulai, pastikan Anda telah:

Mengaktifkan Alibaba Cloud Captcha 2.0
Membuat skenario verifikasi dengan Integration Method diatur ke Web/H5

Cara kerja

Integrasi mengikuti tiga langkah dalam urutan berikut:

Definisikan AliyunCaptchaConfig di bagian <head> HTML sebelum file JS Captcha dimuat.
Muat file JS Captcha secara dinamis dari CDN Alibaba Cloud.
Panggil initAliyunCaptcha untuk merender widget CAPTCHA dan mendaftarkan callback.

Siklus hidup verifikasi lengkap bekerja sebagai berikut:

Pemuatan halaman: File JS Captcha dimuat dan mulai mengumpulkan data lingkungan serta perangkat.
Rendering widget: initAliyunCaptcha merender widget dan memuat sumber daya gambar terlebih dahulu.
Interaksi pengguna: Pengguna memicu widget. Captcha 2.0 menganalisis sinyal perilaku dan perangkat.
Generasi token: Saat berhasil, Captcha 2.0 mengembalikan captchaVerifyParam ke callback success.
Validasi server: Backend Anda mengirim captchaVerifyParam ke API sisi server Captcha 2.0 untuk memvalidasinya. Lakukan tindakan sesuai hasilnya dalam logika bisnis Anda.

Penting

Interval antara pemuatan file JS Captcha dan pengiriman permintaan verifikasi harus lebih dari 2 detik. Interval antara inisialisasi dan pengiriman permintaan verifikasi juga harus lebih dari 2 detik. Muat file JS dan panggil initAliyunCaptcha sedini mungkin agar Captcha memiliki cukup waktu untuk mengumpulkan data lingkungan dan memuat sumber daya gambar terlebih dahulu.

Pilih mode

initAliyunCaptcha mendukung dua mode rendering. Pilih salah satu sebelum memulai integrasi.

	Mode popup	Embedded Mode
Trigger	Klik tombol membuka kotak dialog CAPTCHA	Widget selalu terlihat di halaman
Elemen DOM yang diperlukan	Ya — elemen container dan elemen tombol	Ya — elemen container
Dukungan no-captcha	Ya	Tidak — verifikasi no-captcha memerlukan mode popup
Disarankan untuk	Sebagian besar kasus penggunaan, termasuk formulir login dan registrasi	Halaman tempat widget CAPTCHA merupakan elemen UI permanen

Integrasikan Captcha 2.0

Langkah 1: Tambahkan variabel global AliyunCaptchaConfig

Di bagian <head> HTML, tambahkan blok <script> yang mendefinisikan window.AliyunCaptchaConfig sebelum referensi apa pun ke file JS Captcha.

<script>
  window.AliyunCaptchaConfig = {
    // Wajib. Nilai yang valid: cn (Tiongkok daratan), sgp (Singapura).
    region: "cn",
    // Wajib. Dapatkan nilai ini dari Overview > Cumulative Activation Time > Identity Prefix di Konsol.
    prefix: "xxxxxx",
  };
</script>

Penting

Dapatkan awalan identitas dari Overview > Cumulative Activation Time > Identity Prefix di Konsol, seperti yang ditunjukkan di bawah ini:

Nilai region menentukan lapisan kontrol yang digunakan Captcha 2.0 untuk memproses data perilaku dan perangkat. Titik akhir sisi server harus sesuai: gunakan titik akhir Tiongkok daratan ketika region adalah cn, dan titik akhir Singapura ketika region adalah sgp. Untuk detail titik akhir, lihat Akses sisi server.

Langkah 2: Memuat file JS Captcha secara dinamis

Tambahkan tag <script> berikut untuk memuat file JS Captcha dari CDN Alibaba Cloud:

<script
  type="text/javascript"
  src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
></script>

Penting

Selalu muat file JS Captcha secara dinamis dari CDN. Mengunduh dan menghostingnya secara lokal mencegah layanan Captcha menerima pembaruan, yang dapat mengompromikan keamanan serta menyebabkan pemblokiran atau masalah kompatibilitas.

Langkah 3: Inisialisasi Captcha

Setelah halaman dimuat, panggil initAliyunCaptcha sekali untuk merender widget dan mengikat callback verifikasi.

<script type="text/javascript">
  var captcha;
  window.initAliyunCaptcha({
    // ... parameter selain region dan prefix
  });
</script>

Catatan

Panggil initAliyunCaptcha hanya sekali per pemuatan halaman. Lakukan inisialisasi ulang hanya dalam skenario tertentu, seperti saat parameter inisialisasi berubah. Jika inisialisasi gagal, lihat Error inisialisasi sisi klien untuk troubleshooting.

Contoh kode

Contoh lengkap berikut menunjukkan integrasi mode popup. Halaman menyediakan dua elemen DOM: satu untuk container widget CAPTCHA dan satu untuk tombol pemicu.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="data-spm" />

    <!-- Langkah 1: Definisikan AliyunCaptchaConfig sebelum file JS Captcha dimuat. -->
    <script>
      window.AliyunCaptchaConfig = {
        // Nilai yang valid: cn (Tiongkok daratan), sgp (Singapura).
        region: "cn",
        // Dapatkan dari Overview > Cumulative Activation Time > Identity Prefix.
        prefix: "xxxxxx",
      };
    </script>

    <!-- Langkah 2: Memuat file JS Captcha secara dinamis. -->
    <script
      type="text/javascript"
      src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
    ></script>
  </head>

  <body>
    <!-- Container yang disediakan untuk widget CAPTCHA. Harus sesuai dengan parameter element di bawah. -->
    <div id="captcha-element"></div>

    <!-- Tombol pemicu. Di mode popup, klik ini membuka kotak dialog CAPTCHA. -->
    <button id="button" class="btn">Log on</button>

    <!-- Langkah 3: Inisialisasi Captcha setelah body halaman siap. -->
    <script type="text/javascript">
      var captcha;
      window.initAliyunCaptcha({
        // Dapatkan dari daftar skenario verifikasi setelah membuat skenario.
        SceneId: "xxxxxx",
        // popup: kotak dialog dipicu oleh klik tombol.
        // embed: widget selalu terlihat di halaman.
        mode: "popup",
        // Harus sesuai dengan elemen container yang disediakan di HTML.
        element: "#captcha-element",
        // Elemen yang memicu kotak dialog CAPTCHA atau verifikasi no-captcha.
        button: "#button",
        // Dipanggil saat verifikasi berhasil. captchaVerifyParam diperlukan untuk validasi sisi server.
        success: function (captchaVerifyParam) {
          // Kirim captchaVerifyParam ke backend Anda.
          // Backend Anda memanggil API validasi sisi server Captcha 2.0 untuk memvalidasinya.
          // Tangani logika bisnis Anda berdasarkan hasil validasi.
          // Jika diperlukan verifikasi ulang, panggil metode inisialisasi initAliyunCaptcha untuk menginisialisasi ulang Captcha.
        },
        // Dipanggil saat verifikasi gagal. Captcha secara otomatis mencoba ulang dalam periode validitas.
        fail: function (result) {
          // result berisi detail kegagalan.
          // Tidak perlu tindakan untuk kegagalan sementara — Captcha akan merefresh secara otomatis.
          console.error(result);
        },
        // Dipanggil setelah Captcha berhasil diinisialisasi. Menyimpan instans untuk penggunaan selanjutnya.
        getInstance: function (instance) {
          captcha = instance;
        },
        // Lebar dan tinggi (px) kotak pemicu untuk verifikasi slider dan point-and-click.
        // Lebar minimum: 320 px. Nilai di bawah 320 diabaikan dan digunakan 320 sebagai gantinya.
        // Tidak berlaku untuk verifikasi CAPTCHA puzzle atau restorasi gambar.
        slideStyle: {
          width: 360,
          height: 40,
        },
        // Untuk parameter lainnya, lihat referensi parameter di bawah.
      });
    </script>
  </body>
</html>

Referensi parameter

Parameter AliyunCaptchaConfig

Definisikan parameter ini sebelum file JS Captcha dimuat.

Parameter	Tipe	Wajib	Bawaan	Deskripsi
`region`	String	Ya	`cn`	Wilayah instans Captcha Anda. Nilai yang valid: `cn` (Tiongkok daratan), `sgp` (Singapura). Klien mengirim data perilaku dan perangkat ke lapisan kontrol yang sesuai. Titik akhir sisi server harus sesuai.
`prefix`	String	Ya	Tidak ada	Awalan identitas untuk instans Captcha Anda. Dapatkan nilai ini dari Overview > Cumulative Activation Time > Identity Prefix di Konsol setelah mengaktifkan Captcha 2.0.

Parameter initAliyunCaptcha

Panggil initAliyunCaptcha setelah halaman dimuat. Tabel berikut mencantumkan parameter yang paling umum digunakan.

Parameter yang umum digunakan

Parameter	Tipe	Wajib	Bawaan	Deskripsi
`SceneId`	String	Ya	Tidak ada	ID skenario. Dapatkan nilai ini setelah membuat skenario verifikasi.
`mode`	String	Ya	Tidak ada	Mode rendering. `popup`: kotak dialog muncul saat dipicu. `embed`: widget selalu terlihat. Verifikasi no-captcha memerlukan `popup`.
`element`	String	Ya	Tidak ada	Selektor CSS untuk elemen container yang disediakan tempat Captcha melakukan rendering. Harus sesuai dengan elemen DOM di HTML Anda.
`button`	String	Ya	Tidak ada	Selektor CSS untuk elemen yang memicu kotak dialog CAPTCHA atau verifikasi no-captcha.
`success`	Function	Ya	Tidak ada	Callback untuk verifikasi yang berhasil. Menerima `captchaVerifyParam`, yang digunakan backend Anda untuk memanggil API validasi sisi server.
`fail`	Function	Tidak	Tidak ada	Callback untuk verifikasi yang gagal. Menampilkan kode kesalahan kegagalan. Captcha mencoba ulang secara otomatis dalam periode validitas.
`getInstance`	Function	Ya	`getInstance`	Callback yang dipanggil setelah inisialisasi berhasil. Gunakan untuk menyimpan referensi ke instans Captcha. Sintaksnya tetap: `function getInstance(instance) { captcha = instance; }`
`slideStyle`	Object	Tidak	`{ width: 360, height: 40 }`	Lebar dan tinggi (px) kotak pemicu untuk verifikasi slider dan point-and-click. Lebar minimum: 320 px — nilai di bawah 320 dianggap sebagai 320. Tidak berlaku untuk verifikasi CAPTCHA puzzle atau restorasi gambar. Jangan mengganti CSS untuk CAPTCHA puzzle; ukuran gambar dan jawabannya telah ditetapkan dan tidak dapat diubah.

Parameter tambahan

Parameter	Tipe	Wajib	Bawaan	Deskripsi
`language`	String	Tidak	`cn`	Bahasa tampilan. Untuk nilai yang didukung, lihat Pengaturan copy kustom dan multi-bahasa.
`timeout`	Number	Tidak	`5000`	Timeout (ms) untuk satu permintaan inisialisasi.
`rem`	Number	Tidak	`1`	Menskalakan seluruh UI CAPTCHA. Masukkan angka positif: `0.5` memperkecil ukuran separuhnya, `2` melipatgandakannya. Terutama berguna untuk browser seluler.
`onError`	Function	Tidak	Tidak ada	Callback kesalahan untuk kegagalan API inisialisasi atau timeout pemuatan resource.
`onClose`	Function	Tidak	Tidak ada	Callback yang dipicu saat kotak dialog CAPTCHA ditutup.
`captchaLogoImg`	String	Tidak	Tidak ada	Mengganti logo perusahaan di sebelah kanan tombol pemicu dalam mode embedded (verifikasi point-and-click, CAPTCHA puzzle, dan restorasi gambar). Menerima URL gambar atau data base64-encoded.
`dualStack`	Boolean	Tidak	`false`	Mengaktifkan jaringan dual-stack. `false`: hanya IPv4. `true`: IPv4 dan IPv6.
`showErrorTip`	Boolean	Tidak	`true`	Menampilkan pesan kesalahan saat akses gagal karena kualitas jaringan yang buruk.
`delayBeforeSuccess`	Boolean	Tidak	`true`	Menunda callback `success` selama 1 detik setelah verifikasi berhasil.

Metode instans

Setelah inisialisasi, gunakan instans Captcha (disimpan melalui getInstance) untuk mengontrol visibilitas widget secara terprogram.

Catatan

Metode show dan hide tidak didukung untuk verifikasi pertama dalam mode no-captcha.

Metode	Deskripsi	Contoh	Kapan digunakan
`show`	Menampilkan elemen Captcha dan mask.	`captcha.show()`	Membuka otomatis kotak dialog CAPTCHA tanpa klik tombol — misalnya, saat formulir dikirimkan secara terprogram.
`hide`	Menyembunyikan atau menutup elemen Captcha dan mask.	`captcha.hide()`	Menutup otomatis kotak dialog CAPTCHA tanpa interaksi pengguna — misalnya, setelah timeout.

Data yang dikembalikan

Setelah pengguna menyelesaikan verifikasi perilaku, Captcha 2.0 mengembalikan kode CAPTCHA dan parameter pendukung ke klien. Lihat data yang dikembalikan di panel Network browser Anda. Untuk detail struktur respons, lihat Data yang dikembalikan oleh arsitektur klien V3.

lQLPJxFSi2GYDIHNBHTNCpawwjNH3sY_CI4IOehh6YNsAQ_2710_1140

Contoh parameter rem

Gunakan parameter rem untuk menskalakan UI CAPTCHA pada browser seluler tempat viewport lebih sempit daripada lebar slider bawaan.

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) {
  // Skala UI secara proporsional agar slider sesuai dengan viewport.
  const rem = Math.floor((pageWidth / customWidth) * 100) / 100;
  initCaptcha(rem);
}

Langkah selanjutnya

Unduh demo integrasi spesifik framework dan jalankan secara lokal:
Siapkan validasi sisi server: Akses sisi server
Tinjau kode kesalahan sisi klien: Error inisialisasi sisi klien