Modul chatbotu Drupal

Oficiální modul Drupal ChattyBox použijte, pokud chcete instalaci spravovanou Composerem pro web Drupal 10 nebo Drupal 11. Lokálně auditovaná verze modulu 0.1.0 připojuje loader hostovaného widgetu pouze ke způsobilým požadavkům: na administrativních routách ani u požadavků, jejichž formát v Drupalu není HTML, jej nepřipojuje. Používá napevno zadaný koncový bod API. Tato příručka popisuje provozní nastavení. Stránka modulu AI chatbotu pro Drupal shrnuje produkt a proces vyhodnocení.

Než začnete s instalací

Nejprve dokončete postup Začínáme: připojte veřejnou URL Drupalu, projděte indexované stránky a ověřte reprezentativní odpovědi v Otestovat chatbota. V části Instalace → Klíče a domény zkontrolujte, zda máte vhodný veřejný klíč widgetu, nebo jej vytvořte; v obou případech ověřte jeho nastavení originu. V části Instalace → Instalace na web vyberte vhodný klíč a z instalačního úryvku zkopírujte jeho hodnotu data-api-key.

Instalace pomocí Composeru

Tato instalace používá veřejný repozitář GitHub jako zdroj VCS pro Composer. Před spuštěním composer require přidejte níže uvedenou deklaraci repozitáře; před instalací ověřte aktuální dostupnost balíčku a tagy.

Přidejte veřejný repozitář GitHub do kořenového composer.json používaného projektu Drupal:

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

Pokud projekt už obsahuje sekci repositories, sloučte s ní položku chattybox-drupal. Poté nainstalujte označený modul:

composer require openstaticfish/chattybox-drupal:^0.1

Balíček je deklarován jako drupal-module a vyžaduje Drupal ^10 || ^11; modul deklaruje PHP 8.1 jako minimální verzi, vaše verze Drupalu však může vyžadovat novější PHP. Standardní instalační cesty Drupal Composeru jej obvykle umístí do web/modules/contrib/, nastavení konkrétního projektu se ale může lišit. ^0.1 je verze omezená rozsahem, nikoli přesně připnutá: Composer vyřeší a uzamkne konkrétní verzi. Pokud potřebujete reprodukovatelné instalace, použijte přesnou verzi.

Před aktualizací si prohlédněte veřejný zdroj modulu Drupal a změny v označených verzích; ověřte dostupný způsob aktualizace pro svou instalaci.

Chcete-li místo toho otestovat aktuální vývojovou větev:

composer require openstaticfish/chattybox-drupal:dev-main

Povolení a konfigurace

1. Povolte ChattyBox v části Extend nebo spusťte drush en chattybox.
2. Otevřete Configuration > Web services > ChattyBox.
3. Vložte pouze veřejný API klíč widgetu z instalačního úryvku pro web.
4. URL hostovaného skriptu widgetu ponechte beze změny, pokud vám ChattyBox neposkytl URL loaderu pro náhled nebo vlastní hostování.
5. Přepsání jazyka ponechte prázdné, chcete-li použít jazykovou politiku projektu, nebo zadejte podporovaný kód malými písmeny, například en, fr či de. Podporované přepsání má přednost pouze tehdy, pokud projekt povoluje přepsání skriptem. V aktuálním zdrojovém kódu hostovaného widgetu v16 automatický režim (Automatická detekce) postupně zkouší jazyk stránky, jazyky prohlížeče a nastavený výchozí jazyk; nepodporované hodnoty přeskočí a nakonec použije angličtinu. Pevný režim (Pevné) použije podporovaný výchozí jazyk projektu, nebo angličtinu. Toto chování je verzováno nezávisle na modulu: než se na něj spolehnete, ověřte loader nasazený na webu a nepředpokládejte, že se všechny verze chovají stejně.
6. Povolte chatbot a uložte konfiguraci.

Na administrativních routách ani u požadavků, jejichž formát požadavku Drupalu není HTML, auditovaný modul nepřipojuje loader widgetu. Nekontroluje konečnou hlavičku Content-Type odpovědi ani neurčuje, zda je obsah na frontendu soukromý. U ostatních způsobilých požadavků připojuje pomocí deklarované knihovny Drupalu a drupalSettings veřejný klíč, napevno zadaný koncový bod, volitelný jazyk a loader widgetu.

Nové instalace jsou vypnuté a klíč i přepsání jazyka jsou prázdné. Formulář nastavení je na adrese /admin/config/services/chattybox a vyžaduje oprávnění administer chattybox configuration. Modul načítá widget; neprochází ani nesynchronizuje obsah Drupalu.

V auditované verzi modulu je koncový bod API napevno zadaný — neodvozuje se od klíče ani se automaticky neaktualizuje. Změna URL loaderu tento koncový bod nezmění. Porovnejte jej s instalačním úryvkem pro web; pokud úryvek používá jiné nasazení API, použijte jeho ruční integraci widgetu bez modulu. Vzdálené URL skriptů musí používat HTTPS (HTTP je povoleno pouze pro místní vývojové hostitele).

Klíče vytvořené bez omezení fungují napříč originy prohlížeče; klíč připravený pro web už může být omezen na origin tohoto webu. Volitelná omezení v části Instalace → Klíče a domény vyžadují každé požadované schéma URL, název hostitele a port. U omezeného klíče vrátí chybějící nebo nepovolený efektivní origin odpověď 401 Invalid API key. Efektivní origin se získá z Origin, a pokud chybí, z originu v Referer. Omezení originu představuje dodatečné zabezpečení, nikoli autentizaci návštěvníků.

Vyloučení dalších rout

Modul administrativní routy automaticky vynechává. Vlastní modul může widget vypnout na dalších veřejných routách pomocí hook_chattybox_load_widget_alter():

Kontrola administrativních rout nechrání soukromí veškerého obsahu na frontendu. Podle potřeby přidejte výjimky pro checkout, účet a členské routy; název routy v příkladu je pouze ilustrativní. Modul pro rozhodnutí hooku nepřidává cache kontexty ani cache tagy. Pro každou podmínku implementujte a ověřte variaci a invalidaci cache specifickou pro web, a to v případech, kdy se knihovna widgetu připojí i kdy se nepřipojí, napříč cache Drupalu i mezičlánků. Samotné vyloučení není hranicí řízení přístupu.

/**
 * 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;
  }
}

Ruční záložní varianta

Composer je doporučený způsob instalace. Pokud vaše nasazení Drupalu nemůže Composer použít, zkopírujte modul do web/modules/custom/chattybox nebo jiného adresáře vlastních modulů, povolte jej a nakonfigurujte v Configuration > Web services > ChattyBox.

Do modulu nevkládejte přihlašovací údaje pro správu ChattyBoxu. Veřejný API klíč widgetu je určen pro frontendový kód.

Používejte pouze jeden loader: nepovolujte modul současně s úryvkem v šabloně, značkou GTM ani montáží SDK. Auditovaný modul přeskočí vložení, pokud najde jakýkoli označený skript script[data-chattybox-widget="true"]; jeho konfiguraci nekontroluje ani nemění a neoznačené skripty nerozpozná.

Automatický loader modulu před inicializací nekontroluje souhlas. Pokud je souhlas vyžadován před odesíláním požadavků, použijte místo tohoto automatického loaderu integraci zohledňující souhlas. Při změně trasy SPA nebo odvolání souhlasu zabraňte načtení na vyloučených trasách a aktivně ukončete běh a uvolněte již inicializovaný widget pomocí integrace podporované nasazeným loaderem; nestačí widget skrýt nebo odstranit pouze značku skriptu. Znovu jej inicializujte, jen když je to povoleno. Ukončení nemůže vzít zpět požadavky, které už server zpracoval.

Ověření

Po konfiguraci modulu:

• Otevřete veřejnou stránku Drupalu v anonymním okně.
• Ověřte, že se launcher widgetu zobrazí právě jednou.
• Položte skutečnou otázku návštěvníka.
• Ověřte, že podporovaná odpověď cituje indexované veřejné stránky Drupalu a že se u nepodporované otázky zobrazí záložní odpověď, která nemusí obsahovat zdroje.
• Zkontrolujte konzoli prohlížeče, zda nechybí data-api-key, data-api-url nebo zda neobsahuje chyby klíče.
• Otestujte vyloučené i povolené routy se zahřátou i studenou cache Drupalu, stránky a CDN. Po změně nastavení nebo hooku znovu sestavte příslušné cache. Vyloučení na straně serveru neukončí widget, který už byl načten během navigace na straně klienta.

Před oznámením chatbota pokračujte podle kontrolního seznamu spuštění.