Moduł chatbota Drupal
Użyj oficjalnego modułu Drupal ChattyBox, jeśli chcesz instalacji zarządzanej przez Composer dla witryny Drupal 10 lub Drupal 11. Lokalnie audytowany moduł w wersji 0.1.0 dołącza loader hostowanego widżetu tylko do kwalifikujących się żądań: nie dołącza go na trasach administracyjnych ani w przypadku żądań, których format w Drupalu nie jest HTML. Używa zakodowanego na stałe endpointu API. Ten przewodnik opisuje konfigurację operacyjną. Strona modułu chatbota AI dla Drupal opisuje produkt i proces oceny.
Zanim rozpoczniesz instalację
Najpierw ukończ proces Pierwsze kroki: połącz publiczny adres URL Drupal, przejrzyj zindeksowane strony i zweryfikuj reprezentatywne odpowiedzi w Przetestuj chatbota. W Instalacja → Klucze i domeny sprawdź, czy masz odpowiedni publiczny klucz widżetu, lub utwórz go; w obu przypadkach sprawdź jego ustawienia originu. W Instalacja → Instalacja na stronie wybierz odpowiedni klucz i skopiuj wartość data-api-key z fragmentu instalacyjnego.
Instalacja przez Composer
Ta instalacja korzysta z publicznego repozytorium GitHub jako źródła VCS dla Composer. Dodaj poniższą deklarację repozytorium przed uruchomieniem composer require; przed instalacją sprawdź aktualną dostępność pakietu i tagi.
Dodaj publiczne repozytorium GitHub do głównego pliku composer.json używanego projektu Drupal:
{
"repositories": {
"chattybox-drupal": {
"type": "vcs",
"url": "https://github.com/OpenStaticFish/chattybox-drupal.git"
}
}
}
Jeśli projekt ma już sekcję repositories, połącz z nią wpis chattybox-drupal. Następnie zainstaluj oznaczoną wersję modułu:
composer require openstaticfish/chattybox-drupal:^0.1
Pakiet jest zadeklarowany jako drupal-module i wymaga Drupal ^10 || ^11; moduł deklaruje PHP 8.1 jako wersję minimalną, choć Twoja wersja Drupala może wymagać nowszego PHP. Standardowe ścieżki instalatora Drupal Composer zwykle umieszczają go w web/modules/contrib/, ale mapowania projektu mogą się różnić. ^0.1 to ograniczenie wersji, a nie dokładne przypięcie: Composer rozwiązuje i zapisuje wybraną wersję w pliku blokady. Jeśli wymagana jest powtarzalność instalacji, użyj dokładnej wersji.
Przed aktualizacją przejrzyj publiczny kod źródłowy modułu Drupal i zmiany w oznaczonych wersjach; potwierdź dostępny mechanizm aktualizacji dla swojej instalacji.
Aby zamiast tego przetestować bieżącą gałąź deweloperską:
composer require openstaticfish/chattybox-drupal:dev-main
Włączanie i konfiguracja
- Włącz ChattyBox w Extend lub uruchom
drush en chattybox. - Otwórz Configuration > Web services > ChattyBox.
- Wklej wyłącznie publiczny klucz API widżetu z fragmentu instalacyjnego witryny.
- Pozostaw adres URL hostowanego skryptu widżetu, chyba że ChattyBox dostarczył adres URL loadera wersji podglądowej lub hostowanej samodzielnie.
- Pozostaw override języka puste, aby stosować politykę lokalizacji projektu, albo wpisz obsługiwany kod małymi literami, np.
en,frlubde. Obsługiwany override ma pierwszeństwo tylko wtedy, gdy projekt zezwala na nadpisywanie przez skrypt. W aktualnym kodzie źródłowym hostowanego widżetu v16 tryb automatyczny (Wykryj automatycznie) próbuje kolejno języka strony, języków przeglądarki, a następnie skonfigurowanego języka domyślnego; pomija nieobsługiwane wartości i ostatecznie używa angielskiego. Tryb stały (Stały) używa obsługiwanego domyślnego języka projektu lub angielskiego. Zachowanie to jest wersjonowane niezależnie od modułu: przed poleganiem na nim sprawdź loader wdrożony w swojej witrynie i nie zakładaj, że wszystkie wersje działają tak samo. - Włącz chatbota i zapisz konfigurację.
Na trasach administracyjnych ani przy żądaniach, których format w Drupalu nie jest HTML, audytowany moduł nie dołącza loadera widżetu. Nie sprawdza końcowego nagłówka Content-Type odpowiedzi ani nie ustala, czy treść frontendowa jest prywatna. W przypadku pozostałych kwalifikujących się żądań dołącza publiczny klucz, zakodowany na stałe punkt końcowy, opcjonalny język i loader widżetu za pomocą zadeklarowanej biblioteki Drupal oraz drupalSettings.
Nowe instalacje są domyślnie wyłączone, a klucz i override języka są puste. Formularz ustawień znajduje się pod /admin/config/services/chattybox i wymaga uprawnienia administer chattybox configuration. Moduł ładuje widżet; nie skanuje ani nie synchronizuje treści Drupala.
W audytowanej wersji modułu endpoint API jest zakodowany na stałe — nie jest wyznaczany na podstawie klucza ani aktualizowany automatycznie. Zmiana adresu URL loadera nie zmienia tego endpointu. Porównaj go z fragmentem instalacyjnym witryny; jeśli fragment wskazuje inne wdrożenie API, użyj jego ręcznej integracji widżetu bez modułu. Zdalne adresy URL skryptów muszą używać HTTPS (HTTP jest dozwolone tylko dla lokalnych hostów deweloperskich).
Klucze utworzone bez ograniczeń działają z różnych originów przeglądarki; klucz przygotowany dla witryny może już być ograniczony do originu tej witryny. Opcjonalne ograniczenia w Instalacja → Klucze i domeny wymagają podania każdego używanego schematu, hosta i portu. Dla ograniczonego klucza brak dozwolonego originu lub niedozwolony origin powoduje odpowiedź 401 Invalid API key. Efektywny origin pochodzi z Origin, a gdy tego nagłówka brakuje — z originu w Referer. Ograniczenia originu to dodatkowe zabezpieczenie, a nie uwierzytelnianie odwiedzających.
Wykluczanie dodatkowych tras
Moduł automatycznie pomija trasy administracyjne. Niestandardowy moduł może wyłączyć widżet na dodatkowych trasach publicznych za pomocą hook_chattybox_load_widget_alter():
Kontrola tras administracyjnych nie chroni prywatności całej treści frontendu. W razie potrzeby dodaj wykluczenia dla tras płatności, kont i członkostwa; nazwa trasy w przykładzie ma charakter ilustracyjny. Moduł nie dodaje kontekstów ani tagów cache dla decyzji podejmowanej przez hook. Zaimplementuj i zweryfikuj właściwe dla witryny różnicowanie cache oraz unieważnianie dla każdego warunku — zarówno gdy biblioteka widżetu jest dołączana, jak i gdy nie jest — we wszystkich cache Drupal i pośredniczących. Samo wykluczenie nie stanowi granicy kontroli dostępu.
/**
* 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;
}
}
Ręczna instalacja awaryjna
Composer to zalecana ścieżka instalacji. Jeśli wdrożenie Drupal nie może korzystać z Composer, skopiuj moduł do web/modules/custom/chattybox lub innego katalogu modułów niestandardowych, włącz go i skonfiguruj w Configuration > Web services > ChattyBox.
Nie wklejaj do modułu poświadczeń do zarządzania ChattyBox. Publiczny klucz API widżetu jest przeznaczony do kodu frontendu.
Używaj tylko jednego loadera: nie włączaj modułu jednocześnie z fragmentem w motywie, tagiem GTM ani montowaniem SDK. Audytowany moduł pomija wstawienie, jeśli znajdzie dowolny oznaczony skrypt script[data-chattybox-widget="true"]; nie sprawdza ani nie zmienia konfiguracji tego skryptu, a nieoznaczonych skryptów nie wykrywa.
Automatyczny loader modułu nie sprawdza zgody przed inicjalizacją. Jeśli zgoda jest wymagana przed wysłaniem żądań, zamiast tego loadera automatycznego użyj integracji uwzględniającej zgodę. Przy zmianie trasy SPA lub wycofaniu zgody zapobiegaj ładowaniu na wykluczonych trasach i aktywnie przeprowadź pełny demontaż już zainicjowanego widżetu za pomocą integracji obsługiwanej przez wdrożony loader; samo ukrycie widżetu lub usunięcie znacznika skryptu nie wystarczy. Inicjalizuj ponownie tylko wtedy, gdy jest to dozwolone. Demontaż nie może cofnąć żądań już przetworzonych przez serwer.
Weryfikacja
Po skonfigurowaniu modułu:
- Otwórz publiczną stronę Drupal w oknie incognito.
- Sprawdź, czy launcher widżetu pojawia się tylko raz.
- Zadaj prawdziwe pytanie odwiedzającego.
- Sprawdź, czy obsługiwana odpowiedź cytuje zindeksowane publiczne strony Drupal, a przy pytaniu spoza zakresu pojawia się odpowiedź awaryjna, która może nie zawierać źródeł.
- Sprawdź konsolę przeglądarki pod kątem brakujących
data-api-key,data-api-urllub błędów klucza. - Przetestuj trasy wykluczone i dozwolone przy rozgrzanych i zimnych cache Drupal, strony i CDN. Po zmianach ustawień lub hooka przebuduj odpowiednie cache. Wykluczenie po stronie serwera nie wyłącza widżetu załadowanego wcześniej podczas nawigacji po stronie klienta.
Przejdź przez listę kontrolną uruchomienia przed ogłoszeniem chatbota.