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 in modalità di dialogo espansa per una conversazione mirata.
Limitazioni
Al momento, le risposte con contenuti avanzati supportano solo l'inglese.
Configura il widget web
Per incorporare il widget nel tuo sito web:
- Fai clic su Esegui il deployment nella parte superiore di Agent Builder.
- 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 deployment 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 maggiori dettagli sulle opzioni e sulla configurazione, consulta la sezione Configura l'autenticazione.
Incorpora il widget nel tuo sito web
Per aggiungere il widget al tuo sito web, devi aggiungere i seguenti snippet HTML.
Lo snippet riportato di seguito include uno script obbligatorio 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 di Google. 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 di adattabilità e per far scorrere il messenger dentro e fuori dalla visualizzazione quando utilizzi 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 o di copiarne i contenuti e integrarli nel tuo CSS.
Per un rendimento ottimale e per garantire layout adattabili, segui questi posizionamenti:
Nella sezione <header>:
<header>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script defer src="https://www.gstatic.com/chat-messenger/sdk/prod/latest/chat-messenger.js"></script>
<!-- Chat Messenger CSS -->
<link rel="stylesheet" href="https://www.gstatic.com/chat-messenger/sdk/prod/latest/themes/chat-messenger-default.css">
<!-- Optional responsive styling -->
<!-- <link rel="stylesheet" href="https://www.gstatic.com/chat-messenger/sdk/prod/latest/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>
Avvia 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.
Quando questa opzione è attiva, 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 shadow DOM nella pagina host.
Per impostazione predefinita, non applica un sandboxing rigoroso (come un iframe).
Poiché il widget condivide l'origine della finestra con la tua applicazione:
- Accesso allo spazio di archiviazione condiviso:
tutti gli script in esecuzione all'interno del componente personalizzato del widget
hanno accesso a
window.sessionStorageewindow.localStoragedella pagina host. Sono inclusi i token di autenticazione o i dati sensibili della sessione archiviati dal widget stesso. - Cross-Site Scripting (XSS): se il codice del componente personalizzato o i payload dei contenuti avanzati contengono input non sanitizzati, 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 gli input: tratta tutti i dati passati al widget da fonti esterne (incluse le risposte dell'agente) come non attendibili.
- Gestisci l'isolamento: 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, inserendo il componente del widget in un container che controlli e isoli).
Configura l'handoff ad agenti umani
Prima di configurare il widget, assicurati che siano state create le risorse necessarie e che il deployment del proxy WebChat sia stato completato.
- Configura il numero di escalation.
- Crea una risorsa PhoneNumber per il tuo progetto.
- Utilizza un profilo di conversazione valido configurato per l'applicazione dell'agente.
- Associa il profilo di conversazione al numero di telefono per consentire al sistema di gestire l'escalation umana.
- Segui le istruzioni per configurare WebChat Proxy.
- Crea una risorsa PhoneNumber per il tuo progetto.
Configurazione del client di chat web:
Imposta l'attributo da WebChat Proxy per attivare la funzionalità di passaggio ad agenti umani. 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 ha 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 separato da virgole di domini di immagini |
| 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 si avvia nel momento in cui viene eseguito il rendering del container chat-messenger-container | |
| enable-audio-input | chat-messenger-container | Aggiunge un pulsante per consentire la chat multimodale | |
| enable-file-upload | chat-messenger-container | Abilita i caricamenti di immagini | |
| bot-writing-image | chat-messenger-container | string | URL dell'immagine visualizzata durante l'elaborazione 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 client. Gli stili sono obbligatori 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 della chat sia coerente con il tuo brand, mantenendo al contempo l'integrità e l'accessibilità del layout.
Token di 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 |
|---|---|---|---|
| Contenitori / superfici | |||
| --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 ad alta enfasi per gli elementi all'interno dei widget (ad esempio i campi di immissione) | #F0F4F9 | #1E1F20 |
| Brand / Decorazione | |||
| --chat-messenger-color--primary | Colore principale del brand utilizzato per i riempimenti ad alta enfasi e i pulsanti principali. | #303030 | #E3E3E3 |
| --chat-messenger-color--primary-container | Colore di sfondo in evidenza per i componenti chiave, come i fumetti dei messaggi dell'utente. | #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 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 il testo e le icone posizionati sopra gli sfondi principali del brand. | #F2F2F2 | #303030 |
| --chat-messenger-color--on-primary-container | Colore per il testo e le icone posizionati sopra gli sfondi del contenitore principale. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-secondary | Colore per il testo e le icone posizionati sopra gli sfondi del brand secondari. | #444746 | #C4C7C5 |
| Stati | |||
| --chat-messenger-color--state-layer-on-surface | L'overlay traslucido utilizzato per indicare gli stati di passaggio del mouse o di selezione su superfici standard. Il riempimento per i componenti disattivati. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-layer-on-primary | L'overlay traslucido utilizzato per gli stati di interazione sopra gli elementi di colore primario. | #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 generali, divisori e contorni decorativi. | #C4C7C5 | #444746 |
| --chat-messenger-color--outline-variant | Colore per i bordi sottili (ad esempio, la cornice esterna dei widget) | #747775 al 16% | #8E918F al 16% |
| --chat-messenger-color--outline-active | Colore del bordo per i campi di immissione e i menu a discesa quando sono selezionati o attivi. | #747775 | #8E918F |
| --chat-messenger-color--error | Colore accattivante rispetto alla 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 container di errore. | #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 degli angoli e la profondità visiva (ombre) dei componenti della chat.
| Proprietà | Descrizione | Predefinito |
|---|---|---|
| --chat-messenger-shape--corner-value-small | Raggio dell'angolo per piccoli elementi nidificati all'interno dei widget (ad esempio, miniature delle immagini dei prodotti) | 8 px |
| --chat-messenger-shape--corner-value-medium | Raggio dell'angolo per gli elementi nidificati all'interno dei widget (ad esempio campi di immissione, immagini) | 16 px |
| --chat-messenger-shape--corner-value-large | Raggio dell'angolo per i contenitori nidificati all'interno dei widget (ad esempio, schede carosello, schede di azioni rapide) | 20 px |
| --chat-messenger-shape--corner-value-extra-large | Raggio dell'angolo per la finestra di chat principale e i container 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'ombra della casella 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 tipografico e la scala specifica (dimensioni, 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 | |
| Title small | ||
| --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 | |
| Corpo grande | 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 | Testo UI standard | |
| --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 di pulsanti e chip di azione principali. | |
| --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 | |
| Etichetta media | Testo dei pulsanti secondari 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 | Microetichette e testo dei 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.
Il target di 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 evento 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 seguente:eventId= `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 la quantità dell'articolo", "Elimina articolo" si verificano negli elementi dei 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 influenzarne il comportamento.
renderCustomText
Questa funzione visualizza 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. A questo scopo, viene utilizzato 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 che viene eseguito nel tuo progetto Google Cloud e 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 broker di token all'inizio di una conversazione per ottenere un nuovo token da utilizzare durante la comunicazione 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 broker di token 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, facoltativamente, i controlli dell'origine e di reCAPTCHA (consigliati per prevenire lo spoofing e l'abuso).
- Il widget di chat richiederà un token con ambito di sessione dal broker di token fornito da Google e lo utilizzerà per le sessioni di chat.
Self-hosted
Per configurare un broker di token in hosting autonomo, segui questi passaggi:
- 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.
Consulta le istruzioni passo passo dettagliate nel repository open source.
Configura 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 dell'agente.
Ecco i passaggi principali da seguire:
- Nella console Google Cloud , vai alla piattaforma di autenticazione di Google e seleziona Client.
- Fai clic su Crea client.
- Seleziona Applicazione web come tipo di client.
- Inserisci un nome per il nuovo client.
- Aggiungi l'URL del tuo sito web sia alle origini JavaScript autorizzate sia agli 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 per chiamare runSession nella tua app.
Per informazioni sull'utilizzo dell'API CX Agent Studio, consulta Accesso all'API.