BotFramework WebChat
[4.18.0] - 2024-07-10
このリポジトリには、Bot Framework Web Chat コンポーネントのコードが含まれています。 Bot Framework Web チャット コンポーネントは、Bot Framework v4 SDK の高度にカスタマイズ可能な Web ベースのクライアントです。 Bot Framework SDK v4 を使用すると、開発者は会話をモデル化し、洗練されたボット アプリケーションを構築できます。
このリポジトリは、エンタープライズ グレードの会話型 AI エクスペリエンスを構築するための包括的なフレームワークである Microsoft Bot Framework の一部です。
Web チャットはコンテンツ セキュリティ ポリシー (CSP) をサポートしています。 Web 開発者は、CSP を有効にしてセキュリティを強化し、会話を保護することをお勧めします。 CSP について詳しくは、この記事をご覧ください。
このセクションでは、バージョンに関する重要な注意事項を示します。詳細については、関連リンクを参照し、
CHANGELOG.md確認してください。
注: Web 開発者は、 ~ (チルダ範囲) を使用して、新機能や修正が含まれるマイナー バージョンを選択することをお勧めします。 ^ (キャレット範囲) を使用して、重大な変更が含まれる可能性があるメジャー バージョンを選択します。
このリリースでは、メモリやロード時間の最適化などのパフォーマンスの向上に重点を置いています。
ボットは応答をライブストリーミングできるようになりました。 Bot Framework SDK がこの機能をサポートする前は、ボット作成者は LIVESTREAMING.md の詳細に従ってライブストリーム応答を構築できます。
Web チャットは、CommonJS (名前付きおよび名前なしエクスポート) とともに ES モジュール (名前付きエクスポート) としてエクスポートされるようになりました。
エンドユーザーは、ファイルをボットにアップロードする前にメッセージを追加して確認できるようになりました。新しいエクスペリエンスをオプトアウトするには、スタイル オプションでsendAttachmentOn: 'send'を渡します。
テーマ パックのサポートを追加できることを嬉しく思います。開発者は、すべてのカスタマイズを 1 つのパッケージにまとめて NPM に公開できるようになりました。
Fluent UI テーマ パックが開発中で、現在実験段階にあることを発表できることを嬉しく思います。このテーマ パックは、ネイティブの Copilot ユーザー エクスペリエンスを顧客に提供したい Web 開発者向けに設計されています。
今後も新機能を追加し、ホワイトラベル エクスペリエンスと Fluent UI エクスペリエンスの両方を同じレベルでサポートしていきます。
Web チャットを<FluentThemeProvider>でラップして、新しいエクスペリエンスを試すことができます。
import ReactWebChat from 'botframework-webchat' ;
import { FluentThemeProvider } from 'botframework-webchat-fluent-theme' ;
export default function MyComponent ( ) {
return (
< FluentThemeProvider >
< ReactWebChat / >
< / FluentThemeProvider >
) ;
} Web チャットは HTML-in-Markdown をレンダリングするようになりました。サニタイザーとアクセシビリティ フィクサーを HTML レベルで動作するように移植しました。 Markdown と HTML-in-Markdown はどちらも同じ扱いを受け、セキュリティとアクセシビリティの要件を満たします。
このオプションをオフにするには、 styleOptions.markdownRenderHTML falseに設定します。
Web チャットは、1.6 までのアダプティブ カード スキーマをサポートするようになりました。アダプティブ カードの一部の機能はプレビュー段階にあるか、Bot Framework の外部で使用するように設計されています。 Web チャットはこれらの機能をサポートしていません。
4.16.0 以降、Internet Explorer はサポートされなくなりました。 Internet Explorer 11 が正式に廃止されてから 1 年以上が経過した後、私たちは Internet Explorer のサポートを停止することを決定しました。これは、Web チャットに新しい機能を導入するのに役立ちます。 4.15.9 は、限定的に Internet Explorer をサポートする最後のバージョンです。
adaptiveCardsParserMaxVersionWeb Chat 4.12.1 パッチには、開発者がアダプティブ カード スキーマの最大バージョンを選択できる新しいスタイル プロパティが含まれています。コードの変更については PR #3778 を参照してください。
別の最大バージョンを指定するには、以下に示すスタイル オプションを調整できます。
window . WebChat . renderWebChat (
{
directLine ,
store ,
styleOptions : {
adaptiveCardsParserMaxVersion : '1.2'
}
} ,
document . getElementById ( 'webchat' )
) ;新しいアクセシビリティ更新が PR #3703 から Web チャットに追加されました。この変更により、デフォルトでトランスクリプト (太字の黒枠) とaria-activedescendentに焦点を当てたアクティビティ (黒の破線) に視覚的なフォーカスが作成されます。該当する場合、 transcriptVisualKeyboardIndicator...値はカルーセル ( CarouselFilmStrip.js ) の子にも適用されます。これは、カルーセルの子である可能性があるアダプティブ カードの現在のデフォルトのフォーカス スタイルと一致させるために行われます。
これらのスタイルを変更するには、 styleOptionsを介して次のプロパティを変更できます。
transcriptActivityVisualKeyboardIndicatorColor: DEFAULT_SUBTLE,
transcriptActivityVisualKeyboardIndicatorStyle: 'dashed',
transcriptActivityVisualKeyboardIndicatorWidth: 1,
transcriptVisualKeyboardIndicatorColor: 'Black',
transcriptVisualKeyboardIndicatorStyle: 'solid',
transcriptVisualKeyboardIndicatorWidth: 2,
上記のコードは、Web チャットに表示されるデフォルト値を示しています。
Web チャット API は別のパッケージにリファクタリングされました。詳細については、API リファクタリングの概要をご覧ください。
Web チャット 4.7.0 以降では、ダイレクト ライン スピーチがサポートされており、これは Web チャットに統合された音声機能を提供するための推奨される方法です。私たちは、Direct Line Speech と Web Speech API (Cognitive Services およびブラウザー提供の音声機能を含む) の間の機能ギャップを埋めることに取り組んでいます。
Web チャット 4.6.0 以降、Web チャットには React 16.8.6 以降が必要です。
できるだけ早くホスト アプリをアップグレードすることをお勧めしますが、特に大規模なアプリケーションに関しては、ホスト アプリの React 依存関係が更新されるまでに時間がかかる場合があることを理解しています。
アプリがまだ React 16.8.6 に対応する準備ができていない場合は、ハイブリッド React サンプルに従って、アプリ内で React をデュアルホストすることができます。
Web チャットでの音声と入力ヒントに関する動作の期待に重大な変更があります。詳細については、4.5.0 より前の入力ヒントの動作に関するセクションを参照してください。
Web Chat v3 からの移行については、移行ドキュメントを参照してください。
まず、Azure Bot Service を使用してボットを作成します。ボットを作成したら、Azure Portal でボットの Web チャット シークレットを取得する必要があります。次に、シークレットを使用してトークンを生成し、それを Web チャットに渡します。
Web チャットは、Direct Line および Direct Line Speech Channel 上に UI を提供します。クライアントからの HTTP 呼び出しを通じてボットに接続するには、ボットのシークレットを送信する方法と、シークレットを介してトークンを生成する方法の 2 つがあります。
アプリにシークレットを提供するのではなく、トークン API を使用することを強くお勧めします。その理由の詳細については、トークン API とクライアント セキュリティに関する認証ドキュメントを参照してください。
さらに詳しく知りたい場合は、次のリンクを参照してください。
Azure Bot Services 認証での Web チャットの使用
強化された Direct Line 認証機能
Web チャットは、JavaScript または React を使用して既存の Web サイトと統合するように設計されています。 JavaScript と統合すると、適度なスタイルとカスタマイズ性のオプションが提供されます。
最も一般的に使用される機能が含まれる完全な標準的な Web チャット パッケージ (フル機能バンドルと呼ばれる) を使用できます。
Web チャット コントロールを 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、username、およびlocaleすべて、renderWebChatメソッドに渡すオプションのパラメータです。 Web チャットの小道具の詳細については、Web チャット API リファレンス ドキュメントを参照してください。
userID静的な値として割り当てることは、すべてのユーザーが状態を共有することになるため、お勧めできません。詳細については、API userID entryを参照してください。
ローカリゼーションの詳細については、ローカリゼーションのドキュメントを参照してください。
完全な Web チャット バンドルの動作サンプルをご覧ください。
完全にカスタマイズ可能にするために、React を使用して Web チャットのコンポーネントを再構成できます。
NPM から運用ビルドをインストールするには、 npm install botframework-webchatを実行します。バージョンの選択方法については、バージョン ノートを参照してください。
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" / > ;
} ;
npm install botframework-webchat@main実行して、Web チャットの GitHubmainブランチと同期される開発ビルドをインストールすることもできます。
React 経由でレンダリングされた Web チャットの動作サンプルをご覧ください。
Web チャットは内部で状態管理に Redux を使用します。 Redux DevTools は、NPM ビルドでオプトイン機能として有効になっています。
これは、Web チャットがどのように機能するかをざっと確認するためのものです。これは API エクスプローラーではなく、Redux ストアを使用してプログラムで UI にアクセスすることを推奨するものでもありません。代わりにフック API を使用する必要があります。
Redux DevTools を使用するには、 createStoreWithDevTools関数を使用して 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" />;
};Redux DevTools を使用する場合は、いくつかの制限があります。
redux-sagaによる副作用を使用します。タイムトラベルすると UI が壊れる可能性があります。Web チャットは、ソース コードをフォークせずにカスタマイズできるように設計されています。以下の表は、さまざまな方法で Web チャットをインポートするときに実現できるカスタマイズの概要を示しています。このリストはすべてを網羅したものではありません。
| CDNバンドル | 反応する | |
|---|---|---|
| 色の変更 | ✔ | ✔ |
| サイズを変更する | ✔ | ✔ |
| CSS スタイルを更新/置換する | ✔ | ✔ |
| イベントを聞く | ✔ | ✔ |
| ホスティング Web ページと対話する | ✔ | ✔ |
| カスタムレンダリングアクティビティ | ✔ | |
| カスタムレンダリングアタッチメント | ✔ | |
| 新しい UI コンポーネントを追加する | ✔ | |
| UI全体を再構成する | ✔ |
カスタマイズの詳細については、「Web チャットのカスタマイズに関する詳細」を参照してください。
Bot Framework には多くのアクティビティ タイプがありますが、すべてが Web チャットでサポートされているわけではありません。詳細については、アクティビティ タイプのドキュメントを参照してください。
Web チャットのカスタマイズに関するその他のアイデアについては、Web チャット サンプルの完全なリストをご覧ください。
Web チャットを実装するための API ドキュメントを参照してください。
Web チャットは、Chrome、Microsoft Edge、FireFox などの最新ブラウザの最新 2 バージョンをサポートしています。 Internet Explorer 11 で Web チャットが必要な場合は、ES5 バンドルのデモをご覧ください。
ただし、次の点にご注意ください。
babelのようなトランスパイラを使用してコードを ES6+ から ES5 に変換することを検討することをお勧めします。 アクセシビリティに関するドキュメントをご覧ください。
Web チャットでの実装については、ローカリゼーション ドキュメントを参照してください。
Web チャットでの実装に関する通知のドキュメントを参照してください。
Web チャットでの実装については、テレメトリのドキュメントを参照してください。
新しい問題を提出する前に、テクニカル サポート ガイドを参照して、Web チャット リポジトリのトラブルシューティングに関するガイダンスとヘルプを参照して詳細を確認してください。
Web チャットは、ボットとの自然なチャット エクスペリエンスを実現するための幅広い音声エンジンをサポートしています。このセクションでは、サポートされているさまざまなエンジンについて説明します。
Web チャットに音声機能を追加するには、Direct Line Speech が推奨される方法です。詳細については、Direct Line Speech のドキュメントを参照してください。
Cognitive Services 音声サービスを使用して、Web チャットに音声機能を追加できます。詳細については、Cognitive Services 音声サービスのドキュメントを参照してください。
W3C Web Speech API 標準をサポートする音声エンジンを使用することもできます。一部のブラウザは音声認識 API と音声合成 API をサポートしています。 Cognitive Services 音声サービスなどのさまざまなエンジンを組み合わせて、最高のユーザー エクスペリエンスを提供できます。
Web チャットの最新情報は、Web チャットの毎日のリリース ページで入手できます。
デイリーは、メイン ブランチに変更がコミットされた太平洋標準時の午前 3 時以降にリリースされます。
プロジェクトの構築方法とプル リクエストのリポジトリ ガイドラインの詳細については、「Contributing」ページを参照してください。
Microsoft の行動規範の詳細については、「行動規範」ページを参照してください。
セキュリティ問題の報告の詳細については、セキュリティに関するドキュメントを参照してください。
