Lewati ke konten utama

Modul Chatbot Drupal

Gunakan modul Drupal resmi ChattyBox jika Anda menginginkan instalasi yang dikelola Composer untuk situs Drupal 10 atau Drupal 11. Modul 0.1.0 yang diperiksa secara lokal menyertakan loader widget ter-host pada permintaan nonadministratif yang memenuhi syarat dan memiliki format permintaan Drupal HTML; modul ini menggunakan endpoint API yang di-hard-code. Panduan ini mencakup penyiapan operasional. Halaman modul chatbot AI Drupal membahas produk dan alur evaluasinya.

Sebelum Menginstal​

Selesaikan alur Memulai terlebih dahulu: hubungkan URL Drupal publik Anda, tinjau halaman yang diindeks, dan verifikasi jawaban yang mewakili di Uji chatbot. Di Pasang → Kunci & domain, tinjau kunci widget publik yang sudah ada atau buat kunci baru; dalam kedua kasus, periksa pengaturan origin kunci tersebut. Di Pasang → Instalasi situs web, pilih kunci yang sesuai dan salin nilai data-api-key dari cuplikan instalasi.

Instalasi Composer​

Instalasi ini menggunakan repositori GitHub publik sebagai sumber VCS Composer. Tambahkan deklarasi repositori di bawah sebelum menjalankan composer require; periksa ketersediaan paket dan tag terbaru sebelum menginstal.

Tambahkan repositori GitHub publik ke composer.json root proyek Drupal yang menggunakannya:

{
  "repositories": {
    "chattybox-drupal": {
      "type": "vcs",
      "url": "https://github.com/OpenStaticFish/chattybox-drupal.git"
    }
  }
}

Jika proyek sudah memiliki bagian repositories, gabungkan entri chattybox-drupal ke dalamnya. Lalu instal modul dengan versi bertag:

composer require openstaticfish/chattybox-drupal:^0.1

Paket dideklarasikan sebagai drupal-module dan memerlukan Drupal ^10 || ^11. Modul menetapkan PHP 8.1 sebagai versi minimum, tetapi versi Drupal Anda mungkin memerlukan PHP yang lebih baru. Jalur penginstal Composer Drupal standar biasanya menempatkannya di web/modules/contrib/, tetapi pemetaan direktori proyek dapat berbeda. ^0.1 adalah batas versi, bukan pin versi yang pasti: Composer akan menyelesaikan dan mengunci versinya. Gunakan versi yang pasti jika instalasi harus dapat direproduksi.

Tinjau sumber modul Drupal publik dan perubahan bertag sebelum melakukan upgrade; pastikan mekanisme pembaruan yang berlaku untuk instalasi Anda.

Untuk menguji branch pengembangan saat ini:

composer require openstaticfish/chattybox-drupal:dev-main

Mengaktifkan dan Mengonfigurasi​

  1. Aktifkan ChattyBox dari Extend, atau jalankan drush en chattybox.
  2. Buka Configuration > Web services > ChattyBox.
  3. Tempel hanya kunci API widget publik dari cuplikan instalasi situs web.
  4. Biarkan URL skrip widget ter-host kecuali ChattyBox telah memberikan URL loader pratinjau atau self-hosted.
  5. Biarkan override bahasa kosong agar mengikuti kebijakan locale proyek, atau masukkan kode huruf kecil yang didukung seperti en, fr, atau de. Override yang didukung hanya mendapat prioritas jika proyek mengizinkan override skrip. Dalam widget ter-host v16 yang dirujuk oleh kode sumber saat ini, mode otomatis mencoba bahasa halaman, bahasa browser, lalu bahasa default yang dikonfigurasi; nilai yang tidak didukung dilewati, dan bahasa Inggris menjadi fallback jika tidak ada kandidat yang didukung. Mode tetap menggunakan default proyek jika didukung, atau bahasa Inggris. Verifikasi loader yang di-deploy sebelum mengandalkan perilaku yang versinya dikelola secara terpisah ini.
  6. Aktifkan chatbot dan simpan konfigurasi.

Pada rute administratif dan permintaan dengan format permintaan Drupal selain HTML, modul yang diperiksa tidak melampirkan loader widget. Modul tidak memeriksa header Content-Type respons akhir atau menentukan apakah konten frontend bersifat privat. Pada permintaan yang memenuhi syarat, modul menyertakan kunci publik, endpoint API yang di-hard-code, locale opsional, dan loader widget melalui library Drupal yang dideklarasikan serta drupalSettings.

Instalasi baru dimulai dalam keadaan nonaktif, dengan kunci dan override locale kosong. Formulir pengaturan ada di /admin/config/services/chattybox dan memerlukan izin administer chattybox configuration. Modul memuat widget; modul tidak merayapi atau menyinkronkan konten Drupal.

Endpoint API di-hard-code dalam versi modul yang diperiksa; endpoint tidak ditentukan dari kunci dan tidak diperbarui secara otomatis. Mengubah URL loader tidak mengubah endpoint. Bandingkan endpoint tersebut dengan cuplikan instalasi situs web. Jika cuplikan itu menggunakan deployment API lain, gunakan integrasi widget manualnya tanpa modul. URL skrip jarak jauh harus menggunakan HTTPS (HTTP hanya diizinkan untuk host pengembangan lokal).

Kunci yang dibuat tanpa pembatasan berfungsi dari semua origin browser; kunci yang disiapkan untuk suatu situs mungkin sudah dibatasi ke origin situs tersebut. Pembatasan opsional di Pasang → Kunci & domain memerlukan skema, hostname, dan port yang tepat untuk setiap origin yang dituju. Kunci yang dibatasi menghasilkan 401 Invalid API key jika origin efektif tidak ada atau tidak diizinkan. Origin diambil dari Origin atau, jika tidak ada, dari origin pada Referer. Pembatasan origin adalah penguatan keamanan tambahan, bukan autentikasi pengunjung.

Mengecualikan Rute Tambahan​

Modul secara otomatis melewati rute administratif. Modul khusus dapat menonaktifkan widget pada rute publik tambahan dengan hook_chattybox_load_widget_alter():

Pemeriksaan rute administratif bukan pemeriksaan privasi untuk semua konten frontend: tambahkan pengecualian untuk rute checkout, akun, dan keanggotaan bila sesuai. Nama rute di bawah hanya contoh. Modul tidak menambahkan cache context atau cache tag untuk keputusan hook. Terapkan dan uji variasi serta invalidasi cache khusus situs untuk setiap kondisi, baik saat widget disertakan maupun tidak, di seluruh cache Drupal dan perantara. Pengecualian bukan batas kontrol akses.

/**
 * Implements hook_chattybox_load_widget_alter().
 */
function mymodule_chattybox_load_widget_alter(&$should_load, $config, $route_match) {
  if ('commerce_checkout.form' === $route_match->getRouteName()) {
    $should_load = FALSE;
  }
}

Fallback Manual​

Composer adalah jalur instalasi yang direkomendasikan. Jika deployment Drupal Anda tidak dapat menggunakan Composer, salin modul ke web/modules/custom/chattybox atau direktori modul khusus lainnya, aktifkan, lalu konfigurasikan dari Configuration > Web services > ChattyBox.

Jangan menempelkan kredensial manajemen ChattyBox ke dalam modul. Kunci API widget publik ditujukan untuk markup frontend.

Gunakan hanya satu loader: jangan aktifkan modul bersamaan dengan cuplikan tema, tag GTM, atau pemasangan SDK. Modul yang diperiksa melewati penyisipan loader jika menemukan script[data-chattybox-widget="true"] bertanda apa pun; modul tidak memvalidasi atau mengonfigurasi ulang skrip tersebut, dan tidak mendeteksi skrip yang tidak bertanda.

Loader otomatis modul tidak memeriksa persetujuan sebelum menginisialisasi widget. Jika persetujuan diwajibkan sebelum permintaan dikirim, gunakan integrasi yang memperhatikan persetujuan alih-alih loader otomatis ini. Saat rute SPA berubah atau persetujuan dicabut, cegah pemuatan pada rute yang dikecualikan dan lakukan teardown widget yang sudah diinisialisasi melalui integrasi yang didukung loader ter-deploy. Menyembunyikan widget atau hanya menghapus tag skrip tidak cukup. Inisialisasi ulang hanya jika diizinkan. Teardown tidak dapat membatalkan permintaan yang sudah diproses server.

Verifikasi​

Setelah mengonfigurasi modul:

  • Buka halaman Drupal publik di jendela penyamaran.
  • Pastikan peluncur widget muncul satu kali.
  • Ajukan pertanyaan pengunjung yang nyata.
  • Pastikan jawaban yang didukung menyitasi halaman Drupal publik yang diindeks dan pertanyaan yang tidak didukung menampilkan fallback, yang dapat tidak memiliki sumber.
  • Periksa konsol browser untuk data-api-key, data-api-url yang hilang, atau kesalahan kunci.
  • Uji rute yang dikecualikan dan disertakan saat cache Drupal/halaman/CDN dingin maupun hangat. Bangun ulang cache yang relevan setelah perubahan pengaturan atau hook. Pengecualian rute sisi server tidak membongkar widget yang sudah dimuat saat navigasi sisi klien.

Lanjutkan ke daftar periksa peluncuran sebelum mengumumkan chatbot.