Ga naar de hoofdinhoud

Drupal-chatbotmodule

Gebruik de officiële ChattyBox Drupal-module voor een installatie met Composer op een Drupal 10- of Drupal 11-site. De lokaal gecontroleerde module 0.1.0 voegt de gehoste widgetloader toe aan geschikte niet-administratieve verzoeken waarvan het Drupal-requestformaat HTML is, en gebruikt een hardgecodeerd API-eindpunt. Deze gids behandelt de operationele installatie. De pagina over de Drupal-AI-chatbotmodule geeft een overzicht van het product en het evaluatieproces.

Voordat je installeert​

Doorloop eerst Aan de slag: koppel je openbare Drupal-URL, bekijk geïndexeerde pagina's en controleer representatieve antwoorden met Chatbot testen. Controleer bij Installeren → Sleutels en domeinen de origin-instellingen van een publieke widgetkey, of je er nu een aanmaakt of een bestaande gebruikt. Selecteer bij Installeren → Installatie op website een geschikte sleutel en kopieer de waarde van data-api-key uit het installatiesnippet.

Installatie met Composer​

Bij deze installatie wordt de openbare GitHub-repository als Composer-VCS-bron gebruikt. Voeg de onderstaande repositorydeclaratie toe voordat je composer require uitvoert; controleer vóór installatie of het pakket beschikbaar is en welke tags er actueel zijn.

Voeg de openbare GitHub-repository toe aan de composer.json in de hoofdmap van het Drupal-project dat de module gebruikt:

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

Als het project al een sectie repositories heeft, voeg je de entry chattybox-drupal daaraan toe. Installeer daarna de getagde module:

composer require openstaticfish/chattybox-drupal:^0.1

Het pakket is gedeclareerd als drupal-module en vereist Drupal ^10 || ^11; de module declareert PHP 8.1 als minimumversie, maar jouw Drupal-versie kan een nieuwere PHP-versie vereisen. Standaardpaden van de Drupal Composer-installer plaatsen de module vaak onder web/modules/contrib/, maar projectconfiguraties kunnen hiervan afwijken. ^0.1 is een versieconstraint, geen exact vastgelegde versie: Composer lost een versie op en legt die vast in het lockbestand. Gebruik voor reproduceerbaarheid een exacte versie.

Bekijk vóór een upgrade de openbare bron van de Drupal-module en de wijzigingen per tag; controleer welk updateproces voor jouw installatie beschikbaar is.

Om in plaats daarvan de huidige ontwikkelbranch te testen:

composer require openstaticfish/chattybox-drupal:dev-main

Inschakelen en configureren​

  1. Schakel ChattyBox in via Extend of voer drush en chattybox uit.
  2. Open Configuratie > Webservices > ChattyBox.
  3. Plak alleen de openbare widget-API-sleutel uit het installatiesnippet van de website.
  4. Laat de URL van het gehoste widgetscript staan, tenzij ChattyBox een preview- of zelfgehoste loader-URL heeft gegeven.
  5. Laat de taaloverride leeg om het taalbeleid van het project te volgen, of gebruik een ondersteunde code in kleine letters, zoals en, fr of de. Een ondersteunde override krijgt alleen voorrang als het project script-overschrijvingen toestaat. In de gehoste widget v16 zoals beschreven door de huidige bron probeert de modus Automatisch detecteren eerst de paginataal, daarna de browsertalen en vervolgens de ingestelde standaardtaal; niet-ondersteunde waarden worden overgeslagen en als geen enkele taal wordt ondersteund, wordt Engels gebruikt. De modus Vast gebruikt de ondersteunde standaardtaal van het project, of anders Engels. Controleer de daadwerkelijk uitgerolde loader voordat je op dit gedrag vertrouwt; de loader heeft een afzonderlijke versie.
  6. Schakel de chatbot in en sla de configuratie op.

De hook hook_page_attachments() van de gecontroleerde module voegt de widgetloader niet toe op administratieve routes of bij verzoeken waarvan het Drupal-requestformaat niet HTML is; de hook controleert niet het Content-Type van het uiteindelijke antwoord en bepaalt niet of frontendinhoud privé is. Via Drupals gedeclareerde library en drupalSettings voegt de module de publieke sleutel, het vaste eindpunt, de optionele locale en de widgetloader toe.

Nieuwe installaties zijn uitgeschakeld en hebben een lege sleutel en taaloverride. De instellingen staan op /admin/config/services/chattybox; toegang vereist de permissie administer chattybox configuration. De module laadt de widget, maar crawlt of synchroniseert geen Drupal-inhoud.

In de gecontroleerde versie staat het API-eindpunt vast in de modulecode; het wordt niet afgeleid van de sleutel en niet automatisch bijgewerkt. Een andere loader-URL verandert dat eindpunt niet. Vergelijk het met het installatiesnippet van je website. Gebruikt dat snippet een andere API-deployment, gebruik dan de bijbehorende handmatige widgetintegratie zonder de module. Externe script-URL's moeten HTTPS gebruiken; HTTP is alleen toegestaan voor lokale ontwikkelhosts (localhost, 127.0.0.1 en ::1).

Sleutels zonder beperkingen werken vanaf alle browserorigins; een voor een website voorbereide sleutel kan al tot de origin van die site beperkt zijn. Voor optionele beperkingen bij Installeren → Sleutels en domeinen moet je elke beoogde combinatie van schema, hostnaam en poort opgeven. Bij een beperkte sleutel geeft de API 401 Invalid API key terug als de effectieve origin ontbreekt of niet is toegestaan. Die origin komt uit Origin of, als die header ontbreekt, uit de origin van Referer. Originbeperkingen zijn een extra beveiligingslaag, geen bezoekersauthenticatie.

Extra routes uitsluiten​

De module slaat administratieve routes automatisch over. Een aangepaste module kan de widget op extra openbare routes uitschakelen met hook_chattybox_load_widget_alter():

De controle op administratieve routes beschermt niet alle frontendinhoud. Sluit checkout-, account- en ledenroutes zo nodig expliciet uit; de routenaam hieronder is alleen een voorbeeld. De module voegt geen cachecontexts of -tags toe voor de beslissing van de hook. Implementeer en test sitespecifieke cachevariatie en -invalidatie voor elke voorwaarde, zowel wanneer de widget wel als niet wordt toegevoegd, voor Drupal- en tussenliggende caches. Een uitsluiting is geen grens voor toegangscontrole.

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

Handmatige fallback​

Composer is de aanbevolen installatieroute. Als je Drupal-deployment Composer niet kan gebruiken, kopieer je de module naar web/modules/custom/chattybox of een andere map voor aangepaste modules, schakel je de module in en configureer je deze via Configuratie > Webservices > ChattyBox.

Plak geen beheerdersgegevens in de module. De openbare widget-API-sleutel is bedoeld voor frontend-markup.

Gebruik één loader: schakel de module niet tegelijk in met een snippet in het thema, een GTM-tag of een SDK-mount. De gecontroleerde moduleversie voegt geen script toe als er al een script met de markering script[data-chattybox-widget="true"] staat; de module controleert of herconfigureert dat script niet en detecteert scripts zonder die markering niet.

De automatische loader van de module controleert het toestemmingssignaal niet voordat deze wordt geïnitialiseerd. Als toestemming vereist is voordat verzoeken mogen worden verstuurd, gebruik dan een toestemmingsbewuste integratie in plaats van deze automatische loader. Voorkom bij SPA-routewisselingen of het intrekken van toestemming dat de widget op uitgesloten routes wordt geladen en breek een al geïnitialiseerde widget actief af via een integratie die door de daadwerkelijk uitgerolde loader wordt ondersteund. Alleen verbergen of de script-tag verwijderen is onvoldoende. Initialiseer de widget alleen opnieuw wanneer dat is toegestaan. Afbreken kan verzoeken die de server al heeft verwerkt niet ongedaan maken.

Verificatie​

Nadat je de module hebt geconfigureerd:

  • Open een openbare Drupal-pagina in een incognitovenster.
  • Controleer of de widgetlauncher één keer verschijnt.
  • Stel een echte bezoekersvraag.
  • Controleer of een ondersteund antwoord geïndexeerde openbare Drupal-pagina's citeert en of een niet-ondersteunde vraag de fallback toont, die geen bronnen hoeft te bevatten.
  • Controleer de browserconsole op ontbrekende data-api-key, data-api-url of sleutelfouten.
  • Test zowel uitgesloten als ingesloten routes met warme en koude Drupal-, pagina- en CDN-caches. Bouw relevante caches opnieuw op na wijzigingen aan instellingen of de hook. Een server-side route-uitsluiting verwijdert geen widget die al tijdens client-side navigatie is geladen.

Doorloop de launchchecklist voordat je de chatbot aankondigt.