UI 程式庫使用案例
使用 Azure 通訊服務 UI 連結庫中的元件和複合，在應用程式中建立通話和聊天體驗。
在複合項目中，會在您將複合項目整合至應用程式時直接內建並公開通話和聊天功能。 在 UI 元件中，通話和聊天功能是透過 UI 功能和基礎具狀態程式庫的組合來公開呈現。 若要充分利用這些功能，建議您搭配具狀態通話和聊天用戶端程式庫使用 UI 元件。
在 UI 程式庫 Storybook 中取得更多概念說明文件、快速入門和範例。
通話使用案例
| 區域 | 使用案例 |
|---|---|
| 通話類型 | 加入 Microsoft Teams 會議。 |
| 使用群組標識碼加入 Azure 通訊服務 呼叫。 | |
| 加入 Azure 通訊服務 會議室。 | |
| 啟動另一位 Azure 通訊服務 用戶的輸出呼叫。 | |
| 啟動電話號碼的輸出通話。 | |
| Teams 互通性 | 加入通話大廳。 |
| 顯示轉譯和錄製警示橫幅。 | |
| 通話控制項 | 將呼叫靜音並取消靜音。 |
| 在通話期間開啟和關閉視訊。 | |
| 開啟屏幕共用。 | |
| 結束呼叫。 | |
| 參與者資源庫 | 在方格上顯示遠程參與者。 |
| 讓視訊預覽可在本機使用者的通話中取得。 | |
| 當視訊關閉時，請讓預設虛擬人偶可供使用。 | |
| 在參與者資源庫中顯示共享畫面內容。 | |
| 通話設定 | 管理麥克風裝置。 |
| 管理相機裝置。 | |
| 管理喇叭裝置。 | |
| 讓用戶可檢查影片的本機預覽。 | |
| 參與者 | 顯示參與者名冊。 |
聊天使用案例
| 區域 | Azure 通訊服務 聊天 | Teams 互操作性聊天 |
|---|---|---|
| 聊天類型 | 加入 Azure 通訊服務 聊天對話。 | 加入Microsoft Teams 會議聊天。 |
| 聊天操作 | 發送和接收簡訊。 | 發送和接收簡訊。 |
| 傳送和接收 RTF 簡訊。* | 傳送和接收 RTF 簡訊。* | |
| - | 接收內嵌影像。 | |
| 傳送和接收檔案附件。 | 接收檔案附件。* | |
| 聊天事件 | 傳送和接收輸入指標。 | 傳送和接收輸入指標。** |
| 傳送和接收讀取回條。 | 傳送和接收讀取回條。 | |
| 顯示新增或移除參與者的時機。 | 顯示新增或移除參與者的時機。 | |
| 參與者 | 顯示參與者名冊。 | 顯示參與者名冊。 |
*傳送 RTF 簡訊和檔案附件支援目前為公開預覽狀態。 提供的預覽 API 和 SDK 並無服務等級協定。 建議您不要將其用於生產工作負載。 部分功能可能不受支援，或是在功能上有所限制。 如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用規定。
**Teams 使用者輸入事件的顯示名稱可能無法正確顯示。
支援的身分識別
若要初始化複合並驗證服務，用戶必須具有 Azure 通訊服務 身分識別。 如需詳細資訊，請參閱驗證 Azure 通訊服務以及快速入門：建立和管理存取權杖。
小組互通性
針對 Teams 互操作性案例，您可以使用 UI 連結庫複合，透過 Azure 通訊服務 將使用者新增至 Teams 會議。 若要啟用 Teams 互操作性，請使用通話複合或聊天複合中的預設功能。 您也可以使用UI元件來建置自訂體驗。
當您將通話和聊天新增至應用程式時，請記住，在參與者進入通話之前，無法初始化聊天用戶端。 在參與者被接納之後，您可以初始化聊天用戶端以加入會議聊天對話。 下圖示範此模式。
如果您使用 UI 元件來提供 Teams 互通性體驗，請先使用 UI 程式庫範例來建立體驗的關鍵要素：
- 大廳範例：範例大廳，參與者可以等候進入通話。
- 合規性橫幅：記錄通話時顯示使用者的範例橫幅。
- Teams 主題：讓UI連結庫元素看起來像Microsoft Teams的範例主題。
- 影像共用*：顯示 Azure 通訊服務 使用者如何接收Teams使用者所傳送影像的範例。
- 檔案共用*：顯示 Azure 通訊服務 使用者如何接收 Teams 使用者所傳送的檔案附件的範例。
自訂
使用 UI 程式庫模式來修改元件，以符合應用程式的外觀和風格。 自訂是 Azure 通訊服務 中複合和UI元件之間的主要差異。 複合項目的自訂選項較少，提供簡化的整合體驗。
下表比較用於自定義使用案例的複合和UI元件。
| 使用案例 | 複合項目 | UI 元件 |
|---|---|---|
| 使用 Fluent 型主題。 | X | X |
| 撰寫體驗版面配置。 | X | |
| 使用 CSS 樣式來修改樣式屬性。 | X | |
| 取代圖示。 | X | |
| 修改參與者資源庫配置。 | X | |
| 修改呼叫控件配置。 | X | X |
| 插入數據模型以修改使用者元數據。 | X | X |
可檢視性
UI 程式庫的狀態管理架構已分離，因此您可以直接存取具狀態的通話和聊天用戶端。 連結至具狀態用戶端以讀取狀態、處理事件，以及覆寫行為以傳遞至 UI 元件。
下表比較複合和UI元件是否有可觀察性使用案例。
| 使用案例 | 複合項目 | UI 元件 |
|---|---|---|
| 存取通話和聊天客戶端狀態。 | X | X |
| 存取及處理用戶端事件。 | X | X |
| 存取及處理UI事件。 | X | X |
建議架構
使用 Azure 通訊服務存取權杖，初始化複合項目和基礎元件。 請務必透過您管理的受信任服務，向 Azure 通訊服務取得存取權杖。 如需詳細資訊，請參閱快速入門：建立和管理存取權杖以及受信任的服務教學課程。
通話和聊天用戶端程式庫必須具有其加入的通話或聊天情境內容。 使用您自己的受信任服務，將內容傳播給用戶端。 例如，使用使用者存取令牌。
下表摘要說明將內容新增至客戶端連結庫所需的初始化和資源管理功能。
| Contoso 責任 | UI 程式庫責任 |
|---|---|
| 提供來自 Azure 的存取令牌。 | 傳遞提供的存取令牌來初始化元件。 |
| 提供重新整理函式。 | 使用開發人員提供的函式重新整理存取令牌。 |
| 擷取並傳遞通話或聊天的聯結資訊。 | 傳遞通話和聊天資訊以初始化元件。 |
| 擷取並傳遞任何自定義數據模型的用戶資訊。 | 將自定義數據模型傳遞至要轉譯的元件。 |
平台支援
| SDK | Windows | macOS | Ubuntu \(英文\) | Linux | Android | iOS |
|---|---|---|---|---|---|---|
| UI SDK | Chrome，* Microsoft Edge | Chrome，* Safari** | Chrome* | Chrome* | Chrome* | Safari** |
*支援目前版本的 Chrome 和上述兩個版本。
**支援 Safari 13.1 版和更新版本。 目前尚不支援 Safari macOS 的傳出影片，但 iOS 系統可提供支援。 只有桌面版 iOS 支援傳出螢幕畫面分享。
協助工具選項
將協助工具融入設計是 Microsoft 產品的共通原則。 UI 程式庫遵循此原則，且所有 UI 元件都適用於任何族群。
當地語系化
當地語系化是讓世界各地的使用者使用不同語言產品的關鍵。 UI 連結庫提供某些語言和功能的默認支援。 此支援包含由右至左的語言。 您可以提供專用的當地語系化檔案，以搭配 UI 程式庫使用。
已知問題
目前編輯現有訊息時，UI 連結庫不支援更新訊息類型。 將 RTF 格式新增至現有的郵件會將 HTML 樣式新增至文字內容。 由於訊息類型不會變更，因此結果可能是在訊息線程中顯示為純文本的 HTML 內容。
使用 CallComposite 和 ChatComposite Azure 通訊服務 UI 連結庫，在您的 iOS 和 Android 應用程式中建立通話體驗。 您可以使用幾行程式碼，輕鬆在應用程式中整合完整通話和聊天體驗。 Azure 通訊服務 中的複合 Azure 通訊服務 管理通話和聊天的整個生命週期，從設定到通話和聊天結束。
通話使用案例
使用 Azure 通訊服務 中的呼叫複合來建立這些使用案例。
| 區域 | 使用案例 |
|---|---|
| 通話類型 | 加入 Microsoft Teams 會議。 |
| 使用會議標識碼和密碼加入Microsoft Teams 會議。 | |
| 使用群組標識碼加入通話。 | |
| 使用會議室標識碼加入通話。 | |
| 撥打並接收 1：1 通話。 | |
| Teams 互通性 | 加入通話大廳。 |
| 顯示轉譯和錄製警示橫幅。 | |
| 承認或拒絕遊說者。 | |
| 隱藏式輔助字幕 | Teams 互操作性。 |
| 群組通話、會議室通話和 1：1 通話。 | |
| 參與者資源庫 | 在方格上顯示遠程參與者。 |
| 讓視訊預覽可在本機使用者的通話中取得。 | |
| 當視訊關閉時，請讓預設虛擬人偶可供使用。 | |
| 在參與者資源庫中顯示共享畫面內容。 | |
| 啟用參與者虛擬人偶自定義。 | |
| 顯示參與者名冊。 | |
| 通話管理 | 管理麥克風裝置。 |
| 管理相機裝置。 | |
| 管理喇叭裝置（有線或藍牙）。 | |
| 讓用戶可檢查影片的本機預覽。 | |
| 訂閱事件。 | |
| 通話控制項 | 將呼叫靜音並取消靜音。 |
| 在通話期間開啟或關閉視訊。 | |
| 結束呼叫。 | |
| 在音訊中斷後保留並繼續通話。 | |
| CallKit 和 TelecomManager 支援。 | |
| 自訂體驗 | 按鈕列自定義。 |
| 標題和副標題組態。 | |
| 啟用結束通話確認對話。 | |
| 略過安裝畫面。 |
通話整合
本節討論呼叫的整合。
小組互通性
針對 Teams 互操作性案例，您可以使用 UI 連結庫複合，透過 Azure 通訊服務 將使用者新增至 Teams 會議。 若要啟用 Teams 互通性，請使用複合式通話。 複合會管理加入 Teams 互通性通話的整個生命週期。
下圖顯示將來電者新增至 Teams 會議之前用戶體驗的範例。
會議室整合
Azure 通訊服務 為建置結構化交談的開發人員提供空間的概念，例如虛擬約會或虛擬活動。 會議室目前允許語音和視訊通話。
會議室是一個容器，可管理 Azure 通訊服務 用戶之間的活動。 會議室可讓應用程式開發人員更充分掌控誰可以加入通話、何時開會，以及他們共同作業的方式。 若要深入瞭解會議室，請參閱 概念檔。
在下列三個角色之一中使用會議室 API，邀請使用者加入會議室：
- 簡報者 （預設值）
- 學員
- 消費者
每個角色之間的差異在於在使用會議室通話 CallComposite 期間所擁有的功能。 虛擬會議室概觀會說明與每個角色相關聯的特定功能。
注意
會議室 API 可用來建立會議室、管理使用者，以及調整會議室的存留期。 會議室 API 是與 UI 連結庫分開的後端服務。
一對一通話和推播通知支援
UI 連結庫支援一對一的 VoIP 呼叫，以透過通訊標識元撥打使用者。 若要接收來電，UI 連結庫也支持註冊 PUSH 通知。 若要深入瞭解 Android 和 iOS 平臺的整合和使用 API，請參閱 進行一對一呼叫並接收 PUSH 通知。
電話撥接特色
有數個功能可供呼叫。
協助工具選項
協助工具是通話程式庫的關鍵焦點。 使用螢幕助讀程式來發出關於通話狀態的重要公告，並協助確保視覺受損的使用者在使用應用程式時可以有效地參與。
隱藏式輔助字幕
隱藏式輔助字幕可啟用各種案例，包括與 Teams 的互操作性、Azure 通訊服務 群組通話、會議室通話和一對一通話。 這項功能可確保使用者能夠遵循各種通話環境中的交談，增強輔助功能和使用者體驗。
用戶必須使用現用UI連結庫手動選取標題的語言，因為系統不會自動偵測口語。
如需隱藏式輔助字幕的詳細資訊，請參閱 檔 以檢閱說明和使用方針。 如果您想要直接在UI連結庫中設定隱藏式輔助字幕，請遵循教學 課程 以輕鬆設定。
事件
開發人員現在可以訂閱 屬性內的 CallComposite 事件。 透過這項功能，他們可以將接聽程式附加至整個呼叫生命週期中的特定事件。 這項增強功能提供更大的控制和自定義機會。 開發人員可以根據參與者加入或離開通話的參與者等事件觸發自定義動作。 他們也可以使用事件來記錄互動、動態更新使用者介面，或增強整體功能。
如需詳細資訊，請參閱 處理UI連結庫中的事件。
當地語系化
當地語系化是讓世界各地的使用者使用不同語言產品的關鍵。 UI 程式庫支援 12 種語言：英文、西班牙文、法文、德文、義大利文、日文、韓文、荷蘭文、葡萄牙文、俄文、土耳其文和中文。 此外也支援從右至左語言。 如需詳細資訊，請參閱 將當地語系化新增至您的應用程式。
多任務處理和圖片中模式
UI 連結庫支援通話畫面的圖片內嵌模式。 在通話中，用戶可以選取通話畫面上的 [上一頁] 按鈕，讓多任務返回上一個畫面。 如果啟用圖片內圖片模式，系統圖片內畫面會出現來電。 若要深入瞭解 Android 和 iOS 平臺的多任務處理和圖片內模式，以及 API 的使用方式，請參閱 使用 UI 連結庫開啟圖片中的圖片。
螢幕方向
UI 連結庫支援在連結庫體驗開始之前個別設定每個畫面的螢幕方向設定。 應用程式開發人員可以針對呼叫體驗設定固定方向，以配合其應用程式方向。 若要深入瞭解 Android 和 iOS 平台支援的方向清單和使用 API，請參閱 使用 UI 連結庫設定螢幕方向。
螢幕大小
調整 Azure 通訊服務 呼叫複合，以適應從5英吋到平板電腦大小的螢幕大小。 在複合式通話中使用分割模式和平板電腦模式，以取得動態參與者的名冊配置、提供檢視清晰度，並將焦點放在交談上。
| 分割模式 | 平板電腦模式 |
|---|---|
|
|
檢視資料插入
使用適用於行動原生平臺的UI連結庫，為本機和遠端參與者提供選項，以自定義他們在通話中以使用者身分顯示的方式。 本機參與者可以在開始通話時，選擇本機虛擬人偶、自定義顯示名稱，以及設定畫面上的導覽標題和副標題。 遠端使用者可以在加入會議時建立自訂的虛擬人偶。 如需詳細資訊，請參閱 在UI連結庫中插入自定義數據模型。
檢視共用內容
透過行動原生平臺的 UI 連結庫，當其他參與者在 Teams 通話期間共用其畫面時，通話參與者可以檢視共用內容。 遠端參與者可以使用開合手勢來放大或縮小通話中的分享內容。
OS 整合
與您的OS整合。
CallKit 支援
UI 連結庫支援 CallKit 整合來處理呼叫的 CallKit 互動。 若要深入瞭解 iOS 平臺的整合和使用 API，請參閱 將 CallKit 整合到 UI 連結庫。
TelecomManager 支援
UI 連結庫現在支援與 TelecomManager 整合，並允許處理呼叫保留和繼續函式。 若要深入瞭解 Android 平臺的整合和使用 API，請參閱 將 TelecomManager 整合到 UI 連結庫。
自訂通話體驗
您可以自定義通話體驗。
僅限音訊模式
UI 連結庫中的僅限音訊模式可讓參與者只使用其音訊加入通話，而不需共用或接收視訊。 這項功能用來節省頻寬並將盡可能提高隱私性。 啟用時，僅限音訊模式會自動停用傳送和接收數據流的視訊功能。 其會移除視訊相關控制項來調整 UI 以反映這項變更。 透過組態啟用 CallComposite 此模式。 如需詳細資訊，請參閱 僅限音訊的快速入門。
停用結束通話提示
當您開發整合呼叫功能的應用程式時，請務必確保順暢且直覺式的用戶體驗。 您可以在呼叫終止程式期間簡化用戶體驗的其中一個區域。 具體而言，開發人員可能會發現停用使用者想要結束通話時出現的左側通話確認提示會很有説明。 這項功能雖然有助於防止意外呼叫終止，有時可能會妨礙使用者體驗，尤其是在速度和效率至關重要的環境中。 如需詳細資訊，請參閱 停用通話確認。
快速節奏的通訊環境：在交易樓層、緊急電話中心或客戶服務中心等設定中，必須快速執行決策和行動。 確認呼叫終止的額外步驟可能會妨礙工作流程效率。
按鈕列自訂
此功能可讓開發人員將新動作新增至內容功能表，或移除按鈕列中的目前按鈕。 他們可以提供彈性來導入自定義動作，並根據特定應用程式需求量身打造使用者介面。
- 新增自定義按鈕：開發人員可以將新按鈕引入內容相關按鈕列，以觸發自定義動作。
- 拿掉現有的按鈕：開發人員可以移除不必要的默認按鈕，以簡化介面，例如相機、麥克風或音訊選取。
在實作這項功能期間，請考慮下列條件約束：
- 圖示和標籤：只會針對新動作新增圖示。 按鈕列圖示會保留預先定義的圖示，而且標籤應該簡潔，以符合功能表維度。
- 輔助功能考慮：開發人員應確定所有自定義按鈕都可存取，包括螢幕助讀程式的適當標籤。
| 移除按鈕 | 新增自訂動作 |
|---|---|
![示範底部列上 [移除] 按鈕的螢幕擷取畫面。](includes/media/ui-library-remove-button.png)
|
|
使用案例
- 自定義通話動作：商務應用程式可以新增自定義 報表問題 按鈕，讓使用者在通話期間直接回報技術問題。
- 商標和用戶體驗：企業應用程式可以移除與其使用案例無關的按鈕，並新增可增強用戶體驗的品牌按鈕。
為了確保呼叫體驗一致，我們建議您將 Fluent UI 圖示整合到專案中。 其可在 Fluent UI GitHub 存放庫取得。 如此一來，您的自定義圖示會符合屬性的設計 CallComposite ，並建立一個凝聚力和專業的外觀。
最佳作法
- 全新設計：避免過度擁擠關係型功能表欄。 僅新增對使用者體驗而言不可或缺的按鈕。
- 使用者測試：進行用戶測試，以確保自定義符合使用者需求，且不會混淆或壓倒使用者。
- 意見反應機制：新增報表問題之類的按鈕，可確保有健全的後端系統可用來處理所收集的意見反應。 重複使用 UI 連結庫預設所提供的機制。
如需詳細資訊，請參閱 自定義按鈕列。
跳過安裝畫面
UI 連結庫透過略過通話聯結體驗的設定畫面，提供加入呼叫的功能。 根據預設，您會瀏覽安裝畫面以加入通話。 在這裡，您會設定通話組態，例如相機開啟或關閉、麥克風開啟或關閉，以及加入通話前的音訊裝置選取。 此畫面需要由使用者進行互動才能加入通話，但部分使用者可能不需要此動作。 因此，我們提供跳過安裝畫面加入通話的功能，並提供通話設定 API。 如需詳細資訊，請參閱 略過安裝畫面功能。
主題和色彩
使用 iOS 和 Android 的 UI 連結庫呼叫複合來建立呼叫端體驗的自定義主題。 您可以彈性地自定義主要色彩，以便量身打造色彩配置，以符合您的特定品牌需求。 藉由調整主要色彩，您可以確保介面與品牌視覺身分識別整合。 您可以增強用戶體驗，同時維護應用程式之間的一致性。 如需詳細資訊，請參閱 建立您的主題。
| Android | iOS |
|---|---|
|
|
標題和子標題
使用UI連結庫來輸入自定義字串，讓您更輕鬆地量身打造呼叫介面，以符合您的特定需求。 您可以在設定階段和通話進行期間自訂通話的標題與子標題。
例如，在公司環境中，您可以設定標題以反映會議的議程和副標題，以指出公告。 對於客戶支援，代理程式可以使用標題來顯示查詢的性質，以提高清晰度和溝通。
在具有時間敏感討論的通話期間，您也可以使用副標題來顯示通話持續時間，以確保所有參與者都知道時間限制。
如需詳細資訊，請參閱 設定標題和副標題。
聊天使用案例
重要
此 Azure 通訊服務功能目前處於預覽狀態。
提供的預覽 API 和 SDK 並無服務等級協定。 建議您不要將其用於生產工作負載。 部分功能可能不受支援，或是在功能上有所限制。
如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用規定。
| 區域 | 使用案例 |
|---|---|
| 聊天類型 | 加入 Azure 通訊服務 聊天對話。 |
| 聊天操作 | 傳送聊天訊息。 |
| 接收聊天訊息。 | |
| 聊天事件 | 顯示輸入指標。 |
| 顯示讀取收據。 | |
| 顯示新增或移除參與者的時機。 | |
| 顯示聊天標題的變更。 |
靈活性
屬性 ChatComposite 的設計目的是要放入應用程式中的不同版面配置和檢視中。 例如，您可以選擇將聊天放在瀏覽檢視、強制響應檢視或其他檢視中。 屬性 ChatComposite 會自行調整，並確保用戶有順暢的體驗。
| 瀏覽檢視 | 強制響應檢視 |
|---|---|
|
|
支援的身分識別
若要初始化複合並驗證服務，用戶必須具有 Azure 通訊服務 身分識別。 如需詳細資訊，請參閱驗證 Azure 通訊服務以及快速入門：建立和管理存取權杖。
建議架構
使用 Azure 通訊服務存取權杖來初始化複合項目。 請務必透過您管理的受信任服務，向 Azure 通訊服務取得存取權杖。 如需詳細資訊，請參閱快速入門：建立和管理存取權杖以及受信任的服務教學課程。
通話和聊天用戶端程式庫必須具有其加入的通話情境內容。 使用您自己的受信任服務，將內容傳播給用戶端。 例如，使用使用者存取令牌。 下表摘要說明將內容新增至客戶端連結庫所需的初始化和資源管理功能。
| Contoso 責任 | UI 程式庫責任 |
|---|---|
| 提供來自 Azure 的存取令牌。 | 傳遞提供的存取令牌來初始化元件。 |
| 提供重新整理函式。 | 使用開發人員提供的函式重新整理存取令牌。 |
| 擷取並傳遞通話或聊天的聯結資訊。 | 傳遞通話和聊天資訊以初始化元件。 |
| 擷取並傳遞任何自定義數據模型的用戶資訊。 | 將自定義數據模型傳遞至要轉譯的元件。 |
平台支援
| 平台 | 版本 |
|---|---|
| iOS | iOS 14 和更新版本 |
| Android | API 21 和更新版本 |
疑難排解指南
針對語音或視訊通話進行疑難解答時，系統可能會要求您提供通話標識符。 此標識碼可用來識別 Azure 通訊服務呼叫。
若要擷取此通話標識碼，請使用通話畫面底部的動作列。 選取省略號按鈕以查看 共用診斷資訊。 使用此選項來共享支援小組追蹤任何問題所需的診斷資訊。
如需以程式設計方式存取呼叫標識符，請參閱 以程序設計方式取得偵錯資訊。
如需疑難解答的詳細資訊，請參閱 Azure 通訊服務 中的疑難解答。
| 通話畫面 | 診斷資訊功能表 | 共用通話標識碼 |
|---|---|---|
|
|
|