Passa al contenuto principale

Modulo chatbot Drupal

Usa il modulo Drupal ufficiale di ChattyBox se desideri un'installazione gestita con Composer per un sito Drupal 10 o Drupal 11. Il modulo 0.1.0 verificato localmente aggiunge il loader del widget ospitato alle richieste idonee non amministrative il cui formato della richiesta Drupal è HTML e usa un endpoint API fisso nel codice. Questa guida illustra la configurazione operativa. La pagina del modulo chatbot AI per Drupal riassume il prodotto e il flusso di valutazione.

Prima dell'installazione​

Completa prima il flusso Per iniziare: collega il tuo URL Drupal pubblico, esamina le pagine indicizzate e verifica risposte rappresentative in Prova il chatbot. In Installa → Chiavi e domini, esamina una chiave pubblica del widget o creane una; in entrambi i casi, controlla le relative impostazioni delle origini. In Installa → Installazione sul sito web, seleziona una chiave adatta e copia il valore data-api-key dallo snippet di installazione.

Installazione con Composer​

Questa installazione usa il repository GitHub pubblico come sorgente VCS di Composer. Aggiungi la dichiarazione del repository riportata sotto prima di eseguire composer require; verifica la disponibilità e i tag attuali del pacchetto prima dell'installazione.

Aggiungi il repository GitHub pubblico al composer.json principale del progetto Drupal che utilizza il modulo:

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

Se il progetto ha già una sezione repositories, unisci a essa la voce chattybox-drupal. Poi installa il modulo contrassegnato da tag:

composer require openstaticfish/chattybox-drupal:^0.1

Il pacchetto è dichiarato come drupal-module e richiede Drupal ^10 || ^11; il modulo dichiara PHP 8.1 come versione minima, anche se la versione di Drupal scelta potrebbe richiedere una versione più recente di PHP. I percorsi standard dell'installer Drupal Composer spesso collocano il modulo in web/modules/contrib/, ma le mappature del progetto possono variare. ^0.1 è un vincolo di versione, non fissa una versione esatta: Composer risolve una versione e la registra nel lockfile. Per la riproducibilità, usa una versione esatta.

Prima di aggiornare, consulta il codice sorgente pubblico del modulo Drupal e le modifiche contrassegnate dai tag; verifica il meccanismo di aggiornamento disponibile per la tua installazione.

Per provare invece l'attuale branch di sviluppo:

composer require openstaticfish/chattybox-drupal:dev-main

Abilitazione e configurazione​

  1. Abilita ChattyBox da Extend oppure esegui drush en chattybox.
  2. Apri Configuration > Web services > ChattyBox.
  3. Incolla solo la chiave API pubblica del widget dal relativo snippet di installazione sul sito.
  4. Lascia l'URL dello script del widget ospitato, a meno che ChattyBox non ti abbia fornito un URL del loader di anteprima o ospitato autonomamente.
  5. Lascia vuoto l'override della lingua per seguire la policy delle lingue del progetto oppure inserisci un codice supportato in minuscolo, ad esempio en, fr o de. Un override supportato ha la precedenza solo se il progetto consente gli override tramite script. Nel widget ospitato v16 descritto dal sorgente attuale, la modalità Rilevamento automatico prova prima la lingua della pagina, poi quelle del browser e infine la lingua predefinita configurata; ignora i valori non supportati e, se nessuno è supportato, usa l'inglese. La modalità Fissa usa la lingua predefinita supportata del progetto oppure l'inglese. Verifica il loader effettivamente distribuito prima di fare affidamento su questo comportamento, poiché è versionato separatamente.
  6. Abilita il chatbot e salva la configurazione.

L'hook hook_page_attachments() del modulo verificato non allega il loader del widget sulle route amministrative né per le richieste il cui formato Drupal non è HTML; non controlla il Content-Type della risposta finale e non determina se il contenuto frontend sia privato. Per le richieste idonee, aggiunge la chiave pubblica, l'endpoint fisso, la lingua opzionale e il loader del widget tramite la libreria dichiarata di Drupal e drupalSettings.

Le nuove installazioni sono disattivate, con chiave e override della lingua vuoti. Il modulo si configura da /admin/config/services/chattybox, con il permesso administer chattybox configuration. Carica il widget, ma non esegue il crawling né la sincronizzazione dei contenuti Drupal.

Nella versione verificata, l'endpoint API è fisso nel codice del modulo: non viene ricavato dalla chiave né aggiornato automaticamente. Cambiare l'URL del loader non cambia l'endpoint. Confrontalo con lo snippet di installazione del sito; se lo snippet usa un'altra istanza dell'API, usa la relativa integrazione manuale del widget senza il modulo. Gli URL degli script remoti devono usare HTTPS; HTTP è consentito solo per host locali di sviluppo (localhost, 127.0.0.1 e ::1).

Le chiavi senza restrizioni funzionano da tutte le origini del browser; una chiave preparata per un sito può essere già limitata all'origine di quel sito. Le restrizioni opzionali in Installa → Chiavi e domini richiedono ogni combinazione prevista di schema, nome host e porta. Per una chiave limitata, l'API restituisce 401 Invalid API key se l'origine effettiva manca o non è consentita: viene ricavata da Origin oppure, se assente, dall'origine di Referer. Le restrizioni di origine sono un'ulteriore misura di protezione, non un'autenticazione dei visitatori.

Esclusione di altre route​

Il modulo salta automaticamente le route amministrative. Un modulo personalizzato può disabilitare il widget su altre route pubbliche con hook_chattybox_load_widget_alter():

I controlli delle route amministrative non proteggono la privacy di tutti i contenuti frontend. Aggiungi esclusioni per le route di checkout, account e delle aree riservate agli iscritti, se opportuno; il nome della route seguente è solo un esempio. Il modulo non aggiunge contesti né tag di cache per la decisione dell'hook. Implementa e verifica le variazioni e l'invalidazione della cache specifiche del sito per ogni condizione, sia nei casi in cui il widget viene allegato sia in quelli in cui non viene allegato, attraverso Drupal e le cache intermedie. Un'esclusione non è un confine di controllo degli accessi.

/**
 * 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 manuale​

Composer è il percorso di installazione consigliato. Se il tuo deployment Drupal non può usare Composer, copia il modulo in web/modules/custom/chattybox o in un'altra directory per moduli personalizzati, abilitalo e configuralo da Configuration > Web services > ChattyBox.

Non inserire credenziali di gestione nel modulo. La chiave API pubblica del widget è destinata al markup frontend.

Usa un solo loader: non abilitare il modulo insieme a uno snippet del tema, a un tag GTM o a un mount SDK. La versione verificata del modulo non inserisce un altro script se trova qualsiasi script[data-chattybox-widget="true"] contrassegnato; non convalida né riconfigura quello script e non rileva gli script senza contrassegno.

Il loader automatico del modulo non verifica il consenso prima di inizializzarsi. Se il consenso è necessario prima dell'invio delle richieste, usa un'integrazione compatibile con la gestione del consenso al posto del loader automatico. Durante i cambi di route SPA o la revoca del consenso, impedisci il caricamento sulle route escluse e smonta attivamente il widget già inizializzato tramite un'integrazione supportata dal loader effettivamente distribuito; nasconderlo o rimuovere solo il tag script non basta. Reinizializzalo solo quando è consentito. Lo smontaggio non può annullare le richieste già elaborate dal server.

Verifica​

Dopo aver configurato il modulo:

  • Apri una pagina Drupal pubblica in una finestra di navigazione in incognito.
  • Verifica che il launcher del widget compaia una sola volta.
  • Poni una domanda reale di un visitatore.
  • Verifica che una risposta supportata citi pagine Drupal pubbliche indicizzate e che una domanda senza supporto mostri la risposta di fallback, che potrebbe non contenere fonti.
  • Controlla la console del browser per data-api-key, data-api-url mancanti o errori della chiave.
  • Prova sia le route escluse sia quelle incluse con le cache Drupal, di pagina e CDN calde e fredde. Ricostruisci le cache pertinenti dopo modifiche alle impostazioni o all'hook. Un'esclusione server-side di una route non smonta il widget già caricato durante la navigazione client-side.

Continua con la checklist di lancio prima di annunciare il chatbot.