Saltar al contenido principal

Módulo de chatbot de Drupal

Usa el módulo oficial de Drupal de ChattyBox para una instalación gestionada con Composer en un sitio de Drupal 10 u 11. El módulo de Drupal de ChattyBox, versión 0.1.0 y auditado localmente, añade el loader del widget alojado a las solicitudes aptas no administrativas cuyo formato de Drupal es HTML. Usa un endpoint de API codificado de forma fija. Esta guía cubre la configuración operativa. La página del módulo de chatbot de IA para Drupal resume el producto y el flujo de evaluación.

Antes de instalar​

Completa primero el flujo de Primeros pasos: conecta tu URL pública de Drupal, revisa las páginas indexadas y verifica respuestas representativas en Probar chatbot. En Instalar → Claves y dominios, revisa una clave pública del widget existente o crea una; en ambos casos, comprueba su configuración de origen. En Instalar → Instalación en el sitio web, selecciona una clave adecuada y copia su valor data-api-key del fragmento de instalación.

Instalación con Composer​

Esta instalación usa el repositorio público de GitHub como fuente VCS de Composer. Añade la declaración de repositorio que aparece abajo antes de ejecutar composer require y comprueba la disponibilidad actual del paquete y sus etiquetas antes de instalarlo.

Añade el repositorio público de GitHub al composer.json raíz del proyecto Drupal que lo consuma:

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

Si el proyecto ya tiene una sección repositories, combina con ella la entrada chattybox-drupal. Después, instala el módulo etiquetado:

composer require openstaticfish/chattybox-drupal:^0.1

El paquete está declarado como drupal-module y requiere Drupal ^10 || ^11; el módulo declara PHP 8.1 como versión mínima, aunque tu versión de Drupal podría requerir una más reciente. Las rutas estándar de instalación de Composer para Drupal suelen colocarlo en web/modules/contrib/, pero las asignaciones de rutas del proyecto pueden variar. ^0.1 es una restricción de versión, no una versión exacta: Composer resuelve una versión y la registra en el archivo de bloqueo. Usa una versión exacta si necesitas reproducibilidad.

Revisa el código fuente público del módulo de Drupal y los cambios etiquetados antes de actualizar; confirma qué mecanismo de actualización está disponible para tu instalación.

Para probar en su lugar la rama de desarrollo actual:

composer require openstaticfish/chattybox-drupal:dev-main

Activar y configurar​

  1. Activa ChattyBox desde Extend o ejecuta drush en chattybox.
  2. Abre Configuration > Web services > ChattyBox.
  3. Pega solo la clave API pública del widget del fragmento de instalación del sitio web.
  4. Deja la URL del script del widget alojado, a menos que ChattyBox te haya proporcionado una URL de loader de vista previa o autoalojada.
  5. Deja vacía la anulación de idioma para seguir la política de idioma del proyecto o introduce un código admitido en minúsculas, como en, fr o de. Una anulación admitida solo tiene prioridad si el proyecto permite las anulaciones por script. Según el código fuente auditado actualmente del widget alojado v16, el modo automático prueba primero el idioma de la página, después los idiomas del navegador y, por último, el idioma predeterminado configurado; omite los valores no compatibles y finalmente recurre al inglés. El modo fijo usa el idioma predeterminado del proyecto si es compatible y, si no, el inglés. Comprueba el loader desplegado antes de confiar en este comportamiento, que tiene un versionado independiente.
  6. Activa el chatbot y guarda la configuración.

El módulo auditado no adjunta el loader del widget en las rutas administrativas ni en las solicitudes cuyo formato de petición de Drupal no sea HTML; no inspecciona el Content-Type de la respuesta final ni determina si el contenido del frontend es privado. En las solicitudes aptas, adjunta la biblioteca de Drupal declarada para el loader y proporciona en drupalSettings la clave pública, el endpoint codificado de forma fija y el idioma opcional.

Las instalaciones nuevas empiezan desactivadas, con la clave y la anulación de idioma vacías. El formulario de configuración está en /admin/config/services/chattybox y requiere el permiso administer chattybox configuration. El módulo carga el widget, pero no rastrea ni sincroniza el contenido de Drupal.

El endpoint de API está codificado de forma fija en la versión auditada del módulo: no se obtiene de la clave ni se actualiza automáticamente. Cambiar la URL del loader no cambia ese endpoint. Compáralo con el fragmento de instalación del sitio web; si el fragmento usa otro despliegue de API, utiliza su integración manual del widget sin el módulo. Las URL de scripts remotos deben usar HTTPS (HTTP solo se permite para hosts de desarrollo locales).

Las claves creadas sin restricciones funcionan desde cualquier origen del navegador; una clave preparada para un sitio web puede estar restringida de antemano al origen de ese sitio. Las restricciones opcionales de Instalar → Claves y dominios requieren cada esquema, nombre de host y puerto previstos. Una clave restringida devuelve 401 Invalid API key si falta el origen efectivo o no está permitido; se obtiene de Origin o, si no existe, del origen de Referer. Las restricciones de origen son una protección adicional, no autentican a los visitantes.

Excluir rutas adicionales​

El módulo omite automáticamente las rutas administrativas. Un módulo personalizado puede desactivar el widget en otras rutas públicas con hook_chattybox_load_widget_alter():

Las comprobaciones de rutas administrativas no protegen la privacidad de todo el contenido del frontend. Añade exclusiones para las rutas de pago, cuenta y membresía cuando corresponda; el nombre de ruta siguiente es solo ilustrativo. El módulo no añade contextos ni etiquetas de caché para la decisión del hook. Implementa y verifica la variación e invalidación de caché específica del sitio para cada condición, tanto si se adjuntan recursos como si no, en las cachés de Drupal y las intermediarias. Una exclusión no es un límite de control de acceso.

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

Alternativa manual​

Composer es la ruta de instalación recomendada. Si tu despliegue de Drupal no puede usar Composer, copia el módulo en web/modules/custom/chattybox o en otro directorio de módulos personalizados, actívalo y configúralo desde Configuration > Web services > ChattyBox.

No introduzcas credenciales de administración de ChattyBox en el módulo. La clave API pública del widget está pensada para el marcado del frontend.

Elige un solo loader: no actives el módulo junto con un fragmento del tema, una etiqueta de GTM o un montaje de SDK. El módulo auditado no inserta su script si encuentra cualquier elemento marcado script[data-chattybox-widget="true"]; no valida ni reconfigura ese script y no detecta scripts sin marcar.

El loader automático del módulo no comprueba el consentimiento antes de inicializarse. Si se requiere consentimiento antes de realizar solicitudes, usa una integración compatible con la gestión del consentimiento en lugar de activar este loader automático. Al cambiar de ruta en una SPA o retirar el consentimiento, impide la carga en las rutas excluidas y desmonta activamente cualquier widget inicializado mediante una integración compatible con el loader desplegado; ocultarlo o quitar solo la etiqueta del script no basta. Vuelve a inicializarlo únicamente cuando esté permitido. El desmontaje no puede deshacer las solicitudes que el servidor ya haya procesado.

Verificación​

Después de configurar el módulo:

  • Abre una página pública de Drupal en una ventana de incógnito.
  • Confirma que el lanzador del widget aparece una sola vez.
  • Haz una pregunta real de visitante.
  • Verifica que una respuesta respaldada cite páginas públicas de Drupal indexadas y que una pregunta sin respaldo muestre la respuesta alternativa, que puede no incluir fuentes.
  • Comprueba en la consola del navegador si faltan data-api-key o data-api-url, o si hay errores de clave.
  • Prueba las rutas incluidas y excluidas con las cachés de Drupal, de página y CDN frías y calientes. Reconstruye las cachés pertinentes después de cambiar la configuración o el hook. Una exclusión del servidor no desmonta un widget ya cargado al navegar del lado del cliente.

Continúa con la lista de comprobación de lanzamiento antes de anunciar el chatbot.