BotFramework WebChat
[4.18.0] - 2024-07-10
Ce référentiel contient le code du composant Bot Framework Web Chat. Le composant Bot Framework Web Chat est un client Web hautement personnalisable pour le SDK Bot Framework v4. Le Bot Framework SDK v4 permet aux développeurs de modéliser la conversation et de créer des applications de robot sophistiquées.
Ce référentiel fait partie de Microsoft Bot Framework, un cadre complet permettant de créer des expériences d'IA conversationnelle de niveau entreprise.
Web Chat prend en charge la politique de sécurité du contenu (CSP). Il est recommandé aux développeurs Web de permettre au CSP d'améliorer la sécurité et de protéger les conversations. Vous pouvez en savoir plus sur CSP dans cet article.
Cette section souligne les notes de version importantes. Pour plus d'informations, veuillez consulter les liens associés et consulter le
CHANGELOG.md
Remarques : il est conseillé aux développeurs Web d'utiliser ~ (plage de tilde) pour sélectionner les versions mineures contenant de nouvelles fonctionnalités et/ou des correctifs. Utilisez ^ (plage de carets) pour sélectionner les versions majeures, qui peuvent contenir des modifications importantes.
Dans cette version, nous nous concentrons sur l'amélioration des performances, notamment l'optimisation de la mémoire et du temps de chargement.
Les robots peuvent désormais diffuser leurs réponses en direct. Avant que le SDK Bot Framework ne prenne en charge cette fonctionnalité, les auteurs de robots peuvent suivre les détails dans LIVESTREAMING.md pour construire les réponses en direct.
Web Chat s'exporte désormais sous forme de modules ES (exportations nommées) avec CommonJS (exportations nommées et sans nom).
L'utilisateur final peut désormais ajouter un message et confirmer avant de télécharger son fichier sur le bot. Pour vous désinscrire de la nouvelle expérience, transmettez sendAttachmentOn: 'send' dans les options de style.
Nous sommes ravis d’ajouter la prise en charge des packs de thèmes. Les développeurs peuvent désormais regrouper toute leur personnalisation dans un seul package et la publier sur NPM.
Nous sommes ravis d'annoncer que le pack de thèmes Fluent UI est en préparation et est actuellement en phase expérimentale. Ce pack de thèmes est conçu pour les développeurs Web qui souhaitent apporter une expérience utilisateur Copilot native à leurs clients.
Nous continuerons d'ajouter de nouvelles fonctionnalités et de prendre en charge à la fois l'expérience en marque blanche et l'expérience Fluent UI avec le même niveau de parité.
Vous pouvez envelopper le chat Web avec <FluentThemeProvider> pour essayer la nouvelle expérience.
import ReactWebChat from 'botframework-webchat' ;
import { FluentThemeProvider } from 'botframework-webchat-fluent-theme' ;
export default function MyComponent ( ) {
return (
< FluentThemeProvider >
< ReactWebChat / >
< / FluentThemeProvider >
) ;
} Web Chat affichera désormais le HTML dans Markdown. Nous avons porté notre désinfectant et notre fixateur d'accessibilité pour qu'il fonctionne au niveau HTML. Markdown et HTML-in-Markdown recevront le même traitement et répondront à nos exigences de sécurité et d'accessibilité.
Vous pouvez désactiver cette option en définissant styleOptions.markdownRenderHTML sur false .
Web Chat prend désormais en charge le schéma Adaptive Cards jusqu'à 1.6. Certaines fonctionnalités des cartes adaptatives sont en version préliminaire ou conçues pour être utilisées en dehors de Bot Framework. Web Chat ne prend pas en charge ces fonctionnalités.
À partir de la version 4.16.0, Internet Explorer n'est plus pris en charge. Après plus d'un an de retrait officiel d'Internet Explorer 11, nous avons décidé de cesser de prendre en charge Internet Explorer. Cela nous aidera à apporter de nouvelles fonctionnalités au Web Chat. 4.15.9 est la dernière version qui prend en charge Internet Explorer de manière limitée.
adaptiveCardsParserMaxVersionLe correctif Web Chat 4.12.1 inclut une nouvelle propriété de style permettant aux développeurs de choisir la version maximale du schéma des cartes adaptatives. Voir PR # 3778 pour les modifications de code.
Pour spécifier une version maximale différente, vous pouvez ajuster les options de style, indiquées ci-dessous :
window . WebChat . renderWebChat (
{
directLine ,
store ,
styleOptions : {
adaptiveCardsParserMaxVersion : '1.2'
}
} ,
document . getElementById ( 'webchat' )
) ; Une nouvelle mise à jour d'accessibilité a été ajoutée à Web Chat à partir du PR #3703. Ce changement crée un focus visuel pour la transcription (bordure noire en gras) et l'activité ciblée aria-activedescendent (bordure en pointillés noirs) par défaut. Le cas échéant, les valeurs transcriptVisualKeyboardIndicator... seront également appliquées aux enfants du carrousel ( CarouselFilmStrip.js ). Ceci est fait afin de correspondre au style de focus par défaut actuel pour les cartes adaptatives, qui peuvent être un enfant d'un carrousel.
Pour modifier ces styles, vous pouvez changer les accessoires suivants via styleOptions :
transcriptActivityVisualKeyboardIndicatorColor: DEFAULT_SUBTLE,
transcriptActivityVisualKeyboardIndicatorStyle: 'dashed',
transcriptActivityVisualKeyboardIndicatorWidth: 1,
transcriptVisualKeyboardIndicatorColor: 'Black',
transcriptVisualKeyboardIndicatorStyle: 'solid',
transcriptVisualKeyboardIndicatorWidth: 2,
Le code ci-dessus montre les valeurs par défaut que vous verrez dans Web Chat.
L'API Web Chat a été refactorisée dans un package distinct. Pour en savoir plus, consultez le résumé du refactoring de l'API.
À partir de Web Chat 4.7.0, Direct Line Speech est pris en charge et constitue le moyen privilégié pour fournir une fonctionnalité vocale intégrée dans Web Chat. Nous travaillons à combler les lacunes en termes de fonctionnalités entre l'API Direct Line Speech et Web Speech (inclut les services cognitifs et la fonctionnalité vocale fournie par le navigateur).
À partir de Web Chat 4.6.0, Web Chat nécessite React 16.8.6 ou version ultérieure.
Bien que nous vous recommandons de mettre à niveau votre application hôte dès que possible, nous comprenons que l'application hôte peut avoir besoin d'un certain temps avant que ses dépendances React ne soient mises à jour, en particulier en ce qui concerne les applications volumineuses.
Si votre application n'est pas encore prête pour React 16.8.6, vous pouvez suivre l'exemple React hybride pour utiliser React à double hôte dans votre application.
Il y a un changement radical dans les attentes comportementales concernant la parole et les indications de saisie dans le chat Web. Veuillez vous référer à la section sur le comportement des indices de saisie avant la version 4.5.0 pour plus de détails.
Consultez les documents de migration pour en savoir plus sur la migration à partir de Web Chat v3.
Tout d’abord, créez un bot à l’aide d’Azure Bot Service. Une fois le bot créé, vous devrez obtenir le secret Web Chat du bot dans le portail Azure. Utilisez ensuite le secret pour générer un jeton et transmettez-le à votre chat Web.
Web Chat fournit une interface utilisateur en plus des canaux vocaux Direct Line et Direct Line. Il existe deux manières de se connecter à votre bot via des appels HTTP du client : en envoyant le secret du Bot ou en générant un jeton via le secret.
Nous vous recommandons fortement d'utiliser l'API de jeton au lieu de fournir votre secret à l'application. Pour en savoir plus, consultez la documentation d'authentification sur l'API de jeton et la sécurité du client.
Pour en savoir plus, veuillez consulter les liens suivants :
Utilisation de Web Chat avec l'authentification Azure Bot Services
Fonctionnalités d'authentification Direct Line améliorées
Web Chat est conçu pour s'intégrer à votre site Web existant à l'aide de JavaScript ou de React. L'intégration avec JavaScript vous offrira des options de style et de personnalisation modérées.
Vous pouvez utiliser le package Web Chat complet et typique (appelé ensemble complet de fonctionnalités) qui contient les fonctionnalités les plus généralement utilisées.
Voici comment ajouter le contrôle Web Chat à votre site Web :
<!DOCTYPE html >
< html >
< head >
< script
crossorigin =" anonymous "
src =" https://cdn.botframework.com/botframework-webchat/latest/webchat.js "
> </ script >
< style >
html,
body {
height: 100%;
}
body {
margin: 0;
}
#webchat {
height: 100%;
width: 100%;
}
</ style >
</ head >
< body >
< div id =" webchat " role =" main " > </ div >
< script >
window . WebChat . renderWebChat (
{
directLine : window . WebChat . createDirectLine ( {
token : 'YOUR_DIRECT_LINE_TOKEN'
} ) ,
userID : 'YOUR_USER_ID' ,
username : 'Web Chat User' ,
locale : 'en-US'
} ,
document . getElementById ( 'webchat' )
) ;
</ script >
</ body >
</ html >
userID,usernameetlocalesont tous des paramètres facultatifs à transmettre à la méthoderenderWebChat. Pour en savoir plus sur les accessoires Web Chat, consultez la documentation de référence de l'API Web Chat.
L'attribution
userIDen tant que valeur statique n'est pas recommandée car cela entraînerait le partage de l'état par tous les utilisateurs. Veuillez consulter l'API userID entrypour plus d'informations.
Plus d’informations sur la localisation peuvent être trouvées dans la documentation sur la localisation.
Consultez l’exemple fonctionnel de l’ensemble complet de Web Chat.
Pour une personnalisation complète, vous pouvez utiliser React pour recomposer les composants de Web Chat.
Pour installer la version de production à partir de NPM, exécutez npm install botframework-webchat . Consultez nos notes de version pour savoir comment sélectionner une version.
import React , { useMemo } from 'react' ;
import ReactWebChat , { createDirectLine } from 'botframework-webchat' ;
export default ( ) => {
const directLine = useMemo ( ( ) => createDirectLine ( { token : 'YOUR_DIRECT_LINE_TOKEN' } ) , [ ] ) ;
return < ReactWebChat directLine = { directLine } userID = "YOUR_USER_ID" / > ;
} ;Vous pouvez également exécuter
npm install botframework-webchat@mainpour installer une version de développement synchronisée avec la branchemainGitHub de Web Chat.
Consultez l’exemple fonctionnel de Web Chat rendu via React.
Web Chat utilise Redux en interne pour la gestion de l'état. Redux DevTools est activé dans la version NPM en tant que fonctionnalité opt-in.
Ceci permet de voir comment fonctionne le chat Web. Il ne s'agit pas d'un explorateur d'API et ne constitue pas une approbation de l'utilisation du magasin Redux pour accéder par programme à l'interface utilisateur. L'API hooks doit être utilisée à la place.
Pour utiliser Redux DevTools, utilisez la fonction createStoreWithDevTools pour créer un magasin compatible Redux DevTools.
import React, { useMemo } from 'react';
- import ReactWebChat, { createDirectLine, createStore } from 'botframework-webchat';
+ import ReactWebChat, { createDirectLine, createStoreWithDevTools } from 'botframework-webchat';
export default () => {
const directLine = useMemo(() => createDirectLine({ token: 'YOUR_DIRECT_LINE_TOKEN' }), []);
- const store = useMemo(() => createStore(), []);
+ const store = useMemo(() => createStoreWithDevTools(), []);
return <ReactWebChat directLine={directLine} store={store} userID="YOUR_USER_ID" />;
};Il existe certaines limitations lors de l'utilisation de Redux DevTools :
redux-saga . Les voyages dans le temps peuvent interrompre l'interface utilisateur.Web Chat est conçu pour être personnalisable sans bifurquer le code source. Le tableau ci-dessous décrit les types de personnalisations que vous pouvez réaliser lorsque vous importez Web Chat de différentes manières. Cette liste n'est pas exhaustive.
| Forfait CDN | Réagir | |
|---|---|---|
| Changer les couleurs | ✔ | ✔ |
| Changer les tailles | ✔ | ✔ |
| Mettre à jour/remplacer les styles CSS | ✔ | ✔ |
| Écoutez les événements | ✔ | ✔ |
| Interagir avec la page Web d'hébergement | ✔ | ✔ |
| Activités de rendu personnalisées | ✔ | |
| Pièces jointes de rendu personnalisées | ✔ | |
| Ajouter de nouveaux composants d'interface utilisateur | ✔ | |
| Recomposer toute l'interface utilisateur | ✔ |
En savoir plus sur la personnalisation de Web Chat pour en savoir plus sur la personnalisation.
Bot Framework propose de nombreux types d’activités, mais tous ne sont pas pris en charge dans Web Chat. Consultez la documentation sur les types d’activités pour en savoir plus.
Consultez la liste complète des exemples de Web Chat pour plus d’idées sur la personnalisation de Web Chat.
Consultez la documentation de l'API pour implémenter Web Chat.
Web Chat prend en charge les 2 dernières versions des navigateurs modernes comme Chrome, Microsoft Edge et FireFox. Si vous avez besoin de Web Chat dans Internet Explorer 11, veuillez consulter la démo du bundle ES5.
Attention toutefois :
babel . Consultez la documentation sur l'accessibilité.
Consultez la documentation de localisation pour l’implémentation dans Web Chat.
Consultez la documentation sur les notifications pour l’implémentation dans Web Chat.
Consultez la documentation de télémétrie pour l’implémentation dans Web Chat.
Consultez le guide du support technique pour obtenir des conseils et de l'aide sur le dépannage dans le dépôt Web Chat pour plus d'informations avant de signaler un nouveau problème.
Web Chat prend en charge une large gamme de moteurs vocaux pour une expérience de discussion naturelle avec un bot. Cette section présente les différents moteurs pris en charge :
Direct Line Speech est le moyen privilégié pour ajouter des fonctionnalités vocales dans Web Chat. Veuillez vous référer à la documentation Direct Line Speech pour plus de détails.
Vous pouvez utiliser les services vocaux de Cognitive Services pour ajouter des fonctionnalités vocales à Web Chat. Veuillez vous référer à la documentation des services vocaux de Cognitive Services pour plus de détails.
Vous pouvez également utiliser n’importe quel moteur vocal prenant en charge la norme API Web Speech du W3C. Certains navigateurs prennent en charge l'API de reconnaissance vocale et l'API de synthèse vocale. Vous pouvez mélanger et assortir différents moteurs, notamment les services vocaux de Cognitive Services, pour offrir la meilleure expérience utilisateur.
Les derniers éléments de Web Chat sont disponibles sur la page des versions quotidiennes de Web Chat.
Les quotidiens seront publiés après 3h00, heure normale du Pacifique, lorsque les modifications auront été validées dans la branche principale.
Consultez notre page de contribution pour plus de détails sur la façon de créer le projet et nos directives de référentiel pour les demandes d'extraction.
Consultez notre page CODE DE CONDUITE pour plus de détails sur le Code de conduite Microsoft.
Consultez la documentation sur la sécurité pour en savoir plus sur le signalement des problèmes de sécurité.
