Módulo de chatbot Drupal

Utilize o módulo oficial do ChattyBox para uma instalação gerida pelo Composer num site Drupal 10 ou Drupal 11. A versão 0.1.0 do módulo, analisada localmente, anexa o loader alojado do widget a pedidos elegíveis não administrativos cujo formato de pedido do Drupal é HTML e utiliza um endpoint de API definido diretamente no código. Este guia aborda a configuração operacional. A página do módulo de chatbot IA para Drupal apresenta o produto e o fluxo de avaliação.

Antes de instalar

Conclua primeiro o fluxo Primeiros passos: ligue o URL público do Drupal, reveja as páginas indexadas e verifique respostas representativas em Testar chatbot. Em Instalar → Chaves e domínios, reveja uma chave pública do widget ou crie uma; em qualquer dos casos, verifique as respetivas definições de origem. Em Instalar → Instalação no site, selecione uma chave adequada e copie o valor de data-api-key do excerto de instalação.

Instalação com Composer

Esta instalação utiliza o repositório público do GitHub como origem VCS do Composer. Adicione a declaração do repositório abaixo antes de executar composer require; verifique a disponibilidade atual do pacote e das respetivas tags antes de instalar.

Adicione o repositório público do GitHub ao composer.json raiz do projeto Drupal que utiliza o módulo:

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

Se o projeto já tiver uma secção repositories, junte-lhe a entrada chattybox-drupal. Em seguida, instale o módulo identificado por tag:

composer require openstaticfish/chattybox-drupal:^0.1

O pacote está declarado como drupal-module e requer Drupal ^10 || ^11; o módulo declara PHP 8.1 como versão mínima, embora a versão do Drupal utilizada possa exigir uma versão superior do PHP. Os caminhos padrão do instalador Composer do Drupal colocam-no frequentemente em web/modules/contrib/, mas os mapeamentos do projeto podem variar. ^0.1 é uma restrição de versão, não uma versão exata: o Composer resolve uma versão e regista-a no ficheiro lock. Para garantir reprodutibilidade, utilize uma versão exata.

Antes de atualizar, consulte o código-fonte público do módulo Drupal e as alterações identificadas por tag; confirme o mecanismo de atualização disponível para a sua instalação.

Para testar, em alternativa, a branch de desenvolvimento atual:

composer require openstaticfish/chattybox-drupal:dev-main

Ativar e configurar

1. Ative o ChattyBox em Extend ou execute drush en chattybox.
2. Abra Configuration > Web services > ChattyBox.
3. Cole apenas a chave de API pública do widget do excerto de instalação do site.
4. Mantenha o URL do script do widget alojado, a menos que o ChattyBox tenha fornecido um URL de pré-visualização ou do loader alojado no seu próprio servidor.
5. Deixe a substituição de idioma em branco para seguir a política de idiomas do projeto, ou introduza um código suportado em minúsculas, como en, fr ou de. Uma substituição suportada só tem prioridade se o projeto permitir substituições através de script. No widget alojado v16 descrito pelo código-fonte atual, o modo Detetar automaticamente tenta primeiro o idioma da página, depois os idiomas do navegador e, por fim, o idioma predefinido configurado; ignora valores não suportados e utiliza inglês se nenhum idioma for suportado. O modo Fixo utiliza o idioma predefinido suportado do projeto ou inglês. Verifique o loader efetivamente implementado antes de confiar neste comportamento, uma vez que é versionado separadamente.
6. Ative o chatbot e guarde a configuração.

O hook hook_page_attachments() do módulo analisado não anexa o loader do widget em rotas administrativas nem em pedidos cujo formato Drupal não seja HTML; não verifica o Content-Type da resposta final nem determina se o conteúdo do frontend é privado. Para pedidos elegíveis, anexa a chave pública, o endpoint fixo, o idioma opcional e o loader do widget através da biblioteca declarada do Drupal e de drupalSettings.

As novas instalações começam desativadas, com a chave e a substituição de idioma vazias. A página de configuração é /admin/config/services/chattybox e requer a permissão administer chattybox configuration. O módulo carrega o widget; não rastreia nem sincroniza conteúdo Drupal.

Na versão analisada, o endpoint de API está definido diretamente no código do módulo; não é obtido a partir da chave nem atualizado automaticamente. Alterar o URL do loader não altera esse endpoint. Compare-o com o excerto de instalação do site; se este utilizar uma implementação de API diferente, utilize a integração manual do widget correspondente, sem o módulo. Os URL de scripts remotos têm de utilizar HTTPS; HTTP só é permitido para hosts locais de desenvolvimento (localhost, 127.0.0.1 e ::1).

As chaves sem restrições funcionam a partir de todas as origens do navegador; uma chave preparada para um site pode já estar limitada à origem desse site. As restrições opcionais em Instalar → Chaves e domínios exigem o esquema, o nome do host e a porta pretendidos. Para uma chave restrita, a API devolve 401 Invalid API key quando a origem efetiva está em falta ou não é permitida. A origem é obtida de Origin ou, se esse cabeçalho não existir, da origem de Referer. As restrições de origem são uma camada adicional de proteção, não autenticação de visitantes.

Excluir rotas adicionais

O módulo ignora automaticamente as rotas administrativas. Um módulo personalizado pode desativar o widget noutras rotas públicas através de hook_chattybox_load_widget_alter():

As verificações de rotas administrativas não protegem a privacidade de todo o conteúdo do frontend. Quando necessário, exclua também as rotas de checkout, conta e áreas reservadas a membros; o nome da rota abaixo é apenas ilustrativo. O módulo não adiciona contextos nem tags de cache à decisão do hook. Implemente e teste a variação e invalidação de cache específicas do site para cada condição, tanto nos casos em que o widget é anexado como nos casos em que não o é, nas caches do Drupal e nas caches intermédias. Uma exclusão não é um limite de controlo de acesso.

/**
 * 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 é o método de instalação recomendado. Se a implementação Drupal não puder utilizar Composer, copie o módulo para web/modules/custom/chattybox ou outro diretório de módulos personalizados, ative-o e configure-o em Configuration > Web services > ChattyBox.

Não introduza uma credencial de gestão no módulo. A chave de API pública do widget destina-se à marcação do frontend.

Utilize um único loader: não ative o módulo em simultâneo com um excerto do tema, uma etiqueta GTM ou uma montagem do SDK. A versão analisada do módulo não insere outro script se encontrar qualquer script[data-chattybox-widget="true"] marcado; não valida nem reconfigura esse script e não deteta scripts sem essa marcação.

O loader automático do módulo não verifica o consentimento antes de inicializar. Se for necessário obter consentimento antes de enviar pedidos, utilize uma integração que respeite o consentimento em vez deste loader automático. Em mudanças de rota SPA ou quando o consentimento é retirado, impeça o carregamento nas rotas excluídas e desmonte ativamente o widget já inicializado através de uma integração suportada pelo loader efetivamente implementado; ocultá-lo ou remover apenas a etiqueta script não é suficiente. Volte a inicializá-lo apenas quando for permitido. A desmontagem não pode anular pedidos já processados pelo servidor.

Verificação

Depois de configurar o módulo:

• Abra uma página pública do Drupal numa janela anónima.
• Confirme que o launcher do widget aparece uma única vez.
• Faça uma pergunta real de um visitante.
• Verifique se uma resposta suportada cita páginas públicas do Drupal indexadas e se uma pergunta sem suporte apresenta a resposta de fallback, que poderá não ter fontes.
• Verifique a consola do navegador em busca de data-api-key, data-api-url em falta ou erros de chave.
• Teste as rotas excluídas e incluídas com as caches do Drupal, da página e da CDN quentes e frias. Reconstrua as caches relevantes após alterações às definições ou ao hook. Uma exclusão de rota no servidor não desmonta um widget já carregado durante a navegação do lado do cliente.

Continue com a checklist de lançamento antes de anunciar o chatbot.