Integra un assistente in un sito web

Andare online è soprattutto copia-incolla. Aggiungi tre cose alla tua pagina (lo script di runtime di Seekdown, un elemento contenitore e un breve snippet per avviarlo) ed è fatta. Questo è esattamente lo snippet che il prodotto genera per te.

Prima di iniziare

Aggiungi il dominio del sito alle origini consentite.
Genera una chiave API se la modalità di sicurezza è API.
Tieni a portata di mano l’ID dell’assistente.

Snippet

<div id="seekdown-assistant-root"></div>

<!-- Include the public Seekdown runtime -->
<script src="https://saas.seekdown.ai/js/seekdown-assistant.js"></script>

<!-- Initialize the assistant with your assistantId and accessToken -->
<script>
  document.addEventListener('DOMContentLoaded', function () {
    if (window.skdwn?.startAssistant) {
      let seekdownAssistantOptions = {
        assistantId: 'your-assistant-id',
        accessToken: 'your-api-key-or-identity-access-token',
      };

      skdwn.startAssistant(seekdownAssistantOptions);
    } else {
      console.error('skdwn.startAssistant is not available.');
    }
  });
</script>

Il token di accesso è facoltativo

Includi accessToken solo quando la modalità di sicurezza è API (una chiave dell’assistente) o OIDC (il JWT del tuo provider). Un assistente in modalità None può avviarsi solo con assistantId.

Dove inserire lo snippet

Inserisci lo <script> di runtime e il <div> contenitore subito prima del tag di chiusura </body>, così la pagina è caricata prima che l’assistente si avvii.
Il contenitore <div id="seekdown-assistant-root"></div> deve esistere nella pagina: l’assistente si monta al suo interno.
Se il tuo sito applica una Content-Security-Policy rigorosa, consenti lo script e la connessione a saas.seekdown.ai, altrimenti il runtime non si caricherà.

Lo snippet di integrazione annotato: lo script di runtime, il contenitore seekdown-assistant-root e la chiamata di inizializzazione.

Opzioni di inizializzazione

startAssistant(options) accetta un oggetto di opzioni. Solo un paio sono obbligatorie: le altre ti permettono di adattare l’assistente al suo pubblico e al suo aspetto:

Opzione	Obbligatoria	A cosa serve
`assistantId`	Sì	Quale assistente caricare.
`container`	No	Dove montare il widget: un selettore CSS o un elemento DOM. Permette a più assistenti di convivere in una pagina, ognuno nel proprio contenitore. Per impostazione predefinita è l’elemento con id `seekdown-assistant-root`. Vedi Più assistenti in una pagina.
`accessToken`	Per API / OIDC	La chiave dell’assistente (modalità API) o il JWT del tuo provider (OIDC). Omettila per un assistente in modalità None.
`serviceURL`	Automatica	L’URL del servizio Seekdown. Il valore predefinito è `https://saas.seekdown.ai`, quindi normalmente la ometti.
`userId`	No	Un’identità stabile per il visitatore. Se non ne imposti una, Seekdown genera un UUID e lo memorizza nel browser: così un visitatore di ritorno ritrova la sua conversazione e conta come un solo utente unico. Impostala per collegare il visitatore all’ID del tuo account.
`userInformation`	No	Un insieme piatto di stringhe chiave–valore sul visitatore (ad es. `email`, `plan`, `locale`). Accompagnano le analisi come proprietà `user.*`, così puoi segmentare l’utilizzo.
`additionalContext`	No	Una stringa di contesto aggiuntivo inserita nel prompt dell’assistente e resa disponibile ai suoi template in fase di esecuzione: ad esempio una breve frase che descrive l’utente autenticato o la pagina corrente.
`config`	No	Sostituzioni locali unite in profondità alla configurazione remota dell’assistente: tema, layout, pulsante flottante, persino sostituzioni dei template. Ti permette di integrare lo stesso assistente con un aspetto diverso su siti diversi.
`baseURL`	No	URL di base per le risorse statiche dell’assistente; raramente necessario.
`isDebug`	No	Se `true`, registra lo stato dei template nella console: utile mentre sviluppi sostituzioni dei template.

Personalizza per ogni visitatore

userId, userInformation e additionalContext sono il modo per rendere l’assistente consapevole dell’account: ad esempio, passa il piano dell’utente autenticato così i template possono salutarlo o adattare le risposte, senza esporre nulla di segreto nella pagina.

Eventi del ciclo di vita

startAssistant(options, events?) accetta un secondo argomento facoltativo per agganciarti al suo ciclo di vita:

onStarted(): si attiva quando l’assistente è stato montato e (se abilitato) ha ripristinato la conversazione precedente. Usalo per nascondere un indicatore di caricamento o per tracciare "assistente pronto".
onError(error, info): si attiva se l’inizializzazione non riesce; info.componentStack fornisce il contesto. Usalo per mostrare un’alternativa o riprovare.

<script>
  skdwn.startAssistant(
    {
      assistantId: 'your-assistant-id',
      accessToken: 'your-api-key',
      userId: 'customer-42',
      userInformation: { plan: 'pro', locale: 'en-US' },
      additionalContext: 'Signed-in user is on the Pro plan at Acme.',
      config: { settings: { baseTheme: 'dark' } },
    },
    {
      onStarted: function () { console.log('Assistant ready'); },
      onError: function (err, info) { console.error(err, info.componentStack); },
    }
  );
</script>

Più assistenti in una pagina

Puoi eseguire più assistenti contemporaneamente nella stessa pagina: ad esempio una casella di ricerca nell’intestazione e una chat di supporto come pulsante flottante. La regola è semplice: carica il runtime una sola volta, assegna a ogni assistente il proprio contenitore e chiama startAssistant una volta per assistente con un container. Avviarne uno non chiude mai gli altri.

<!-- Load the runtime once -->
<script src="https://saas.seekdown.ai/js/seekdown-assistant.js"></script>

<!-- One container (with a unique id) per assistant -->
<div id="assistant-search"></div>
<div id="assistant-support"></div>

<script>
  const base = { accessToken: 'your-api-key', serviceURL: 'https://saas.seekdown.ai' };

  // Header search assistant
  skdwn.startAssistant({
    ...base,
    assistantId: 'as-search',
    container: '#assistant-search',
    config: { settings: { baseTemplate: 'overlay' } },
  });

  // Floating support chat
  skdwn.startAssistant({
    ...base,
    assistantId: 'as-support',
    container: '#assistant-support',
    config: { settings: { floatingActionButton: { useFloatingActionButton: true } } },
  });
</script>

Ogni istanza è completamente isolata (connessione, configurazione, template e stato propri), quindi possono condividere un assistantId o usarne di diversi senza interferire.

Rivolgersi a un assistente specifico. Il runtime espone una piccola API su window.skdwn:

Proprietà / metodo	Restituisce
`skdwn.instances`	Un array con tutti gli assistenti attivi nella pagina.
`skdwn.instance`	L’assistente contestuale: quello la cui interfaccia ha generato l’evento corrente o che sta eseguendo il rendering. È a questo che fanno riferimento i gestori dei template (`onclick="skdwn.instance.helpers.…"`), così ogni widget controlla sempre se stesso.
`skdwn.instanceFor(target)`	L’assistente montato in un determinato contenitore (un selettore o un elemento), oppure `undefined`. Usalo per controllare un widget specifico dal codice della tua pagina.

// Open the support chat from your own button
const support = window.skdwn.instanceFor('#assistant-support');
window.skdwn.instance = support;                 // point the context at it
support.helpers.toggleShowFloatingWindow(true);  // helpers act on the current context

Alcune note pratiche

- Lo <script> di runtime si carica una sola volta: espone l’unico oggetto window.skdwn. - Gli id dei contenitori devono essere univoci; ometti container per usare il predefinito #seekdown-assistant-root. - Gli avvii vengono messi in coda (un contenitore non può essere montato due volte contemporaneamente), ma avviare un secondo assistente non ferma il primo. - Riavviare un assistente significa chiamare di nuovo startAssistant con lo stesso container: si riavvia solo quello.

Verifica il risultato

Apri la pagina e verifica che l’assistente compaia e risponda.

Risoluzione dei problemi

Se il widget non compare, controlla l’URL dello script, il contenitore e la console del browser.
Se l’accesso è bloccato, controlla le origini consentite e il token.