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 le 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 a colori 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 al codice 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 nel widget viene utilizzato reCAPTCHA, nella parte inferiore del widget verrà 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,
},
}),
);
});
</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>
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 una sandbox rigorosa (come un iframe).
Poiché il widget condivide l'origine della finestra con la tua 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 fonti 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 WebChat sia completato.
- Configura il numero di riassegnazione.
- Crea una risorsa
PhoneNumber
per il tuo progetto.
- Utilizza un profilo conversazione valido configurato per l'applicazione agente.
- Associa il profilo conversazionale a PhoneNumber 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 inizia 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 del 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 client. 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, ad esempio il pulsante "Invia" o i pulsanti tonali. | #DDE3EA | #333537 |
| Testo e icone | |||
| --chat-messenger-color--on-surface | Colore principale per il testo e le 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 di 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 colorati secondari. | #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, che indica 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 e 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 dell'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 in tutta l'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 | |
| Mezzo del titolo | 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 | |
| Label small | 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ò viene ottenuto 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.
Configurare 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 un account di servizio 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.
In hosting su Google
Utilizza il token broker fornito da Google per consentire l'accesso pubblico al widget di chat:
- Quando crei la configurazione della distribuzione 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 dal broker di token fornito da Google e lo utilizzerà per le sessioni di chat.
Self-hosted
Per configurare un broker di token self-hosted:
- Crea un account di servizio nel tuo progetto e concedigli il ruolo Client 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, si apre 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 accedere 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
con l'autorizzazione a chiamare runSession nella tua app.
Per informazioni sull'utilizzo dell'API CX Agent Studio, consulta la sezione Accesso API.