Il widget web è un client basato sul web che puoi utilizzare nelle tue applicazioni web e mobile per consentire agli utenti di interagire con la tua applicazione agente tramite chat o voce. Questa guida fornisce una panoramica e istruzioni di configurazione.
Una volta aperto, il widget può essere visualizzato come finestra di dialogo mobile nell'angolo in basso a destra, come riquadro accanto ai contenuti principali o aperto in modalità di dialogo espansa per una conversazione mirata.
Limitazioni
Al momento, le risposte con contenuti avanzati supportano solo l'inglese.
Configurare il widget web
Per incorporare il widget nel tuo sito web:
- Fai clic su Esegui il deployment nella parte superiore del generatore di agenti.
- Fai clic su Crea canale o Nuovo canale.
- Seleziona il tipo di canale Widget web.
- Inserisci un nome per il canale.
- Seleziona o crea una versione dell'applicazione dell'agente.
- Configura altre preferenze, come il tema cromatico e il tipo di esperienza (chat, chiamata o mista).
- Fai clic su Crea canale per generare il codice di deployment.
- Aggiungi il codice di implementazione all'HTML del tuo sito web.
- Configura l'autenticazione per gli utenti finali. Il widget mostra un avviso se utilizzi il codice di incorporamento non modificato senza configurare l'autenticazione. Per informazioni dettagliate sulle opzioni e sulla configurazione, consulta la sezione Configurare l'autenticazione.
Incorporare il widget nel tuo sito web
Per aggiungere il widget al tuo sito web, devi aggiungere i seguenti snippet HTML.
Lo snippet seguente include uno script necessario per reCAPTCHA. Se reCAPTCHA viene utilizzato nel widget, nella parte inferiore del widget viene visualizzato un avviso che indica che il sito è protetto da Google e che si applicano le Norme sulla privacy di Google e i Termini di servizio. Puoi anche nascondere il badge reCAPTCHA.
Per supportare i layout adattabili, puoi anche caricare
chat-messenger-layout.css.
Il file chat-messenger-layout.css viene utilizzato per lo stile reattivo
e per far scorrere il messenger dentro e fuori dalla visualizzazione
quando si utilizza render-mode="slide-in" o render-mode="slide-over".
Poiché applica lo stile a body,
potrebbe influire sul tuo sito web.
Pertanto, puoi scegliere di non caricare chat-messenger-layout.css
oppure puoi copiarne i contenuti e integrarli nel tuo CSS.
Per un rendimento ottimale e per garantire layout adattabili, utilizza questi posizionamenti:
Nella sezione <header>:
<header>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script defer src="https://www.gstatic.com/ces-console/fast/chat-messenger/prod/v1/chat-messenger.js"></script>
<!-- Chat Messenger CSS -->
<link rel="stylesheet" href="https://www.gstatic.com/ces-console/fast/chat-messenger/prod/v1/themes/chat-messenger-default.css">
<!-- Optional responsive styling -->
<!-- <link rel="stylesheet" href="https://www.gstatic.com/ces-console/fast/chat-messenger/prod/v1/themes/chat-messenger-layout.css"> -->
<!-- CSS customization -->
<style>
chat-messenger {
z-index: 999;
position: fixed;
<!-- Your CSS customization goes here if needed -->
}
</style>
</header>
Nella sezione <body>:
<body>
<!-- Your website's main content goes here -->
<script>
window.addEventListener("chat-messenger-loaded", () => {
chatSdk.registerContext(
chatSdk.prebuilts.ces.createContext({
deploymentName: "projects/YOUR_PROJECT_ID/locations/YOUR_REGION/apps/YOUR_APP_ID/deployments/YOUR_DEPLOYMENT_ID",
tokenBroker: {
enableTokenBroker: true,
// If you enabled reCAPTCHA for the token broker, set enableRecaptcha to true.
// enableRecaptcha: true,
},
// Automatically prompt the agent to start the conversation with a greeting.
enableWelcomeEvent: true,
}),
);
});
</script>
<!-- Messenger component -->
<chat-messenger
language-code="en"
max-query-length="-1">
<chat-messenger-chat-bubble
chat-title="${your-chat-title}">
</chat-messenger-chat-bubble>
</chat-messenger>
<!-- Page content continues -->
</body>
Avviare automaticamente la conversazione
Per impostazione predefinita, il widget di chat attende che l'utente invii il primo messaggio. Per chiedere all'agente di avviare automaticamente la conversazione con un saluto, imposta enableWelcomeEvent: true nella funzione chatSdk.prebuilts.ces.createContext.
Se questa opzione è abilitata, il widget invia automaticamente un evento welcome all'agente quando viene inizializzata la sessione di chat. L'agente risponde a questo evento con il saluto configurato.
Considerazioni sulla sicurezza
Quando incorpori il widget come elemento personalizzato
(<chat-messenger>)
direttamente nel tuo sito web,
il widget viene eseguito in un
DOM ombra
nella pagina host.
Per impostazione predefinita, non applica il sandboxing rigido (ad esempio un iframe).
Poiché il widget condivide l'origine della finestra con l'applicazione:
- Accesso all'archiviazione condivisa:tutti gli script in esecuzione all'interno del componente personalizzato del widget
hanno accesso a
window.sessionStorageewindow.localStoragedella pagina host. Sono inclusi token di autenticazione o dati sensibili della sessione memorizzati dal widget stesso. - Cross-Site Scripting (XSS): se il codice del componente personalizzato o i payload di contenuti avanzati contengono input non sanificati, possono essere sfruttati per eseguire JavaScript arbitrario nel contesto dell'applicazione principale.
Per mantenere la sicurezza della tua applicazione e dei dati dei tuoi utenti, devi:
- Sanitizza il codice personalizzato:assicurati che tutto il codice JavaScript e HTML personalizzato utilizzato nei componenti o nei payload personalizzati sia rigorosamente sanitizzato.
- Convalida input:Considera tutti i dati passati al widget da origini esterne (incluse le risposte dell'agente) come non attendibili.
- Isolamento dell'handle:se i tuoi requisiti di sicurezza impongono un isolamento rigoroso tra il widget di chat e i dati della tua applicazione, devi implementare il tuo sandboxing (ad esempio, racchiudendo il componente del widget in un contenitore che controlli e isoli).
Configura il trasferimento all'agente umano
Prima di configurare il widget, assicurati che le risorse necessarie siano create e che il deployment del proxy Web Chat sia completato.
- Configura il numero di riassegnazione.
- Crea una risorsa
PhoneNumber
per il tuo progetto.
- Utilizza un profilo conversazione valido configurato per l'applicazione dell'agente.
- Associa il profilo conversazione al numero di telefono per consentire al sistema di gestire la riassegnazione a un operatore umano.
- Segui le istruzioni per configurare WebChat Proxy.
- Crea una risorsa
PhoneNumber
per il tuo progetto.
Configurazione client webchat:
Imposta l'attributo da WebChat Proxy per attivare la funzionalità di trasferimento live. Esempio di snippet di codice:
<chat-messenger service='{"name":"ces","deployment-id":"projects/YOUR_PROJECT_ID/locations/YOUR_REGION/apps/YOUR_APP_ID/deployments/YOUR_DEPLOYMENT_ID"}' liveHandoff="true" escalationNumber="projects/YOUR_PROJECT_ID/locations/global/phoneNumbers/YOUR_PHONE_NUMBER_ID" url-allowlist="*" > </chat-messenger>
Personalizzazione HTML
Puoi personalizzare vari aspetti dell'aspetto e del comportamento della finestra di dialogo della chat.
L'elemento HTML chat-messenger e chat-messenger-container
prevede i seguenti attributi:
| Attributo | Attribuzione dei componenti | Valore (facoltativo) | Effetto |
|---|---|---|---|
| servizio | chat-messenger | Il nome del servizio richiesto per il servizio di backend connesso. | |
| url-allowlist | chat-messenger | * | (elenco di domini delle immagini separati da virgole |
| logging-level | chat-messenger | DEBUG | <OMIT> |
| enable-audio-input-only | chat-messenger-container | Modalità Solo voce | |
| start-with-recording | chat-messenger-container | Richiede la modalità Solo voce. La modalità solo voce viene avviata nel momento in cui viene visualizzato il contenitore chat-messenger. | |
| enable-audio-input | chat-messenger-container | Aggiunge un pulsante per consentire la chat multimodale | |
| enable-file-upload | chat-messenger-container | Consente i caricamenti di immagini | |
| bot-writing-image | chat-messenger-container | string | URL dell'immagine visualizzata durante la "riflessione" del bot |
| chat-title-icon | chat-messenger-container | string | URL dell'immagine visualizzata nella parte superiore della chat (immagine di brand) |
| chat-title | chat-messenger-container | string | Testo del titolo della chat |
| render-mode | chat-messenger | stringa ("slide-in" o "slide-over") | La modalità di rendering della finestra di dialogo della chat rispetto al resto della pagina. Le opzioni sono "slide-over" o "slide-in". Se non specificato, il posizionamento può essere specificato dal cliente. Gli stili sono necessari per supportare la modalità di rendering. chat-messenger-layout.css può essere utilizzato come base di riferimento. |
Personalizzazione CSS
La personalizzazione dell'aspetto del widget viene gestita tramite un sistema di token CSS. Modificando questi token, puoi assicurarti che l'interfaccia di chat sia coerente con il tuo brand mantenendo l'integrità del layout e l'accessibilità.
Token colore
Questi token definiscono la tavolozza dei colori per le superfici dei widget, gli elementi interattivi, il testo e gli stati.
| Proprietà | Descrizione | Tema chiaro predefinito | Tema scuro predefinito |
|---|---|---|---|
| Container / Tipi di inventario | |||
| --chat-messenger-color--surface | Il colore di sfondo principale per il corpo della chat e l'area del piè di pagina. | #F8FAFD | #1B1B1B |
| --chat-messenger-color--surface-container | Il colore di sfondo dei contenitori dei widget (ad esempio schede prodotto e caroselli) nidificati all'interno della chat. | #FFFFFF | #131314 |
| --chat-messenger-color--surface-container-high | Uno sfondo con enfasi elevata per gli elementi all'interno dei widget (ad esempio, i campi di input) | #F0F4F9 | #1E1F20 |
| Brand / Accento | |||
| --chat-messenger-color--primary | Colore principale del brand utilizzato per i riempimenti con enfasi elevata e i pulsanti principali. | #303030 | #E3E3E3 |
| --chat-messenger-color--primary-container | Colore di sfondo in evidenza per i componenti chiave, come le bolle dei messaggi degli utenti. | #E9EEF6 | #282A2C |
| --chat-messenger-color--secondary | Colore per gli elementi interattivi secondari, come il pulsante "Invia" o i pulsanti tonali. | #DDE3EA | #333537 |
| Testo e icone | |||
| --chat-messenger-color--on-surface | Colore principale per testo e icone visualizzati su sfondi di superficie standard. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-surface-variant | Colore con enfasi minore per il testo secondario e le icone decorative. | #444746 | #C4C7C5 |
| --chat-messenger-color--on-primary | Colore per testo e icone posizionati sopra gli sfondi principali del brand. | #F2F2F2 | #303030 |
| --chat-messenger-color--on-primary-container | Colore per testo e icone posizionati sopra gli sfondi del contenitore principale. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-secondary | Colore per testo e icone posizionati sopra gli sfondi secondari del brand. | #444746 | #C4C7C5 |
| Stati | |||
| --chat-messenger-color--state-layer-on-surface | La sovrapposizione traslucida utilizzata per indicare gli stati di passaggio del mouse o di selezione sulle superfici standard. Il riempimento per i componenti disattivati. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-layer-on-primary | La sovrapposizione traslucida utilizzata per gli stati di interazione sopra gli elementi colorati con il colore principale. | #FFFFFF 8% | #062E6F 8% |
| --chat-messenger-color--state-layer-on-secondary | L'overlay traslucido utilizzato per gli stati di interazione sopra gli elementi di colore secondario. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-on-surface-mute | Colore per testo e icone disattivati. | #444746 (38%) | #C4C7C5 (38%) |
| Utilità | |||
| --chat-messenger-color--outline | Colore per bordi, divisori e contorni decorativi generali. | #C4C7C5 | #444746 |
| --chat-messenger-color--outline-variant | Colore per i bordi sottili (ad esempio, il frame esterno dei widget) | #747775 al 16% | #8E918F al 16% |
| --chat-messenger-color--outline-active | Colore del bordo per i campi di input e i menu a discesa quando sono selezionati o attivi. | #747775 | #8E918F |
| --chat-messenger-color--error | Colore che attira l'attenzione a contrasto con la superficie per riempimenti, icone e testo, a indicare urgenza. | #B3261E | #F2B8B5 |
| --chat-messenger-color--error-container | Colore di riempimento dello sfondo per i banner di errore o i contenitori di avvisi interattivi. | #F9DEDC | #8C1D18 |
| --chat-messenger-color--on-error-container | Testo e icone posizionati sullo sfondo del contenitore degli errori. | #8C1D18 | #F9DEDC |
| --chat-messenger-color--link | Colore utilizzato per i link ipertestuali cliccabili all'interno di messaggi o descrizioni. | #0B57D0 | #A8C7FA |
Token di forma ed elevazione
Questi token controllano il raggio dell'angolo e la profondità visiva (ombre) dei componenti della chat.
| Proprietà | Descrizione | Predefinito |
|---|---|---|
| --chat-messenger-shape--corner-value-small | Raggio dell'angolo per i piccoli elementi nidificati all'interno dei widget (ad esempio, le miniature delle immagini prodotto) | 8 px |
| --chat-messenger-shape--corner-value-medium | Raggio dell'angolo per gli elementi nidificati all'interno dei widget (ad esempio, campi di input, immagini) | 16 px |
| --chat-messenger-shape--corner-value-large | Raggio d'angolo per i contenitori nidificati all'interno dei widget (ad esempio, schede del carosello, schede delle azioni rapide) | 20 px |
| --chat-messenger-shape--corner-value-extra-large | Raggio dell'angolo per la finestra di chat principale e i contenitori dei widget. | 28 px |
| --chat-messenger-shape--corner-fully-rounded | Utilizzato per pulsanti ed elementi interattivi a forma di pillola per garantire un'estremità completamente circolare. | 100px |
| --chat-messenger-elevation | L'ombreggiatura applicata agli elementi mobili e al componente principale della chat. | 0 1px 2px 0 rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15) |
Token di tipografia
Questi token definiscono il carattere e la scala specifica (dimensione, spessore, spaziatura) utilizzati nell'interfaccia.
| Proprietà | Uso previsto | Predefinito |
|---|---|---|
| --chat-messenger-font-family | Famiglia di caratteri principale | Google Sans |
| Titolo grande | Intestazioni in evidenza | |
| --chat-messenger-typescale--title-large-font-size | 18 px | |
| --chat-messenger-typescale--title-large-font-weight | 400 | |
| --chat-messenger-typescale--title-large-line-height | 24 px | |
| --chat-messenger-typescale--title-large-letter-spacing | 0 | |
| Title medium | Intestazioni di sezione all'interno dei widget. | |
| --chat-messenger-typescale--title-medium-font-size | 16 px | |
| --chat-messenger-typescale--title-medium-font-weight | 500 | |
| --chat-messenger-typescale--title-medium-line-height | 24 px | |
| --chat-messenger-typescale--title-medium-letter-spacing | 0 | |
| Titolo piccolo | ||
| --chat-messenger-typescale--title-small-font-size | Sottotitoli o titoli all'interno di schede più piccole. | 14px |
| --chat-messenger-typescale--title-small-font-weight | 500 | |
| --chat-messenger-typescale--title-small-line-height | 20 px | |
| --chat-messenger-typescale--title-small-letter-spacing | 0 | |
| Body large | Descrizioni grandi. | |
| --chat-messenger-typescale--body-large-font-size | 16 px | |
| --chat-messenger-typescale--body-large-font-weight | 400 | |
| --chat-messenger-typescale--body-large-line-height | 24 px | |
| --chat-messenger-typescale--body-large-letter-spacing | 0 | |
| Body medium | Standard UI text | |
| --chat-messenger-typescale--body-medium-font-size | 14px | |
| --chat-messenger-typescale--body-medium-font-weight | 400 | |
| --chat-messenger-typescale--body-medium-line-height | 20 px | |
| --chat-messenger-typescale--body-medium-letter-spacing | 0 | |
| Corpo piccolo | Metadati e descrizioni secondari. | |
| --chat-messenger-typescale--body-small-font-size | 12 px | |
| --chat-messenger-typescale--body-small-font-weight | 400 | |
| --chat-messenger-typescale--body-small-line-height | 16 px | |
| --chat-messenger-typescale--body-small-letter-spacing | 0,1 | |
| Etichetta grande | Testo all'interno dei pulsanti e dei chip di azione principale. | |
| --chat-messenger-typescale--label-large-font-size | 14px | |
| --chat-messenger-typescale--label-large-font-weight | 500 | |
| --chat-messenger-typescale--label-large-line-height | 20 px | |
| --chat-messenger-typescale--label-large-letter-spacing | 0 | |
| Supporto dell'etichetta | Testo del pulsante secondario ed etichette dei campi | |
| --chat-messenger-typescale--label-medium-font-size | 12 px | |
| --chat-messenger-typescale--label-medium-font-weight | 500 | |
| --chat-messenger-typescale--label-medium-line-height | 16 px | |
| --chat-messenger-typescale--label-medium-letter-spacing | 0,1 | |
| Etichetta piccola | Micro-etichette e testo del badge | |
| --chat-messenger-typescale--label-small-font-size | 11px | |
| --chat-messenger-typescale--label-small-font-weight | 500 | |
| --chat-messenger-typescale--label-small-line-height | 16 px | |
| --chat-messenger-typescale--label-small-letter-spacing | 0,1 |
Token di spaziatura
Questi token mantengono una densità di layout coerente, definendo margini, spaziatura interna e spazi tra gli elementi.
| Proprietà | Predefinito |
|---|---|
| --chat-messenger-spacing--half | 4 px |
| --chat-messenger-spacing--one | 8 px |
| --chat-messenger-spacing--one-and-half | 12 px |
| --chat-messenger-spacing--two | 16 px |
| --chat-messenger-spacing--two-and-half | 20 px |
| --chat-messenger-spacing--three | 24 px |
| --chat-messenger-spacing--three-and-half | 28 px |
| --chat-messenger-spacing--four | 32 px |
Eventi JavaScript
Messenger attiva una serie di eventi per i quali puoi creare
listener di eventi.
La destinazione evento per questi eventi è l'elemento chat-messenger.
Per aggiungere un listener di eventi per l'elemento chat-messenger,
aggiungi il seguente codice JavaScript,
dove event-type è uno dei nomi degli eventi descritti in questa sezione
const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.addEventListener('event-type', function (event) {
// Handle event
...
});
Sono supportati i seguenti tipi di eventi:
chat-messenger-loaded: Questo evento viene attivato quando l'elementochat-messengerè completamente caricato e inizializzato.chat-messenger-closechat-messenger-error: Questo evento si verifica quando l'agente CES invia un codice di stato di errore. La struttura dell'evento è simile alla seguenteeventId= `chat-messenger-error-v2` event.details { message: string; code: number | undefined; status: number | string; }df-update-cart-count: Questo evento si verifica quando "Aggiungi al carrello", "Modifica quantità articolo", "Elimina articolo" si verificano negli elementi di contenuti avanzatiproduct_carousel,product_detail,product_comparison. La struttura dell'evento è simile alla seguente{ "detail": { "count": <cart_item_count>, } }
Funzioni JavaScript
L'elemento chat-messenger fornisce
funzioni
che puoi chiamare per influire sul suo comportamento.
renderCustomEvent
Questa funzione esegue il rendering di un messaggio di testo, come se provenisse dall'applicazione dell'agente come risposta di testo.
Ad esempio:
const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.renderCustomText('Custom text');
renderCustomCard
Questa funzione esegue il rendering di una scheda personalizzata, come se provenisse dall'applicazione dell'agente come messaggio di risposta avanzata. Il formato della risposta del payload personalizzato è definito nella sezione Messaggi di risposta avanzata.
Ad esempio:
const chatMessenger = document.querySelector('chat-messenger');
const payload = [
{
"type": "info",
"title": "Info item title",
"subtitle": "Info item subtitle",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"actionLink": "https://example.com"
}];
chatMessenger.renderCustomCard(payload);
Configura l'autenticazione
Tutte le richieste API effettuate dal widget web ai servizi di backend di Google devono essere autenticate. Ciò si ottiene utilizzando un token di accesso OAuth 2.0 di breve durata.
L'identità associata a questo token, che si tratti di un utente finale o di un account di servizio, deve disporre delle autorizzazioni IAM necessarie per interagire con l'agente.
Le sottosezioni rimanenti descrivono i modi in cui puoi configurare l'autenticazione.
Configura un broker di token
Un broker di token è un servizio web in esecuzione nel tuo progetto Google Cloud che genera un token di accesso per conto di unaccount di serviziot di tua proprietà. Il widget web può chiamare automaticamente l'URL del tuo token broker all'inizio di una conversazione per ottenere un nuovo token da utilizzare quando comunichi con l'API CX Agent Studio.
Puoi configurare un broker di token in due modi: ospitato da Google o self-hosted.
ospitato da Google
Utilizza il token broker fornito da Google per consentire l'accesso pubblico al widget di chat:
- Quando crei la configurazione del deployment e del widget, abilita l'accesso pubblico e, se vuoi, abilita i controlli di origine e reCAPTCHA (consigliato per impedire lo spoofing e gli abusi).
- Il widget di chat richiederà un token di ambito sessione al broker di token fornito da Google e lo utilizzerà per le sessioni di chat.
Self-hosted
Per configurare un broker di token autogestito:
- Crea un account di servizio nel tuo progetto e concedigli il ruolo Cliente Customer Engagement Suite.
- Esegui il deployment di una funzione Cloud Run Functions con il codice campione del broker di token che forniamo.
Per istruzioni dettagliate passo passo, consulta il repository open source.
Configurare OAuth2
Un client OAuth2 consente al widget web di avviare un flusso di autenticazione per l'utente finale. In genere, questo significa che viene aperta una finestra di dialogo, in cui l'utente accede al proprio Account Google (o ad altri provider) e il widget web riceve un token per operare per conto dell'utente.
Scegli questa opzione per richiedere agli utenti finali di accedere prima di utilizzare l'agente, dove le credenziali utente vengono utilizzate per l'accesso all'applicazione agente.
Ecco i passaggi principali da seguire:
- Nella console Google Cloud , vai a Google Auth Platform e seleziona Client.
- Fai clic su Crea cliente.
- Seleziona Applicazione web come tipo di cliente.
- Inserisci un nome per il nuovo cliente.
- Aggiungi l'URL del tuo sito web sia a Origini JavaScript autorizzate che a URI di reindirizzamento autorizzati.
- Fai clic su Crea e attendi 5 minuti prima di continuare.
Dopo aver seguito i passaggi, riceverai un ID client nel formato:
123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
Fornisci questo valore
nell'attributo oauth-client-id del componente web chat-messenger.
Crea la tua API di autenticazione
Crea la tua API per gestire l'autenticazione e l'autorizzazione
dell'utente finale che restituisce un token di accesso Google o un JWT firmato
che ha l'autorizzazione per chiamare runSession nella tua app.
Per informazioni sull'utilizzo dell'API CX Agent Studio, consulta Accesso API.