Come aggiungere il chatbot IA Asyntai a Docusaurus

Guida passo passo per i siti di documentazione Docusaurus

Piattaforma:

Passaggio 1: ottieni il tuo codice di incorporamento

Per prima cosa, vai alla tua Dashboard Asyntai e scorri fino alla sezione "Codice di incorporamento". Copia il tuo codice di incorporamento univoco che apparirà così:

<script async src="https://asyntai.com/static/js/chat-widget.js" data-asyntai-id="YOUR_WIDGET_ID"></script>

Nota: Il codice sopra è solo un esempio. Devi copiare il tuo codice di incorporamento univoco dalla tua Dashboard poiché contiene il tuo ID widget personale.

Passaggio 2: Aggiungi lo script a docusaurus.config.js (consigliato)

Il modo migliore per aggiungere il chatbot a tutte le pagine del tuo sito Docusaurus è tramite il file di configurazione:

Apri il tuo progetto Docusaurus nel tuo editor di codice
Trova e apri il file docusaurus.config.js nella root del progetto
Trova l'oggetto const config = { }
Aggiungi o aggiorna il campo scripts con il tuo widget Asyntai:

const config = {
  // ... other config options

  scripts: [
    // Other scripts if any
    {
      src: 'https://asyntai.com/static/js/chat-widget.js',
      'data-asyntai-id': 'YOUR_WIDGET_ID',
      async: true,
    },
  ],

  // ... rest of config
};

Salva il file docusaurus.config.js
Ricostruisci il tuo sito eseguendo npm run build o yarn build
Riavvia il server di sviluppo se stai lavorando in locale

Suggerimento: Il campo scripts accetta un array di sorgenti JavaScript. Il tag script verrà inserito automaticamente nell'head HTML di ogni pagina. Questo è il metodo più pulito e manutenibile per i siti Docusaurus.

Metodo alternativo 1: Formato stringa (sintassi più semplice)

Se preferisci un approccio più semplice, puoi usare il formato stringa nell'array scripts:

const config = {
  scripts: [
    'https://asyntai.com/static/js/chat-widget.js',
  ],
};

Nota: Quando usi il formato stringa, dovrai modificare l'URL dello script per includere l'ID del tuo widget come parametro di query, oppure usare il formato oggetto mostrato nel Passaggio 2 che ti permette di impostare direttamente l'attributo data-asyntai-id.

Metodo alternativo 2: Tag head personalizzati

Puoi anche aggiungere lo script usando il campo headTags in docusaurus.config.js:

const config = {
  headTags: [
    {
      tagName: 'script',
      attributes: {
        src: 'https://asyntai.com/static/js/chat-widget.js',
        'data-asyntai-id': 'YOUR_WIDGET_ID',
        async: true,
      },
    },
  ],
};

Suggerimento: Il campo headTags offre un maggiore controllo sui tag HTML esatti inseriti nella sezione <head>. Questo metodo è funzionalmente equivalente all'uso del campo scripts.

Metodo alternativo 3: Template HTML personalizzato (avanzato)

Per gli utenti avanzati che necessitano di un controllo completo sul template HTML:

Crea una nuova directory: src/theme (se non esiste già)
Crea un file: src/theme/Root.js
Aggiungi il seguente codice per iniettare lo script dinamicamente:

import React, { useEffect } from 'react';

export default function Root({children}) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://asyntai.com/static/js/chat-widget.js';
    script.setAttribute('data-asyntai-id', 'YOUR_WIDGET_ID');
    script.async = true;
    document.head.appendChild(script);

    return () => {
      // Cleanup when component unmounts
      document.head.removeChild(script);
    };
  }, []);

  return <>{children}</>;
}

Salva il file e ricostruisci il tuo sito

Importante: Il componente Root.js avvolge l'intera applicazione. Questo metodo avanzato dovrebbe essere utilizzato solo se hai bisogno di logica JavaScript personalizzata o hai requisiti specifici che non possono essere soddisfatti con l'approccio tramite file di configurazione.

Metodo alternativo 4: Swizzle del componente Footer

Puoi personalizzare il footer per includere lo script:

Esegui il comando swizzle: npm run swizzle @docusaurus/theme-classic Footer -- --eject
Questo crea una copia del componente Footer in src/theme/Footer/
Modifica il componente Footer per includere il tuo tag script
Aggiungi lo script prima del tag di chiusura del footer
Salva e ricostruisci il tuo sito

Nota: Lo swizzling ti offre il pieno controllo sui componenti di Docusaurus, ma significa che dovrai mantenere quel componente autonomamente. Gli aggiornamenti di Docusaurus non aggiorneranno automaticamente i componenti modificati tramite swizzle.

Passaggio 3: Compila e distribuisci

Dopo aver aggiunto il codice, compila e distribuisci il tuo sito Docusaurus:

# Build the site
npm run build

# Or with Yarn
yarn build

# Deploy to your hosting platform
# (Vercel, Netlify, GitHub Pages, etc.)

Suggerimento: Durante lo sviluppo, esegui npm start o yarn start per visualizzare le modifiche in anteprima localmente. Il chatbot dovrebbe apparire nell'angolo in basso a destra su tutte le pagine.

Passaggio 4: Verifica l'installazione

Dopo aver distribuito le modifiche, apri il tuo sito di documentazione in una nuova scheda del browser. Dovresti vedere il pulsante del widget chat nell'angolo in basso a destra. Cliccaci sopra per assicurarti che si apra e funzioni correttamente.

Non vedi il widget? Assicurati di aver ricostruito il sito dopo aver apportato le modifiche. Verifica di aver sostituito YOUR_WIDGET_ID con l'ID widget effettivo dalla dashboard. Svuota la cache del browser o visualizza in modalità incognito. Apri la console del browser (F12) per verificare eventuali errori JavaScript.

Documentazione