buildship chat widget
1.0.0
ウェブサイトまたはアプリに簡単に埋め込むことができるオープンソースAIチャットウィジェット。このプラグアンドプレイウィジェットは、カスタムビルドシップワークフローでシームレスに動作するように設計されており、データベース、知識リポジトリ、および使用するその他のツールに接続できるようになります。
この強力なAIチャットアシスタントを使用すると、ウェブサイトまたはアプリのユーザーエクスペリエンスを大幅に強化できます。
まず、次のコードスニペットを追加して、ページにチャットウィジェットをロードします。次に、ステップ2の手順に従って、サンプルAPI URLをBuildship Deployed API URLに置き換えて、ビルドシップワークフローにウィジェットを接続します。必要に応じてカスタマイズオプションを追加します。
< script src =" https://unpkg.com/@buildshipapp/chat-widget@^1 " defer > </ script >
< script >
window . addEventListener ( "load" , ( ) => {
window . buildShipChatWidget . config . widgetTitle = "Chatbot" ;
window . buildShipChatWidget . config . greetingMessage =
"Hello! How may I help you today?" ;
window . buildShipChatWidget . config . url =
"https://<project_id>.buildship.run/chat/...." ;
<!-- Other optional properties, learn more in the `Config Properties` section below -->
} ) ;
</ script >TypeScriptまたはES6を使用している場合は、モジュールとしてインポートすることもできます（タイプ宣言が含まれています）：
import "@buildshipapp/chat-widget" ;
window . buildShipChatWidget . config . widgetTitle = "Chatbot" ;
window . buildShipChatWidget . config . greetingMessage =
"Hello! How may I help you today?" ;
window . buildShipChatWidget . config . url =
"https://<project_id>.buildship.run/chat/...." ;
// ...第二に、ウィジェットを開くために、ウェブサイトまたはアプリのどこにでも次のデータ属性を備えたボタンを配置します。
< button data-buildship-chat-widget-button > Beep Boop </ button >ウィジェットは、Buildshipで動作するように構築されています。これは、APIを作成するためのローコードバックエンドビルダーであり、ドラッグアンドドロップインターフェイスで視覚的および高速でスケジュールされたジョブです。
window.buildShipChatWidget.config.urlプロパティを設定して、このワークフローエンドポイントURLをウィジェットにプラグインします。詳細については、ステップ3を参照してください。ウィジェットは、このURLにPOSTリクエストを行います。リクエスト本文は、ユーザーのメッセージと、使用するワークフローのその他のデータを含むオブジェクトになります。
{
"message" : " The user's message " ,
"threadId" : " A unique identifier for the conversation (learn more below) " ,
"timestamp" : " The timestamp of when the POST request was initiated "
...Other miscellaneous user data (learn more in the 'Config Properties' section below)
}次のセクションでは、各プロパティの詳細について詳しく知ることができます。
ウィジェットは、ワークフローの応答（ message ）とスレッドID（ threadId ）を含むJSONオブジェクトの形でエンドポイントからの応答を期待します。
{
"message" : " The bot's response " ,
"threadId" : " The unique identifier for the conversation (learn more below) "
}ストリーミングされた応答の場合、ウィジェットは上記のようにJSONオブジェクトを予想しませんが、代わりに最終的に応答メッセージに合わせて合計するチャンクのストリームを期待します。ウィジェットは、これらのチャンクが受信され、リアルタイムでメッセージを表示および更新するときに集約し、最終的に完全な応答で終わります。
threadId設定しますオプションで、応答を介してthreadIdを設定するには2つの方法があります。
応答ヘッダーを介して
応答に、スレッドIDが値としてキーx-thread-idを備えたヘッダーが含まれている場合、ウィジェットは自動的にそれをピックアップし、会話のthreadIdとして設定します（まだ設定されていない場合）。
注： x-thread-idヘッダーをクライアントウィジェットに公開するために、 Access-Control-Expose-Headersヘッダーを応答してください。
ストリーム自体を介して
エンドポイントがmessageとthreadIdで次の形式で応答した場合： message + x1f + threadId （ x1fがユニットセパレーター文字）、ウィジェットはストリームからthread IDを抽出し、会話のthreadIdとして設定します（まだ設定されていない場合）。例えば：
// Simulating what a streamed response might look like where
// message: "Hello world!"
// threadId: "tId_123"
readable . push ( "Hello " ) ;
readable . push ( "world!" ) ;
readable . push ( "x1f" + "tId_123" ) ; // No spaces between the end of the message, the unit separator character, and the beginning of the threadIdウィジェットは、 window.buildShipChatWidget.configオブジェクトに存在するプロパティを編集してカスタマイズできます。
| 財産 | タイプ | 説明 |
|---|---|---|
| window.buildshipchatwidget.config.url | 必須 | ユーザーがメッセージを送信したときにウィジェットがPOSTリクエストを行うエンドポイントのURL。エンドポイントは、リクエスト本体にJSONオブジェクトを期待し、ボットの応答とスレッドIDを含むJSONオブジェクトで応答する必要があります。 |
| window.buildshipchatwidget.config.threadid | オプション | 会話のためのユニークな識別子。これは、複数のメッセージ/セッションで会話のコンテキストを維持するために使用できます。設定されていない場合、ウィジェットはスレッドIDなしで最初のユーザーメッセージを送信します。その後、ワークフローを設計して、応答の一部としてスレッドIDを返す場合（リクエストと応答で説明されています）、ウィジェットは、スクリプトがロードされたままになるまで、会話の残りの部分に自動的に使用します - たとえば、ページが更新された場合、スレッドIDは破棄されます。注： threadIdプロパティが既に設定されている場合、応答で返されたスレッドIDは使用されません。 |
| window.buildshipchatwidget.config.user | オプション | ユーザーのデータを含むオブジェクト。これを使用して、ユーザーの名前、電子メール、またはワークフローが必要とする他のデータを送信できます。例： window.buildShipChatWidget.config.user = { name: "Some User", email: "[email protected]", // ...Other user data}; |
| window.buildshipchatwidget.config.widgettitle | オプション | ウィジェットのタイトル。これは、ウィジェットの上部に表示されます。デフォルトはChatbotになります。 |
| window.buildshipchatwidget.config.greetingmessage | オプション | ウィジェットが最初に開かれたときに（システムによって送信されたかのように）表示されるメッセージ。デフォルトでは、挨拶メッセージが表示されません。 |
| window.buildshipchatwidget.config.disableerroralert | オプション | URLが設定されていない場合、リクエストが失敗した場合などを無効にするエラーアラートは、デフォルトでfalseになります。 |
| window.buildshipchatwidget.config.closeonoutsideclick | オプション | ユーザーがウィジェットボディの外側をクリックすると、ウィジェットを閉じます。 falseに設定されている場合は、 close()メソッド（ window.buildShipChatWidgetオブジェクトで提供）を使用して、プログラムでウィジェットを閉じることができる（たとえば、ボタンに接続することで）必要があります。デフォルトはtrueです。 |
| window.buildshipchatwidget.config.openonload | オプション | ページの読み込みが終了すると、ウィジェットが自動的に開きます（ data-buildship-chat-widget-button属性がページに存在するボタンが必要です）。デフォルトはfalseになります。 |
| window.buildshipchatwidget.config.responseisastream | オプション | trueに設定されている場合、ウィジェットは応答がエンドポイントからストリーミングされることを期待します。エンドポイントは、最終的にエンドポイントの応答につながる一連のチャンクで応答する必要があります。ウィジェットは、メッセージを受け取って表示および更新するときにこれらのチャンクを集約し、最終的に完全な応答で終わります。詳細はこちらをご覧ください。デフォルトはfalseになります。 |
ウィジェットのスタイリングは、CSS変数やルールをオーバーライドすることでカスタマイズできます。 （変数とセレクターのリストについては、こちらをご覧ください）。
たとえば、変数は次のようにオーバーライドできます。
: root {
--buildship-chat-widget-primary-color : # 0000ff ;
}
/* Explicitly targeting the light theme is necessary in case the user's system theme is set to 'dark', but the body's `data-theme` attribute is set to `light` (perhaps via a theme toggle on the page). */
[ data-theme *= "light" ] {
...;
}どちらかの場合、ダークモードがアクティブになります。
ユーザーのシステムテーマはdark設定されています（すなわち@media (prefers-color-scheme: dark) true）、それがページが使用するものです。
ボディにはdata-theme属性がdark設定されています。
< body data-theme =" dark " > </ body >ダークモードのスタイルもオーバーライドできます。
@media ( prefers-color-scheme : dark) {
: root {
...;
}
}
[ data-theme *= "dark" ] {
...;
}フォントはボディから継承されます。
スクリプトがロードされると、 data-buildship-chat-widget-button属性のある要素を探し、それらの要素のいずれかがクリックされたときにウィジェットを開きます。
configオブジェクトに加えて、 window.buildShipChatWidgetオブジェクトは、直接呼び出すことができるopen() 、 close() 、およびinit()メソッドも公開します。
open()メソッドはクリックeventを受け入れ、 event.targetを使用して、フローティングUIを使用してウィジェットの位置を計算します。
close()メソッドはウィジェットを閉じます。
init()メソッドはウィジェットを初期化し、ウィンドウの読み込みが終了すると自動的に呼ばれます。必要に応じてウィジェットを再目的化するために手動で呼び出すことができます（特に、ルートの変更後にウィジェットを再目的化する必要があるSPAの場合に役立ちます）。
