Passer au contenu principal

Module de chatbot Drupal

Utilisez le module Drupal officiel de ChattyBox pour une installation gérée par Composer sur un site Drupal 10 ou 11. Le module ChattyBox 0.1.0 audité localement ajoute le loader du widget hébergé aux requêtes admissibles, hors administration, dont le format de requête Drupal est HTML. Il utilise un point de terminaison API codé en dur. Ce guide couvre la configuration opérationnelle. La page du module de chatbot IA Drupal présente le produit et le processus d’évaluation.

Avant l’installation​

Suivez d’abord le parcours Prise en main : connectez votre URL Drupal publique, examinez les pages indexées et vérifiez des réponses représentatives dans Tester le chatbot. Dans Installer → Clés et domaines, examinez une clé publique du widget existante ou créez-en une ; dans les deux cas, vérifiez ses paramètres d’origine. Dans Installer → Installation sur le site web, choisissez une clé appropriée et copiez sa valeur data-api-key depuis l’extrait d’installation.

Installation avec Composer​

Cette installation utilise le dépôt GitHub public comme source VCS de Composer. Ajoutez la déclaration de dépôt ci-dessous avant d’exécuter composer require et vérifiez la disponibilité actuelle du package ainsi que ses tags avant l’installation.

Ajoutez le dépôt GitHub public à la racine composer.json du projet Drupal qui le consomme :

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

Si le projet possède déjà une section repositories, fusionnez-y l’entrée chattybox-drupal. Installez ensuite le module balisé :

composer require openstaticfish/chattybox-drupal:^0.1

Le package est déclaré comme drupal-module et nécessite Drupal ^10 || ^11 ; le module déclare PHP 8.1 comme version minimale, mais votre version de Drupal peut en exiger une plus récente. Les chemins Composer standard de Drupal le placent souvent sous web/modules/contrib/, mais les mappings du projet peuvent différer. ^0.1 est une contrainte de version, pas un verrouillage exact : Composer résout une version et l’enregistre dans le fichier de verrouillage. Utilisez une version exacte si la reproductibilité est nécessaire.

Consultez le code source public du module Drupal et les modifications balisées avant toute mise à niveau ; vérifiez le mécanisme de mise à jour disponible pour votre installation.

Pour tester à la place la branche de développement actuelle :

composer require openstaticfish/chattybox-drupal:dev-main

Activer et configurer​

  1. Activez ChattyBox depuis Extend, ou exécutez drush en chattybox.
  2. Ouvrez Configuration > Web services > ChattyBox.
  3. Collez uniquement la clé API publique du widget depuis l’extrait d’installation du site web.
  4. Conservez l’URL du script du widget hébergé, sauf si ChattyBox vous a fourni une URL de loader de prévisualisation ou auto-hébergée.
  5. Laissez le remplacement de langue vide pour suivre la politique du projet, ou saisissez un code pris en charge en minuscules, par exemple en, fr ou de. Un remplacement pris en charge n’a priorité que si le projet autorise les remplacements par script. D’après le code source actuellement audité du widget hébergé v16, le mode automatique essaie successivement la langue de la page, les langues du navigateur, puis la langue par défaut configurée ; les valeurs non prises en charge sont ignorées et le widget finit par revenir à l’anglais. En mode fixe, il utilise la langue par défaut du projet si elle est prise en charge, sinon l’anglais. Vérifiez le loader déployé avant de vous fier à ce comportement, qui est versionné séparément.
  6. Activez le chatbot et enregistrez la configuration.

Le module audité n’attache pas le loader du widget aux routes d’administration ni aux requêtes dont le format de requête Drupal n’est pas HTML ; il n’examine pas le type de contenu de la réponse finale et ne détermine pas si le contenu du frontend est privé. Pour les requêtes admissibles, il attache la bibliothèque Drupal déclarée pour le loader et fournit dans drupalSettings la clé publique, le point de terminaison codé en dur et la langue facultative.

Les nouvelles installations sont désactivées, avec une clé et un remplacement de langue vides. Le formulaire de configuration se trouve à /admin/config/services/chattybox et nécessite la permission administer chattybox configuration. Le module charge le widget ; il n’explore ni ne synchronise le contenu Drupal.

Le point de terminaison API est codé en dur dans la version du module auditée ; il n’est ni déduit de la clé ni mis à jour automatiquement. Modifier l’URL du loader ne modifie pas ce point de terminaison. Comparez-le à l’extrait d’installation de votre site ; si cet extrait utilise un autre déploiement API, utilisez son intégration manuelle du widget sans le module. Les URL de scripts distants doivent utiliser HTTPS (HTTP est autorisé uniquement pour les hôtes de développement locaux).

Les clés créées sans restriction fonctionnent depuis toutes les origines du navigateur ; une clé préparée pour un site peut déjà être limitée à l’origine de ce site. Les restrictions facultatives dans Installer → Clés et domaines exigent chaque schéma, nom d’hôte et port prévus. Une clé restreinte renvoie 401 Invalid API key si l’origine effective est absente ou non autorisée ; elle provient de Origin ou, à défaut, de l’origine de Referer. Les restrictions d’origine constituent un renforcement supplémentaire, pas une authentification des visiteurs.

Exclure d’autres routes​

Le module ignore automatiquement les routes d’administration. Un module personnalisé peut désactiver le widget sur d’autres routes publiques avec hook_chattybox_load_widget_alter() :

Les contrôles des routes d’administration ne protègent pas la confidentialité de tout le contenu du frontend. Ajoutez des exclusions pour les routes de paiement, de compte et d’adhésion, selon les besoins ; le nom de route ci-dessous est donné à titre d’exemple. Le module n’ajoute ni contexte ni tag de cache pour la décision du hook. Implémentez et vérifiez la variation et l’invalidation du cache propres au site pour chaque condition, aussi bien lorsque le widget est ajouté que lorsqu’il ne l’est pas, dans les caches Drupal et intermédiaires. Une exclusion ne constitue pas une frontière de contrôle d’accès.

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

Solution de repli manuelle​

Composer est la méthode d’installation recommandée. Si votre déploiement Drupal ne peut pas utiliser Composer, copiez le module dans web/modules/custom/chattybox ou un autre répertoire de modules personnalisés, activez-le et configurez-le depuis Configuration > Web services > ChattyBox.

Ne saisissez pas d’identifiants d’administration ChattyBox dans le module. La clé API publique du widget est destinée au balisage frontend.

Choisissez un seul loader : n’activez pas le module en même temps qu’un extrait de thème, une balise GTM ou un montage SDK. Le module audité n’insère pas son script s’il trouve un élément script[data-chattybox-widget="true"] marqué ; il ne valide ni ne reconfigure ce script et ne détecte pas les scripts non marqués.

Le loader automatique du module ne vérifie pas le consentement avant son initialisation. Si le consentement doit être recueilli avant toute requête, utilisez une intégration compatible avec le consentement au lieu d’activer ce loader automatique. Lors des changements de route d’une SPA ou du retrait du consentement, empêchez le chargement sur les routes exclues et démontez activement tout widget initialisé au moyen d’une intégration prise en charge par le loader déployé ; le masquer ou supprimer uniquement la balise script ne suffit pas. Ne réinitialisez le widget que lorsque cela est autorisé. Le démontage ne peut pas annuler les requêtes déjà traitées par le serveur.

Vérification​

Après avoir configuré le module :

  • Ouvrez une page Drupal publique dans une fenêtre de navigation privée.
  • Vérifiez que le lanceur du widget apparaît une seule fois.
  • Posez une vraie question de visiteur.
  • Vérifiez qu’une réponse prise en charge cite les pages Drupal publiques indexées et qu’une question non prise en charge affiche la réponse de repli, qui peut ne comporter aucune source.
  • Consultez la console du navigateur pour détecter l’absence de data-api-key, data-api-url ou des erreurs de clé.
  • Testez les routes incluses et exclues avec les caches Drupal, de page et CDN froids et chauds. Reconstruisez les caches concernés après toute modification des paramètres ou du hook. Une exclusion côté serveur ne démonte pas un widget déjà chargé lors d’une navigation côté client.

Consultez la checklist de lancement avant d’annoncer le chatbot.