> For the complete documentation index, see [llms.txt](https://docs.aisuru.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisuru.com/condivisione/publish-your-agent/advanced-embed-and-web-integration.md).

# 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.](broken://pages/3QUpbpKqAe5wJqA547Xm)

### 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>`:

```html
<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:

```html
<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.

```html
<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:

```html
<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.

```html
<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:

```html
<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.

```html
<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:

```css
.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 è:

```html
<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.