GSS-WebChat

整合 BotFramework-WebChat 的 webchat-es5.js 並客製其它功能，讓大家可以輕鬆將 webchat 功能整合到現有的 Web Application 之中。

BotFramework-WebChat 從 4.8 開始，開放自訂語系文字，所以 GSS-WebChat 從 3.1 開始支援，並之後不再客製 WebChat.js，詳細做法請參考 samples。

Browser suppor

• 所有支援 ES5 的瀏覽器(ex. IE 11)，詳細請參考 compatibility table。

Changes

爲了符合未來更多的客製需求，所以對 GSS-WebChat 進行了重構，原本的一些參數與方法會有所調整，請參考以下項目：

• GSSWebChat
  • createBotChatUI 改名爲 createMinimizableWebChat
  • 新增 createBasicWebChat, clearStorage
  • 移動 WebChatToggleStateObservable 至 WebChatAPI
• WebChatAPI
  • 由 BotChatUI 改名而來
  • clearSession 移至 GSSWebChat 並改名爲 clearStorage
  • getMessageNotifyCount 改名爲 getMessageUnreadCount
  • 新增 ActionObservable, ConnectFulfilledObservable, createMessageMutationObserver, isWebChatVisible, notifyUserAlreadyRead
• WebChatConfig.WebChatOptions
  • 移除 actionSubscribe 參數，改爲自行呼叫 WebChatAPI.ActionObservable.subscribe
  • 移除 domMutationSubscribe 參數，改爲自行呼叫 WebChatAPI.createMessageMutationObserver

How to use

1. 下載專案後，用 browser 開啓 index.html 即可操作。
2. 如果想知道 GSS-WebChat 有提供哪些功能，可以參考 samples。
3. 如果想知道如何將 GSS-WebChat 整合進去你的專案，可以參考 初始化(JS)。
4. 如果你的專案是 React，可以參考 初始化(React版)。

How to build

1. 使用 VSCode 打開專案
2. 下指令 npm install
3. 下指令 npx webpack
4. 成功的話，就會建立出 dist\gss-webchat.js 檔案

How to set up a local development environment

1. 安裝 Bot Connector
2. 執行 Bot (可以使用 Sample Bot)
3. 將 Bot 資料設定至 Bot Connector config
4. 執行 Bot Connector
5. 將 Bot Connector Domain 設定至 WebChat config directLineOptions.domain (如下列 code)
6. 執行 WebChat

directLineOptions: {
    domain: 'http://localhost:3000'
}

Features

• 未讀訊息
  • 歷史訊息
    • 載入歷史訊息後，如果有未讀訊息的部分，會將 scrollbar 移動到未讀訊息的 Tag。
  • MinimizableWebChat 關閉（縮小）狀態
    • webchat 關閉（縮小）狀態下，如果有 bot 訊息進來，除了 webchat button 會有訊息數量通知之外，打開 webchat 時，也會將 scrollbar 移動到未讀訊息的 Tag。（不論原本 scrollbar 的位置在哪裡）

Limits

• 目前僅供 create 一個 WebChat 在 html body 中。

GSSWebChat

在載入 GSS-WebChat.js 之後，即可在 window 底下找到 GSSWebChat 變數，所有 WebChat 的方法與物件都會在 GSSWebChat 這個 namespace 底下。

| Property | Description | |-----------------------------------------------|-------------| | createBasicWebChat | render 一個基本的 WebChat (BasicWebChat) 在指定的 element 中，並回傳 WebChat API。 | | createMinimizableWebChat | render 一個可縮小的 WebChat (MinimizableWebChat) 在自動生成的 element 中，並回傳 WebChat API。 | | clearStorage | WebChat 會使用到 Web Storage，這個方法只會清除 WebChat 使用到的部分。 |

WebChat API

透過 GSSWebChat.createWebChat 建立 WebChat 之後，此 create method 會回傳該 WebChat (ex. MinimizableWebChat) 可以使用的 API。

| Property | Description | |-----------------------------------------------|-------------| | ActionObservable | subscribe WebChat 所有的 Action。 | | ConnectFulfilledObservable | subscribe WebChat 狀態爲連線完成的時候。 | | WebChatToggleStateObservable | subscribe MinimizableWebChat open/close 的狀態改變。 | | createMessageMutationObserver | 建立一個訊息(message)的 DOM tree mutation Observer。 | | isWebChatVisible | return a boolean. true: visible, false: invisible | | getWatermark | 取得目前流水號（watermark）。 | | addMembers | 發送 ConversationUpdate 給 Bot 來新增成員。 | | removeMembers | 發送 ConversationUpdate 給 Bot 來刪除成員。 | | sendEvent | 發送 Event 給 Bot。 | | sendMessage | 發送 Message 給 Bot。 | | setLanguage | 設定 WebChat 語系。 | | setSendBox | 設定 WebChat 文字輸入欄位的文字。 | | notifyUserAlreadyRead | 發送 Event 給 Bot Connector，告知 User 已讀取訊息。（一般使用下，不需要主動呼叫這個方法） | | openWebChat | 開啓（放大） MinimizableWebChat 視窗。 | | closeWebChat | 關閉（縮小） MinimizableWebChat 視窗。 | | startConversation | 讓 MinimizableWebChat 開始連線。 | | endConversation | 讓 MinimizableWebChat 結束連線。 | | getMessageUnreadCount | 取得 MinimizableWebChat 關閉（縮小）狀態下的訊息未讀數量。 |

WebChat API 相關參數請參考這裡

Samples

以下列出 GSSWebChat 常見的使用範例。

| Sample Name | Description | Link | |-------------------------------|-------------|------| | Getting started | | | | 初始化(JS) | 示範如何在一般 Web Application 中加入 MinimizableWebChat | Demo | | 初始化(React) | 示範如何在 React app 中加入 MinimizableWebChat | Demo | | 使用 polling 方式連線 | WebChat 預設是用 webSocket 的方式跟 Bot Connector 連線，這裏示範用 polling 的方式來跟 Bot Connector 連線 | Demo | | 透過後端來取得 WebChat 連線 token | WebChat 連線 token 預設是由前端呼叫 Bot Connector API 取得，若是想由後端取得，可由後端來呼叫 API 取得 token 後再傳給 WebChat | | 修改語系預設內容 | 示範如何修改 WebChat 語系預設的內容 | Demo | | 保留對話紀錄 | 示範如何在關掉 Browser 之後，在下次開啓 WebChat 時，也有之前的對話記錄 | Demo | |||| | Styling, and customization | | | | 調整 WebChat 預設的 style | 示範如何調整 WebChat 的外觀，例如 User/Bot 頭像、對話等等 | Demo | | 客製化卡片樣式 | 示範如何客製化 webchat render 卡片的樣式 | Demo | | 設定 MinimizableWebChat 的 header | 示範如何在 MinimizableWebChat header 加入 icon 與文字 |Demo | | 設定 MinimizableWebChat 關閉（縮小）狀態下，button 靠邊 | 示範如何讓 MinimizableWebChat 在關閉（縮小）狀態下，可以讓 button 靠邊減少佔用螢幕右下角的面積 | Demo | | 客製化上傳按鈕 | 示範如何客製化上傳按鈕打開的內容 | Demo | | 新增 GSS-WebChat icon | 示範如何在客製 GSS-WebChat 時，新增 icon 來使用 | | | 客製訊息回饋功能 | 示範如何客製訊息回饋功能，提供 User 回饋 Bot 訊息是否有用 | Demo | |||| | API | | | | WebChat 的事件處理 | 示範如何使用 ActionObservable/ConnectFulfilledObservable 來訂閱想要關注的事件 | Demo | | WebChat 的對話 DOM 處理 | 示範如何使用 createMessageMutationObserver 來對 WebChat 的對話 DOM 套入其它 UI framework（例如：kendo UI) | Demo | | MinimizableWebChat 視窗開啟/關閉監控 | 示範如何監控 MinimizableWebChat 視窗開啓（放大）/關閉（縮小）狀態的改變 |Demo | | 紀錄使用者的操作 | 示範如何使用 sendAnalytics 紀錄使用者在 WebChat 上的操作 |Demo | |||| | Features | | | | 未讀訊息通知 | 展示 MinimizableWebChat 在關閉（縮小）狀態的時候，當有新的訊息傳送過來時，MinimizableWebChat 如何提醒使用者 |Demo |

Troubleshooting

WebChat 講話沒回應

流程爲 WebChat -> BotConnector -> Bot -> BotConnector -> WebChat

1. 先確認訊息是否有到 BotConnector
   • 訊息發送會送出 Request，看是否發送成功，如果發送失敗，請確認安裝環境是否有問題。
   • BotConnector 收到訊息後會記錄到 DB DialogHistory Table，看看是否有該 User 發送的訊息記錄，如果沒有記錄，請確認資料庫連線及設定是否有問題。
     • 如果是使用 Sqlite，請確認資料夾讀寫權限已設定完成。
2. 確認訊息是否有到 Bot
   • Bot 需要自行處理。(ex. log)
3. 確認 Bot 是否有回覆訊息到 BotConnector
   • 一樣可以看 DB DialogHistory Table 記錄。
4. 最後 WebChat 還是沒收到訊息
   • 看 console 是否有 error。
   • 走 websocket 的話，確認 websocket 是否有通。
     • 如果是 IIS，請確認是否有啓用 WebSocket 服務。
     • 確認 BotConnector Server WebSocket 是否有通，如果 Server 有，但 Client 連不到，可能是防火牆問題。
   • 走 polling 的話，確認是否有定期發送 request 拿訊息，request 是否發送成功。