Integrazione web e incorporamento avanzati

Il codice di incorporamento standard di AIsuru è progettato per semplificare l'aggiunta di un Agente a un sito web senza creare un frontend personalizzato.

Per la maggior parte delle integrazioni, copia il codice generato da AIsuru e aggiungilo alla tua pagina. Se hai bisogno di un controllo più approfondito, lo stesso componente può anche essere configurato e integrato programmaticamente.

Cerchi i passaggi di installazione di base? Consulta Incorporare il tuo Agente in un sito web.

L'incorporamento utilizza un Web Component

L'embed web di AIsuru si basa su un Web Component standard anziché su un'integrazione basata solo su iframe.

Un Web Component può essere aggiunto direttamente a una pagina HTML e configurato tramite attributi HTML senza richiedere uno specifico framework JavaScript.

Questa architettura consente inoltre un'interazione più approfondita con la pagina ospitante, quando necessario.

Perché utilizzare un Web Component?

Rispetto a un'integrazione isolata basata solo su iframe, il Web Component può supportare:

• configurazione tramite attributi HTML;

• integrazione diretta con la pagina circostante;

• interazione con gli elementi della pagina ospitante e il DOM;

• contesto e messaggistica programmatici;

• eventi del browser emessi dall'Agente;

• stile e personalizzazione del frontend;

• esperienze di applicazioni web più complesse.

Per una semplice integrazione in un sito web, non è necessario utilizzare queste funzionalità. Il codice di incorporamento generato è sufficiente.

Caricare il componente

Una tipica installazione CDN carica il Web Component e il relativo foglio di stile prima di aggiungere un elemento <memori-client>:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@memori.ai/memori-webcomponent/dist/memori-webcomponent.js">
</script>

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@memori.ai/memori-react/dist/styles.min.css"
/>

<memori-client
  memoriName="MyAgent"
  ownerUserName="my-user"
  tenantID="www.aisuru.com"
  height="500px"
  multilingual="true"
></memori-client>

Il codice esatto generato per il tuo Agente può contenere attributi aggiuntivi a seconda dell'Agente, del tenant, dell'integrazione e del layout selezionato.

Comprendere<memori-client>

<memori-client>è l'elemento HTML personalizzato che esegue il rendering dell'Agente.

I suoi attributi identificano l'Agente e controllano gli aspetti supportati del comportamento del componente.

Un esempio più personalizzato può avere questo aspetto:

<memori-client
  memoriName="MyAgent"
  ownerUserName="my-user"
  tenantID="www.aisuru.com"
  context="LOCATION:Milan,USER_TYPE:premium"
  height="100vh"
  showShare="true"
  showSettings="true"
  multilingual="true"
></memori-client>

Attributi di configurazione documentati

L'insieme esatto degli attributi può evolvere con i pacchetti frontend. Parti dal codice generato da AIsuru e usa la documentazione Frontend aggiornata come riferimento tecnico per la versione in uso.

Gli attributi e i concetti di integrazione documentati nei riferimenti embed e Frontend includono:

Attributo / concetto	Scopo
memoriName	Identifica l'Agente per nome
memoriID	Identifica l'Agente tramite il suo ID univoco quando utilizzato dall'integrazione
ownerUserName	Identifica il proprietario dell'Agente tramite nome utente
ownerUserID	Identifica il proprietario dell'Agente tramite ID quando richiesto
tenantID	Identifica il tenant/ambiente AIsuru
apiURL	Definisce l'endpoint backend/API quando configurato esplicitamente
engineURL	Definisce l'endpoint del motore quando configurato esplicitamente
baseURL	Definisce l'URL di base utilizzato dall'integrazione
height	Controlla l'altezza del componente
uiLang	Controlla la lingua dell'interfaccia quando supportata dall'integrazione
spokenLang	Controlla la lingua parlata/predefinita quando supportata dall'integrazione
layout	Seleziona il layout quando configurato direttamente a livello di componente
multilingual	Abilita il comportamento multilingue
showShare	Controlla la disponibilità dei controlli di condivisione quando supportati
showSettings	Controlla la disponibilità dell'interfaccia delle impostazioni quando supportata
integrationID	Identifica un'integrazione specifica
tag/ pin	Parametri legacy/documentati di assegnazione di ruolo-persona utilizzati da alcune integrazioni
context	Fornisce il contesto iniziale alla conversazione
initialQuestion	Fornisce una domanda/istruzione iniziale quando supportata
sessionID	Riprende una sessione precedente quando supportata e valida
authToken	Fornisce un token utente autenticato nelle integrazioni che lo richiedono
secretToken	Fornisce il token segreto/password per Agenti privati o segreti, se supportato

Importante: Non aggiungere manualmente identificatori o attributi a meno che tu non sappia quale valore si aspetta l'integrazione. Il codice di embed generato dovrebbe essere il tuo punto di partenza.

Controlli dell'interfaccia a livello di sviluppatore

I riferimenti React/frontend espongono controlli aggiuntivi per gli elementi dell'interfaccia. Non dovrebbero essere documentati automaticamente come opzioni nell'editor no-code del layout di condivisione, a meno che non siano effettivamente presenti.

I controlli a livello di sviluppatore attualmente documentati includono:

Proprietà / controllo	Scopo
showShare	Mostra il controllo di condivisione
showSettings	Mostra il pannello delle impostazioni
showTypingText	Mostra il testo di digitazione/caricamento
showInstruct	Mostra l'interruttore della modalità istruzioni
showOnlyLastMessages	Limita la chat visibile ai messaggi più recenti
showClear	Mostra il controllo per cancellare la chat/la cronologia
showLogin	Mostra il controllo di accesso
showCopyButton	Mostra il controllo per copiare i messaggi
showTranslationOriginal	Mostra il testo originale associato alla traduzione
enableAudio	Abilita l'output audio

Considerali funzionalità del frontend. Occorre verificare separatamente se gli stessi controlli sono disponibili nell'attuale editor del layout di condivisione di AIsuru.

Passare il contesto dalla pagina

Il componente può ricevere un contesto iniziale affinché l'Agente sappia qualcosa dell'ambiente in cui inizia la conversazione.

<memori-client
  memoriName="MyAgent"
  ownerUserName="my-user"
  tenantID="www.aisuru.com"
  context="LOCATION:Milan,USER_TYPE:premium"
></memori-client>

Questo è utile quando lo stesso Agente è incorporato in pagine, aree clienti, posizioni o applicazioni diverse.

Per il contesto no-code configurato a livello di layout di condivisione, consulta le Impostazioni avanzate del layout.

Ascoltare gli eventi dell'Agente

L'integrazione web può emettere eventi del browser che consentono alla pagina ospitante di reagire allo stato dell'Agente.

Ad esempio:

<script>
  document.addEventListener("MemoriNewDialogState", (event) => {
    const state = event.detail;
    console.log("New dialog state:", state);
  });

  document.addEventListener("MemoriEndSpeak", () => {
    console.log("The Agent finished speaking");
  });
</script>

L'integrazione basata su eventi può essere utile quando la tua pagina deve:

• aggiornare altri elementi dell'interfaccia dopo una risposta dell'Agente;

• visualizzare informazioni su prodotti o servizi;

• sincronizzare l'Agente con lo stato dell'applicazione;

• attivare comportamenti specifici della pagina.

Inviare messaggi dalla pagina host

I controlli personalizzati nella pagina possono inviare messaggi all'Agente.

<script>
  function sendCustomMessage() {
    window.typeMessage("Hello from a custom button!");
  }
</script>

<button onclick="sendCustomMessage()">
  Send message
</button>

Dove supportati, i messaggi nascosti possono comunicare informazioni o comandi senza visualizzare il testo come un normale messaggio dell'utente:

<script>
  function sendHiddenMessage() {
    window.typeMessageHidden("system:update", true);
  }
</script>

Verifica il comportamento rispetto alla versione del pacchetto frontend in uso prima di fare affidamento su flussi programmatici o di messaggi nascosti.

Riprendere una sessione a livello programmatico

Quando viene fornito un sessionID valido, le integrazioni supportate possono riprendere la conversazione associata anziché avviarne una nuova.

<memori-client
  memoriName="MyAgent"
  ownerUserName="my-user"
  tenantID="www.aisuru.com"
  sessionID="session-uuid"
></memori-client>

Per il comportamento completo di ripresa della sessione e il relativo ciclo di vita, consulta la documentazione Frontend dedicata.

Stile e personalizzazione visiva

L'editor del layout di condivisione dovrebbe essere il punto di partenza per la normale configurazione visiva.

A livello frontend, AIsuru supporta anche la personalizzazione basata su CSS. È utile quando devi integrare il componente in un design system esistente, adattare dimensioni o spaziature, oppure coordinarlo con altri elementi della pagina.

La documentazione Frontend fornisce variabili CSS per valori di tema comuni, come colori primari, colori del testo, sfondi, bolle di chat, pulsanti, pannelli a scomparsa e finestre modali.

Le integrazioni meno recenti possono anche indirizzare specifiche classi CSS generate. Ad esempio, le bolle di chat o singoli elementi dell'interfaccia possono essere stilizzati o nascosti selezionando la classe o l'elemento HTML corrispondente.

Poiché il markup generato può cambiare, ispeziona il componente corrente prima di fare affidamento sui nomi delle classi interne e, ove possibile, preferisci le variabili CSS supportate.

Esempi di selettori legacy

La precedente documentazione sull'analisi dell'embed includeva esempi che indirizzavano direttamente classi generate, tra cui:

.memori-chat--bubble.memori-chat--with-addon {
  color: #000;
  background-color: #f0f0f0;
}

.memori-chat--ai-generated {
  color: #000;
  background-color: #f0f0f0;
}

.memori-chat--bubble.memori-chat--user-bubble {
  color: #000;
  background-color: #f0f0f0;
}

.memori-button .memori-blob figure {
  opacity: 0;
}

Questi esempi mostrano che le risposte dell'Agente, le risposte generate dall'IA, i messaggi degli utenti e specifici elementi visivi possono essere indirizzati separatamente. Ricontrolla i selettori rispetto al componente attualmente renderizzato prima di usarli in produzione.

Snippet CSS, JavaScript e dell'Agente

I comportamenti avanzati possono essere implementati in luoghi diversi:

• CSS nella pagina host per gli stili che devono essere applicati immediatamente;

• JavaScript nella pagina host per l'interazione a livello di applicazione;

• Snippet dell'Agente per comportamenti CSS o JavaScript attivati da condizioni conversazionali, quando questa funzionalità è appropriata.

Usa il livello più adatto al comportamento che stai implementando invece di inserire tutte le personalizzazioni negli attributi embed.

Comportamento del viewport sui dispositivi mobili

Per integrazioni orientate al tocco in cui il comportamento di zoom del browser è indesiderato, la documentazione legacy sulla condivisione avanzata consiglia di rivedere la configurazione del viewport della pagina.

Una configurazione comunemente utilizzata è:

<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
>

Usala solo se corrisponde ai requisiti di accessibilità e interazione della tua applicazione web.

Quando usare l'embed generato e quando creare un'integrazione per sviluppatori

Usa il codice embed generato quando:

• vuoi aggiungere rapidamente l'Agente a un sito web;

• le opzioni di Sharing Layout soddisfano i tuoi requisiti;

• ti serve solo una configurazione limitata;

• vuoi che AIsuru gestisca la maggior parte della presentazione.

Valuta un'integrazione a livello di sviluppatore quando:

• l'Agente deve reagire a uno stato personalizzato della pagina;

• la pagina deve reagire agli eventi dell'Agente;

• ti servono contesto, messaggistica o gestione delle sessioni a livello di programmazione;

• ti serve un comportamento frontend che vada oltre l'editor di Sharing Layout;

• stai integrando l'Agente in un'applicazione JavaScript o React più ampia.

Documentazione frontend

Per le integrazioni per sviluppatori, consulta anche la documentazione di AIsuru Frontend, in particolare le sezioni dedicate a:

• Web Component;

• Componente React;

• Stile e personalizzazione;

• API client.

• Ripresa e gestione delle sessioni.

La documentazione di base su Condivisione e pubblicazione rimane il punto di partenza consigliato quando devi solo pubblicare un Agente utilizzando le opzioni fornite dall'interfaccia AIsuru.