Le widget Web est un client Web que vous pouvez utiliser dans vos applications Web et mobiles pour permettre à vos utilisateurs d'interagir avec votre application d'agent par chat ou par voix. Ce guide fournit une présentation et des instructions de configuration.
Lorsqu'il est ouvert, le widget peut s'afficher sous la forme d'une fenêtre de dialogue flottante dans l'angle inférieur droit, sous la forme d'un panneau à côté de votre contenu principal ou en mode dialogue étendu pour une conversation ciblée.
Limites
Pour le moment, les réponses de contenu enrichi ne sont disponibles qu'en anglais.
Configurer le widget Web
Pour intégrer le widget à votre site Web :
- Cliquez sur Deploy (Déployer) en haut de l'outil de création d'agents.
- Cliquez sur Créer une chaîne ou Nouvelle chaîne.
- Sélectionnez le type de canal Widget Web.
- Saisissez un nom pour votre chaîne.
- Sélectionnez ou créez une version de l'application d'agent.
- Configurez d'autres préférences, comme le thème de couleurs et le type d'expérience (chat, appel ou mixte).
- Cliquez sur Créer un canal pour générer votre code de déploiement.
- Ajoutez le code de déploiement au code HTML de votre site Web.
- Configurez l'authentification pour vos utilisateurs finaux. Le widget affiche un avertissement si vous utilisez le code d'intégration non modifié sans configurer l'authentification. Pour en savoir plus sur les options et la configuration, consultez la section Configurer l'authentification.
Intégrer le widget à votre site Web
Pour ajouter le widget à votre site Web, vous devez ajouter les extraits HTML suivants.
L'extrait de code ci-dessous inclut un script requis pour reCAPTCHA. Si reCAPTCHA est utilisé dans le widget, un avis s'affiche en bas du widget pour indiquer que le site est protégé par Google et que les Règles de confidentialité et les Conditions d'utilisation de Google s'appliquent. Vous pouvez également masquer le badge reCAPTCHA.
Pour prendre en charge les mises en page responsives, vous pouvez également charger chat-messenger-layout.css (facultatif).
Le fichier chat-messenger-layout.css est utilisé pour le style réactif et pour faire glisser le Messenger dans et hors de la vue lors de l'utilisation de render-mode="slide-in" ou render-mode="slide-over".
Comme il met en forme body, il peut affecter votre site Web.
Vous pouvez donc choisir de ne pas charger chat-messenger-layout.css ou de copier son contenu et de l'intégrer à votre propre CSS.
Pour optimiser les performances et garantir des mises en page responsives, utilisez les emplacements suivants :
Dans la section <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>
Dans la section <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>
Démarrer automatiquement la conversation
Par défaut, le widget de chat attend que l'utilisateur envoie le premier message. Pour inviter l'agent à démarrer automatiquement la conversation par un message d'accueil, définissez enableWelcomeEvent: true dans la fonction chatSdk.prebuilts.ces.createContext.
Lorsque cette option est activée, le widget envoie automatiquement un événement welcome à l'agent lorsque la session de chat est initialisée. L'agent répond à cet événement avec le message d'accueil configuré.
Points à noter concernant la sécurité
Lorsque vous intégrez le widget en tant qu'élément personnalisé (<chat-messenger>) directement sur votre site Web, il s'exécute dans un shadow DOM sur votre page hôte.
Par défaut, il n'applique pas de sandbox stricte (comme un iframe).
En effet, le widget partage l'origine de la fenêtre avec votre application :
- Accès au stockage partagé : tous les scripts exécutés dans le composant personnalisé du widget ont accès à
window.sessionStorageetwindow.localStoragede la page hôte. Cela inclut les jetons d'authentification ou les données de session sensibles stockées par le widget lui-même. - Script intersites (XSS) : si votre code de composant personnalisé ou vos charges utiles de contenu enrichi contiennent des entrées non assainies, elles peuvent être exploitées pour exécuter du code JavaScript arbitraire dans le contexte de votre application principale.
Pour assurer la sécurité de votre application et des données de vos utilisateurs, vous devez :
- Nettoyer le code personnalisé : assurez-vous que tout le code JavaScript et HTML personnalisé utilisé dans les composants ou les charges utiles personnalisés est rigoureusement nettoyé.
- Validez les entrées : considérez comme non fiables toutes les données transmises au widget à partir de sources externes (y compris les réponses de l'agent).
- Isolation des handles : si vos exigences de sécurité imposent une isolation stricte entre le widget de chat et les données de votre application, vous devez implémenter votre propre bac à sable (par exemple, en encapsulant le composant du widget dans un conteneur que vous contrôlez et isolez).
Configurer le transfert à un agent humain
Avant de configurer le widget, assurez-vous que les ressources nécessaires sont créées et que le déploiement du proxy WebChat est terminé.
- Configurez le numéro de téléphone pour les escalades.
- Créez une ressource PhoneNumber pour votre projet.
- Utilisez un profil de conversation valide configuré pour l'application d'agent.
- Associez le profil de conversation au numéro de téléphone pour permettre au système de gérer l'escalade humaine.
- Suivez les instructions pour configurer WebChat Proxy.
- Créez une ressource PhoneNumber pour votre projet.
Configuration du client Webchat :
Définissez l'attribut du proxy WebChat pour activer la fonctionnalité de transfert en direct. Exemple d'extrait de code :
<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>
Personnalisation HTML
Vous pouvez personnaliser divers aspects de l'affichage et du comportement de la boîte de dialogue de chat.
L'élément HTML chat-messenger et chat-messenger-container comporte les attributs suivants :
| Attribut | Attribution des composants | Valeur (facultative) | Effet |
|---|---|---|---|
| service | chat-messenger | Nom de service requis pour le service de backend connecté. | |
| url-allowlist | chat-messenger | * | (liste de domaines d'images séparés par une virgule |
| logging-level | chat-messenger | DÉBOGAGE | <OMIT> |
| enable-audio-input-only | chat-messenger-container | Mode voix uniquement | |
| start-with-recording | chat-messenger-container | Nécessite le mode Voix uniquement. Le mode vocal uniquement démarre dès que le conteneur de chat et de messagerie est affiché. | |
| enable-audio-input | chat-messenger-container | Ajoute un bouton pour autoriser le chat multimodal | |
| enable-file-upload | chat-messenger-container | Permet d'importer des images | |
| bot-writing-image | chat-messenger-container | string | URL de l'image affichée pendant que le bot "réfléchit" |
| chat-title-icon | chat-messenger-container | string | URL de l'image affichée en haut du chat (image de marque) |
| chat-title | chat-messenger-container | string | Texte du titre du chat |
| render-mode | chat-messenger | string ("slide-in" ou "slide-over") | Mode d'affichage de la boîte de dialogue de chat par rapport au reste de la page. Les options sont "slide-over" (superposition) ou "slide-in" (glissement). Si aucune valeur n'est spécifiée, le positionnement peut être spécifié par le client. Les styles sont nécessaires pour prendre en charge le mode d'affichage. chat-messenger-layout.css peut être utilisé comme référence. |
Personnalisation CSS
La personnalisation de l'apparence du widget est gérée par un système de jetons CSS. En modifiant ces jetons, vous pouvez vous assurer que l'interface de chat est cohérente avec votre marque tout en conservant l'intégrité de la mise en page et l'accessibilité.
Jetons de couleur
Ces jetons définissent la palette de couleurs pour les surfaces, les éléments interactifs, le texte et les états du widget.
| Propriété | Description | Thème clair par défaut | Thème sombre par défaut |
|---|---|---|---|
| Conteneurs / Surfaces | |||
| --chat-messenger-color--surface | Couleur d'arrière-plan principale pour le corps et le pied de page du chat. | #F8FAFD | #1B1B1B |
| --chat-messenger-color--surface-container | Couleur d'arrière-plan des conteneurs de widgets (par exemple, les fiches produit et les carrousels) imbriqués dans le chat. | #FFFFFF | #131314 |
| --chat-messenger-color--surface-container-high | Arrière-plan à forte emphase pour les éléments des widgets (par exemple, les champs de saisie) | #F0F4F9 | #1E1F20 |
| Marque / Accent | |||
| --chat-messenger-color--primary | Couleur principale de la marque utilisée pour les remplissages à forte intensité et les boutons principaux. | #303030 | #E3E3E3 |
| --chat-messenger-color--primary-container | Couleur d'arrière-plan distinctive pour les composants clés, comme les bulles de messages utilisateur. | #E9EEF6 | #282A2C |
| --chat-messenger-color--secondary | Couleur des éléments interactifs secondaires, tels que le bouton "Envoyer" ou les boutons tonaux. | #DDE3EA | #333537 |
| Texte et icônes | |||
| --chat-messenger-color--on-surface | Couleur principale du texte et des icônes affichés sur des arrière-plans de surface standards. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-surface-variant | Couleur à faible emphase pour le texte secondaire et les icônes décoratives. | #444746 | #C4C7C5 |
| --chat-messenger-color--on-primary | Couleur du texte et des icônes placés sur les arrière-plans de la marque principale. | #F2F2F2 | #303030 |
| --chat-messenger-color--on-primary-container | Couleur du texte et des icônes placés sur les arrière-plans des conteneurs principaux. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-secondary | Couleur du texte et des icônes placés sur les arrière-plans secondaires de la marque. | #444746 | #C4C7C5 |
| États | |||
| --chat-messenger-color--state-layer-on-surface | Calque translucide utilisé pour indiquer les états de survol ou de sélection sur les surfaces standards. Remplissage des composants désactivés. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-layer-on-primary | Calque translucide utilisé pour les états d'interaction sur les éléments de couleur primaire. | #FFFFFF 8% | #062E6F 8% |
| --chat-messenger-color--state-layer-on-secondary | Calque translucide utilisé pour les états d'interaction sur les éléments de couleur secondaire. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-on-surface-mute | Couleur du texte et des icônes désactivés. | #444746 (38%) | #C4C7C5 (38%) |
| Utilité | |||
| --chat-messenger-color--outline | Couleur des bordures générales, des séparateurs et des contours décoratifs. | #C4C7C5 | #444746 |
| --chat-messenger-color--outline-variant | Couleur des bordures subtiles (par exemple, le cadre extérieur des widgets) | #747775 à 16% | #8E918F à 16% |
| --chat-messenger-color--outline-active | Couleur de la bordure des champs de saisie et des menus déroulants lorsqu'ils sont sélectionnés ou actifs. | #747775 | #8E918F |
| --chat-messenger-color--error | Couleur accrocheuse sur la surface pour les remplissages, les icônes et le texte, indiquant l'urgence. | #B3261E | #F2B8B5 |
| --chat-messenger-color--error-container | Couleur de remplissage de l'arrière-plan des bannières d'erreur ou des conteneurs d'alertes interactives. | #F9DEDC | #8C1D18 |
| --chat-messenger-color--on-error-container | Texte et icônes placés sur l'arrière-plan du conteneur d'erreur. | #8C1D18 | #F9DEDC |
| --chat-messenger-color--link | Couleur utilisée pour les liens hypertexte cliquables dans les messages ou les descriptions. | #0B57D0 | #A8C7FA |
Jetons de forme et d'altitude
Ces jetons contrôlent le rayon d'angle et la profondeur visuelle (ombres) des composants de chat.
| Propriété | Description | Par défaut |
|---|---|---|
| --chat-messenger-shape--corner-value-small | Rayon d'angle pour les petits éléments imbriqués dans les widgets (par exemple, les miniatures d'images de produits) | 8 px |
| --chat-messenger-shape--corner-value-medium | Rayon d'angle pour les éléments imbriqués dans les widgets (par exemple, les champs de saisie et les images) | 16 px |
| --chat-messenger-shape--corner-value-large | Rayon d'angle pour les conteneurs imbriqués dans les widgets (par exemple, les cartes de carrousel, les cartes d'actions rapides) | 20 px |
| --chat-messenger-shape--corner-value-extra-large | Rayon d'angle pour la fenêtre de chat principale et les conteneurs de widgets. | 28 px |
| --chat-messenger-shape--corner-fully-rounded | Utilisé pour les boutons et les éléments interactifs en forme de pilule afin de garantir une extrémité entièrement circulaire. | 100 px |
| --chat-messenger-elevation | Ombre portée appliquée aux éléments flottants et au composant de chat principal. | 0 1px 2px 0 rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15) |
Jetons de typographie
Ces jetons définissent la typographie et l'échelle spécifique (taille, épaisseur, espacement) utilisées dans l'interface.
| Propriété | Utilisation prévue | Par défaut |
|---|---|---|
| --chat-messenger-font-family | Famille de polices principale | Google Sans |
| Titre grand | En-têtes bien visibles | |
| --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 | |
| Support du titre | Titres de sections dans les widgets. | |
| --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 | |
| Titre petit | ||
| --chat-messenger-typescale--title-small-font-size | Sous-titres ou titres dans les petites cartes. | 14 px |
| --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 | Descriptions longues. | |
| --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 | Texte standard de l'UI | |
| --chat-messenger-typescale--body-medium-font-size | 14 px | |
| --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 | |
| Corps petit | Métadonnées et descriptions secondaires. | |
| --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 | |
| Libellé grand | Texte dans les boutons et les chips d'action principale. | |
| --chat-messenger-typescale--label-large-font-size | 14 px | |
| --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 | |
| Libellé du support | Texte du bouton secondaire et libellés des champs | |
| --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 | |
| Libellé petit | Micro-libellés et texte du badge | |
| --chat-messenger-typescale--label-small-font-size | 11 px | |
| --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 |
Jetons d'espacement
Ces jetons maintiennent une densité de mise en page cohérente, en définissant les marges, les marges intérieures et les espaces entre les éléments.
| Propriété | Par défaut |
|---|---|
| --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 |
Événements JavaScript
Messenger déclenche divers événements pour lesquels vous pouvez créer des écouteurs d'événements.
La cible de ces événements est l'élément chat-messenger.
Pour ajouter un écouteur d'événements pour l'élément chat-messenger, ajoutez le code JavaScript suivant, où event-type est l'un des noms d'événement décrits dans cette section.
const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.addEventListener('event-type', function (event) {
// Handle event
...
});
Les types d'événements suivants sont acceptés :
chat-messenger-loaded: cet événement est déclenché lorsque l'élémentchat-messengerest entièrement chargé et initialisé.chat-messenger-closechat-messenger-error: cet événement se produit lorsque l'agent CES envoie un code d'état d'erreur. La structure de l'événement se présente comme suit :eventId= `chat-messenger-error-v2` event.details { message: string; code: number | undefined; status: number | string; }df-update-cart-count: Cet événement se produit lorsque les actions "Ajouter au panier", "Ajuster la quantité d'articles" et "Supprimer l'article" sont effectuées dans les éléments de contenu enrichiproduct_carousel,product_detailetproduct_comparison. La structure de l'événement se présente comme suit :{ "detail": { "count": <cart_item_count>, } }
Fonctions JavaScript
L'élément chat-messenger fournit des fonctions que vous pouvez appeler pour affecter son comportement.
renderCustomEvent
Cette fonction affiche un message texte, comme s'il provenait de l'application d'agent en tant que réponse textuelle.
Exemple :
const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.renderCustomText('Custom text');
renderCustomCard
Cette fonction affiche une fiche personnalisée, comme si elle provenait de l'application de l'agent en tant que message de réponse enrichi. Le format de la réponse de charge utile personnalisée est défini dans la section Messages de réponses enrichies.
Exemple :
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);
Configurer l'authentification
Toutes les requêtes d'API envoyées par le widget Web aux services de backend de Google doivent être authentifiées. Pour ce faire, un jeton d'accès OAuth 2.0 de courte durée est utilisé.
L'identité associée à ce jeton, qu'il s'agisse d'un utilisateur final ou d'un compte de service, doit disposer des autorisations IAM nécessaires pour interagir avec l'agent.
Les autres sous-sections décrivent les différentes façons de configurer l'authentification.
Configurer un agent de service de jetons
Un courtier de jetons est un service Web qui s'exécute dans votre projet Google Cloud et génère un jeton d'accès au nom d'un compte de service qui vous appartient. Le widget Web peut appeler automatiquement l'URL de votre service de jetons au début d'une conversation pour obtenir un nouveau jeton à utiliser lors de la communication avec l'API CX Agent Studio.
Vous pouvez configurer un courtier de jetons de deux manières : hébergé par Google ou auto-hébergé.
Hébergé par Google
Utilisez le broker de jetons fourni par Google pour autoriser l'accès public à votre widget de chat :
- Lorsque vous créez la configuration du déploiement et du widget, activez l'accès public, et éventuellement les vérifications de l'origine et de reCAPTCHA (recommandé pour éviter l'usurpation d'identité et l'utilisation abusive).
- Le widget de chat demandera un jeton de portée de session au courtier de jetons fourni par Google et l'utilisera pour les sessions de chat.
Auto-hébergé
Pour configurer un service de jetons auto-hébergé :
- Créez un compte de service dans votre projet et attribuez-lui le rôle Client Customer Engagement Suite.
- Déployez une fonction Cloud Run Functions avec l'exemple de code du service de jetons que nous fournissons.
Pour obtenir des instructions détaillées, consultez le dépôt Open Source.
Configurer OAuth2
Un client OAuth2 permet au widget Web de lancer un flux d'authentification pour l'utilisateur final. Cela signifie généralement qu'une boîte de dialogue s'ouvre, dans laquelle l'utilisateur se connecte à son compte Google (ou à d'autres fournisseurs), et que le widget Web reçoit un jeton pour agir en son nom.
Sélectionnez cette option pour obliger les utilisateurs finaux à se connecter avant d'utiliser l'agent. Les identifiants de l'utilisateur sont alors utilisés pour accéder à l'application de l'agent.
Voici les principales étapes à suivre :
- Dans la console Google Cloud , accédez à Google Auth Platform et sélectionnez "Clients".
- Cliquez sur Créer un client.
- Sélectionnez Application Web comme type de client.
- Saisissez un nom pour votre nouveau client.
- Ajoutez l'URL de votre site Web aux origines JavaScript autorisées et aux URI de redirection autorisés.
- Cliquez sur Créer et patientez cinq minutes avant de continuer.
Après avoir suivi la procédure, vous obtiendrez un ID client au format suivant :
123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
Indiquez cette valeur dans l'attribut oauth-client-id du composant Web chat-messenger.
Créer votre propre API d'authentification
Créez votre propre API pour gérer l'authentification et l'autorisation de l'utilisateur final, qui renvoie un jeton d'accès Google ou un jeton JWT signé ayant l'autorisation d'appeler runSession dans votre application.
Pour en savoir plus sur l'utilisation de l'API CX Agent Studio, consultez Accès à l'API.