BotFramework WebChat
[4.18.0] - 2024-07-10
Dieses Repository enthält Code für die Bot Framework Web Chat-Komponente. Die Bot Framework Web Chat-Komponente ist ein hochgradig anpassbarer webbasierter Client für das Bot Framework v4 SDK. Mit dem Bot Framework SDK v4 können Entwickler Konversationen modellieren und anspruchsvolle Bot-Anwendungen erstellen.
Dieses Repository ist Teil des Microsoft Bot Framework – einem umfassenden Framework zum Aufbau von Konversations-KI-Erlebnissen auf Unternehmensniveau.
Web Chat unterstützt Content Security Policy (CSP). Webentwicklern wird empfohlen, CSP zu aktivieren, um die Sicherheit zu verbessern und Konversationen zu schützen. Weitere Informationen zu CSP finden Sie in diesem Artikel.
In diesem Abschnitt werden wichtige Versionshinweise aufgeführt. Weitere Informationen finden Sie unter den entsprechenden Links und im
CHANGELOG.md
Hinweise: Webentwicklern wird empfohlen, ~ (Tilde-Bereich) zu verwenden, um Nebenversionen auszuwählen, die neue Funktionen und/oder Korrekturen enthalten. Verwenden Sie ^ (Caret-Bereich), um Hauptversionen auszuwählen, die möglicherweise wichtige Änderungen enthalten.
In dieser Version konzentrieren wir uns auf Leistungsverbesserungen, einschließlich Speicher- und Ladezeitoptimierungen.
Bots können ihre Antworten jetzt per Livestream übertragen. Bevor das Bot Framework SDK diese Funktion unterstützt, können Bot-Autoren den Details in LIVESTREAMING.md folgen, um die Livestream-Antworten zu erstellen.
Web Chat wird jetzt als ES-Module (benannte Exporte) zusammen mit CommonJS (benannte und unbenannte Exporte) exportiert.
Endbenutzer können jetzt eine Nachricht hinzufügen und bestätigen, bevor sie ihre Datei in den Bot hochladen. Um die neue Erfahrung zu deaktivieren, übergeben Sie sendAttachmentOn: 'send' in den Stiloptionen.
Wir freuen uns, die Unterstützung für Theme-Pakete anbieten zu können. Entwickler können jetzt alle ihre Anpassungen in einem einzigen Paket packen und in NPM veröffentlichen.
Wir freuen uns, Ihnen mitteilen zu können, dass das Fluent UI-Themenpaket in Arbeit ist und sich derzeit in der experimentellen Phase befindet. Dieses Themenpaket richtet sich an Webentwickler, die ihren Kunden ein natives Copilot-Benutzererlebnis bieten möchten.
Wir werden weiterhin neue Funktionen hinzufügen und sowohl die White-Label-Erfahrung als auch die Fluent-UI-Erfahrung mit demselben Paritätsniveau unterstützen.
Sie können den Web-Chat mit <FluentThemeProvider> umschließen, um die neue Erfahrung auszuprobieren.
import ReactWebChat from 'botframework-webchat' ;
import { FluentThemeProvider } from 'botframework-webchat-fluent-theme' ;
export default function MyComponent ( ) {
return (
< FluentThemeProvider >
< ReactWebChat / >
< / FluentThemeProvider >
) ;
} Der Web-Chat rendert jetzt HTML-in-Markdown. Wir haben unseren Sanitizer und Accessibility Fixer portiert, um auf HTML-Ebene zu funktionieren. Sowohl Markdown als auch HTML-in-Markdown werden gleich behandelt und erfüllen unsere Sicherheits- und Barrierefreiheitsanforderungen.
Sie können diese Option deaktivieren, indem Sie styleOptions.markdownRenderHTML auf false setzen.
Web Chat unterstützt jetzt das Adaptive Cards-Schema bis 1.6. Einige Funktionen in Adaptive Cards befinden sich in der Vorschau oder sind für die Verwendung außerhalb von Bot Framework konzipiert. Web-Chat unterstützt diese Funktionen nicht.
Ab 4.16.0 wird Internet Explorer nicht mehr unterstützt. Nachdem Internet Explorer 11 mehr als ein Jahr lang offiziell eingestellt wurde, haben wir beschlossen, den Support für Internet Explorer einzustellen. Dies wird uns helfen, neue Funktionen in den Web-Chat einzuführen. 4.15.9 ist die letzte Version, die Internet Explorer eingeschränkt unterstützt.
adaptiveCardsParserMaxVersionWeb Chat 4.12.1-Patch enthält eine neue Stileigenschaft, die es Entwicklern ermöglicht, die maximale Adaptive Cards-Schemaversion auszuwählen. Codeänderungen finden Sie in PR #3778.
Um eine andere maximale Version anzugeben, können Sie die unten gezeigten Stiloptionen anpassen:
window . WebChat . renderWebChat (
{
directLine ,
store ,
styleOptions : {
adaptiveCardsParserMaxVersion : '1.2'
}
} ,
document . getElementById ( 'webchat' )
) ; Ab PR #3703 wurde dem Web-Chat ein neues Barrierefreiheitsupdate hinzugefügt. Durch diese Änderung wird standardmäßig ein visueller Fokus für das Transkript (fetter schwarzer Rand) und die aria-activedescendent fokussierte Aktivität (schwarzer gestrichelter Rand) erstellt. Gegebenenfalls werden transcriptVisualKeyboardIndicator... Werte auch auf untergeordnete Elemente des Karussells ( CarouselFilmStrip.js ) angewendet. Dies geschieht, um dem aktuellen Standard-Fokusstil für adaptive Karten zu entsprechen, bei denen es sich möglicherweise um ein untergeordnetes Element eines Karussells handelt.
Um diese Stile zu ändern, können Sie die folgenden Requisiten über styleOptions ändern:
transcriptActivityVisualKeyboardIndicatorColor: DEFAULT_SUBTLE,
transcriptActivityVisualKeyboardIndicatorStyle: 'dashed',
transcriptActivityVisualKeyboardIndicatorWidth: 1,
transcriptVisualKeyboardIndicatorColor: 'Black',
transcriptVisualKeyboardIndicatorStyle: 'solid',
transcriptVisualKeyboardIndicatorWidth: 2,
Der obige Code zeigt die Standardwerte, die Sie im Web-Chat sehen.
Die Web-Chat-API wurde in ein separates Paket umgestaltet. Weitere Informationen finden Sie in der API-Refactor-Zusammenfassung.
Ab Web Chat 4.7.0 wird Direct Line Speech unterstützt und ist die bevorzugte Möglichkeit, eine integrierte Sprachfunktion im Web Chat bereitzustellen. Wir arbeiten daran, Funktionslücken zwischen Direct Line Speech und der Web Speech API (einschließlich kognitiver Dienste und vom Browser bereitgestellter Sprachfunktionalität) zu schließen.
Ab Web Chat 4.6.0 erfordert Web Chat React 16.8.6 oder höher.
Obwohl wir Ihnen empfehlen, Ihre Host-App so bald wie möglich zu aktualisieren, verstehen wir, dass es einige Zeit dauern kann, bis die React-Abhängigkeiten der Host-App aktualisiert werden, insbesondere im Hinblick auf große Anwendungen.
Wenn Ihre App noch nicht für React 16.8.6 bereit ist, können Sie dem Hybrid-React-Beispiel folgen, um React in Ihrer App mit zwei Hosts zu hosten.
Es gibt eine bahnbrechende Änderung der Verhaltenserwartungen in Bezug auf Sprache und Eingabehinweise im Webchat. Weitere Informationen finden Sie im Abschnitt zum Verhalten von Eingabehinweisen vor 4.5.0.
Sehen Sie sich die Migrationsdokumente an, um mehr über die Migration von Web Chat v3 zu erfahren.
Erstellen Sie zunächst einen Bot mit Azure Bot Service. Sobald der Bot erstellt wurde, müssen Sie das Webchat-Geheimnis des Bots im Azure-Portal abrufen. Verwenden Sie dann das Geheimnis, um ein Token zu generieren und es an Ihren Web-Chat weiterzuleiten.
Web Chat bietet eine Benutzeroberfläche zusätzlich zu den Direct Line- und Direct Line Speech-Kanälen. Es gibt zwei Möglichkeiten, über HTTP-Aufrufe vom Client eine Verbindung zu Ihrem Bot herzustellen: durch Senden des Bot-Geheimnisses oder durch Generieren eines Tokens über das Geheimnis.
Wir empfehlen dringend, die Token-API zu verwenden, anstatt der App Ihr Geheimnis bereitzustellen. Weitere Informationen zum Grund finden Sie in der Authentifizierungsdokumentation zur Token-API und zur Clientsicherheit.
Weitere Informationen finden Sie unter den folgenden Links:
Verwenden von Web-Chat mit Azure Bot Services-Authentifizierung
Erweiterte Direct Line-Authentifizierungsfunktionen
Web Chat ist für die Integration in Ihre bestehende Website mithilfe von JavaScript oder React konzipiert. Durch die Integration mit JavaScript erhalten Sie moderate Gestaltungs- und Anpassbarkeitsoptionen.
Sie können das vollständige, typische Web-Chat-Paket (das sogenannte Full-Feature-Bundle) verwenden, das die am häufigsten verwendeten Funktionen enthält.
So können Sie Ihrer Website eine Web-Chat-Steuerung hinzufügen:
<!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,usernameundlocalesind allesamt optionale Parameter, die an dierenderWebChat-Methode übergeben werden. Weitere Informationen zu Web-Chat-Requisiten finden Sie in der Web-Chat-API-Referenzdokumentation.
Die Zuweisung
userIDals statischen Wert wird nicht empfohlen, da dies dazu führt, dass alle Benutzer den Status teilen. Weitere Informationen finden Sie imAPI userID entry.
Weitere Informationen zur Lokalisierung finden Sie in der Lokalisierungsdokumentation.
Sehen Sie sich das Arbeitsbeispiel des vollständigen Web-Chat-Pakets an.
Für eine vollständige Anpassbarkeit können Sie React verwenden, um Komponenten des Web-Chats neu zusammenzustellen.
Um den Produktions-Build von NPM zu installieren, führen Sie npm install botframework-webchat aus. Informationen zur Auswahl einer Version finden Sie in unseren Versionshinweisen.
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" / > ;
} ;Sie können auch
npm install botframework-webchat@mainausführen, um einen Entwicklungs-Build zu installieren, der mit dem GitHub-mainvon Web Chat synchronisiert wird.
Sehen Sie sich das funktionierende Beispiel des über React gerenderten Web-Chats an.
Web-Chat verwendet intern Redux für die Statusverwaltung. Redux DevTools ist im NPM-Build als Opt-in-Funktion aktiviert.
Hier erhalten Sie einen Einblick in die Funktionsweise des Web-Chats. Dies ist kein API-Explorer und stellt keine Empfehlung für die Verwendung des Redux-Stores für den programmgesteuerten Zugriff auf die Benutzeroberfläche dar. Stattdessen sollte die Hooks-API verwendet werden.
Um Redux DevTools zu verwenden, verwenden Sie die Funktion createStoreWithDevTools zum Erstellen eines Redux DevTools-fähigen Stores.
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" />;
};Bei der Verwendung der Redux DevTools gibt es einige Einschränkungen:
redux-saga . Zeitreisen können die Benutzeroberfläche beschädigen.Web Chat ist so konzipiert, dass es anpassbar ist, ohne den Quellcode zu teilen. Die folgende Tabelle zeigt, welche Anpassungen Sie erreichen können, wenn Sie Web-Chat auf unterschiedliche Weise importieren. Diese Liste ist nicht vollständig.
| CDN-Bundle | Reagieren | |
|---|---|---|
| Farben ändern | ✔ | ✔ |
| Größen ändern | ✔ | ✔ |
| CSS-Stile aktualisieren/ersetzen | ✔ | ✔ |
| Hören Sie sich Ereignisse an | ✔ | ✔ |
| Interagieren Sie mit der Hosting-Webseite | ✔ | ✔ |
| Benutzerdefinierte Renderaktivitäten | ✔ | |
| Benutzerdefinierte Render-Anhänge | ✔ | |
| Fügen Sie neue UI-Komponenten hinzu | ✔ | |
| Stellen Sie die gesamte Benutzeroberfläche neu zusammen | ✔ |
Erfahren Sie mehr über die Anpassung des Web-Chats, um mehr über die Anpassung zu erfahren.
Bot Framework verfügt über viele Aktivitätstypen, aber nicht alle werden im Webchat unterstützt. Sehen Sie sich die Dokumente zu Aktivitätstypen an, um mehr zu erfahren.
Sehen Sie sich die vollständige Liste der Web-Chat-Beispiele an, um weitere Ideen zum Anpassen des Web-Chats zu erhalten.
Sehen Sie sich die API-Dokumentation zur Implementierung von Web Chat an.
Web Chat unterstützt die beiden neuesten Versionen moderner Browser wie Chrome, Microsoft Edge und Firefox. Wenn Sie Web-Chat in Internet Explorer 11 benötigen, sehen Sie sich bitte die ES5-Bundle-Demo an.
Bitte beachten Sie jedoch:
babel in Betracht zu ziehen. Sehen Sie sich die Dokumentation zur Barrierefreiheit an.
Sehen Sie sich die Lokalisierungsdokumentation für die Implementierung im Web-Chat an.
Sehen Sie sich die Benachrichtigungsdokumentation für die Implementierung im Web-Chat an.
Sehen Sie sich die Telemetriedokumentation zur Implementierung im Web-Chat an.
Sehen Sie sich den Leitfaden zum technischen Support an, um Anleitungen und Hilfe zur Fehlerbehebung im Web-Chat-Repository zu erhalten und weitere Informationen zu erhalten, bevor Sie ein neues Problem einreichen.
Web Chat unterstützt eine Vielzahl von Sprach-Engines für ein natürliches Chat-Erlebnis mit einem Bot. In diesem Abschnitt werden die verschiedenen Engines beschrieben, die unterstützt werden:
Direct Line Speech ist die bevorzugte Möglichkeit, Sprachfunktionen im Webchat hinzuzufügen. Weitere Informationen finden Sie in der Direct Line Speech-Dokumentation.
Sie können Cognitive Services Speech Services verwenden, um Sprachfunktionen zum Webchat hinzuzufügen. Weitere Informationen finden Sie in der Dokumentation zu Cognitive Services Speech Services.
Sie können auch alle Sprach-Engines verwenden, die den W3C Web Speech API-Standard unterstützen. Einige Browser unterstützen die Speech Recognition API und die Speech Synthesis API. Sie können verschiedene Engines – einschließlich Cognitive Services Speech Services – kombinieren und anpassen, um die beste Benutzererfahrung zu bieten.
Die neuesten Web-Chat-Inhalte sind auf der Seite mit den täglichen Web-Chat-Veröffentlichungen verfügbar.
Tageszeitungen werden nach 3:00 Uhr pazifischer Standardzeit veröffentlicht, wenn Änderungen im Hauptzweig übernommen wurden.
Weitere Informationen zum Erstellen des Projekts und unsere Repository-Richtlinien für Pull-Anfragen finden Sie auf unserer Seite „Beitragen“.
Weitere Informationen zum Microsoft-Verhaltenskodex finden Sie auf unserer Seite „VERHALTENSKODEX“.
Sehen Sie sich die Sicherheitsdokumentation an, um mehr über das Melden von Sicherheitsproblemen zu erfahren.
