通話 SDK 概觀
透過 Azure 通訊服務，使用者瀏覽器、應用程式和服務可驅動語音和視訊通訊。 本頁面重點介紹呼叫用戶端 SDK，其可內嵌在網站和原生應用程式中。 本頁面提供呼叫用戶端功能的詳細描述，例如平台和瀏覽器支援資訊。 服務會使用呼叫自動化 API 以程式設計方式來管理和存取呼叫。 會議室 API 是選擇性的 Azure 通訊服務 API，可將其他功能 (例如角色和權限) 新增至語音或視訊通話。
若要使用通話 SDK 建置自己的使用者體驗，請查看呼叫快速入門或呼叫主圖範例。
如果想要獲得使用者體驗方面的協助，Azure 通訊服務 UI 程式庫提供開放原始碼生產就緒 UI 元件的集合，以供新增至應用程式中。 透過這組預先建置的控制項，可以使用 Microsoft 的 Fluent 設計語言建立美觀的通訊體驗。 若要深入了解 UI 程式庫，請造訪概觀網站 (部分機器翻譯)。
開始開發之後，請查看已知問題頁面，找到我們正在處理的 Bug。
SDK 連結
| 平台 | Web (JavaScript) | Windows (.NET) | iOS | Android | 其他 |
|---|---|---|---|---|---|
| 通話 | npm \(英文\) | NuGet (英文) | GitHub | Maven | |
| UI 程式庫 | npm \(英文\) | - | GitHub | GitHub | GitHub、Storybook |
主要功能
- 裝置管理和媒體 - 通話 SDK 提供繫結至音訊和視訊裝置的功能、編碼內容以透過通訊資料平面進行有效率的傳輸，以及將內容轉譯為您指定的輸出裝置和檢視。 也提供用於螢幕和應用程式共用的 API。
- PSTN - 通話 SDK 可以使用您在 Azure 入口網站或以程式設計方式取得的電話號碼，使用傳統的公用電話網絡來起始語音通話。 您也可以使用工作階段邊界控制器提供自己的號碼。
- Teams 會議和呼叫 - 通話 SDK 可加入 Teams 會議，並與 Teams 語音和視訊資料平面互動。
- 加密 - 通話 SDK 會加密流量並防止竄改線路。
- 定址 - Azure 通訊服務提供用來定址通訊端點的一般身分識別。 用戶端會使用這些身分識別向服務進行驗證，並互相通訊。 這些身分識別用於通話 API 中，可讓用戶端看見誰連線到通話 (名冊)。
- 使用者存取安全性
- 名冊控制項、排程控制項，以及使用者角色/權限，會透過 Virtual Rooms 強制執行。
- 使用者能夠起始新的呼叫或加入現有的呼叫的能力，可透過使用者身分識別和權杖來管理
- 通知 - 通話 SDK 提供 API，可讓用戶端收到連入通話的通知。 如果應用程式未在前景執行，您可使用模式來引發快顯通知 (「快顯通知 (toasts)」) 以通知使用者來電。
- 媒體統計資料 - 通話 SDK 提供 VoIP 和視訊通話的計量的完整深入解析。 有了這項資訊，開發人員可以更清楚地了解通話品質，並做出明智的決策，以進一步增強其通訊體驗。
- 視訊條件約束 - 通話 SDK 提供 API，使您能夠透過調整解析度和幀速率等參數，在視訊通話期間調整視訊品質和其他參數，從而支援不同視訊品質層次的不同通話情況
- 使用者面向診斷 (UFD) - 通話 SDK 提供了事件，其旨在深入解析可能會影響通話品質的基礎問題。 開發人員可以訂閱網路訊號弱或麥克風靜音等的觸發程序，確保他們一律知道影響通話的任何因素。
詳細功能
下列清單是目前 Azure 通訊服務的通話 SDK 中可用的一組功能。
| 功能群組 | 功能 | JS | Windows | Java (Android) | Objective-C (iOS) |
|---|---|---|---|---|---|
| 核心功能 | 在兩個使用者之間進行一對一通話 | ✔️ | ✔️ | ✔️ | ✔️ |
| 與兩個以上使用者 (最多 100 個使用者) 進行群組通話 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 將兩個使用者的一對一通話提升為兩個以上使用者的群組通話 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 在群組通話開始之後加入 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 邀請另一個 VoIP 參與者加入進行中的群組通話 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 中間通話控制 | 開啟/關閉您的影片 | ✔️ | ✔️ | ✔️ | ✔️ |
| 靜音/取消靜音麥克風 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 將其他參與者設為靜音 | ✔️ | ✔️1 | ✔️1 | ✔️1 | |
| 在相機之間切換 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 本機保留/取消保留 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 作用中喇叭 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 選擇通話的喇叭 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 選擇通話的麥克風 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 顯示參與者的狀態 閒置、接通通知、正在連線、已連線、保留、在大廳中，已中斷連線 |
✔️ | ✔️ | ✔️ | ✔️ | |
| 顯示通話的狀態 接通通知、連入、正在連線、鈴響中、已連線、保留、正在中斷連線、已中斷連線 |
✔️ | ✔️ | ✔️ | ✔️ | |
| 顯示參與者是否已靜音 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 顯示參與者離開通話的原因 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 螢幕共用 | 從應用程式內共用整個螢幕畫面 | ✔️ | ✔️2 | ✔️2 | ✔️2 |
| 共用特定應用程式 (從執行中應用程式的清單) | ✔️ | ✔️2 | ❌ | ❌ | |
| 從開啟的索引標籤清單共用 Web 瀏覽器索引標籤 | ✔️ | ||||
| 在螢幕共用期間共用系統音訊 | ✔️ | ❌ | ❌ | ❌ | |
| 參與者可以檢視遠端螢幕畫面分享 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 名冊 | 列出參與者 | ✔️ | ✔️ | ✔️ | ✔️ |
| 移除參與者 | ✔️ | ✔️ | ✔️ | ✔️ | |
| PSTN | 與 PSTN 參與者進行一對一通話 | ✔️ | ✔️ | ✔️ | ✔️ |
| 與 PSTN 參與者進行群組通話 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 將與 PSTN 參與者的一對一通話提升為群組通話 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 以 PSTN 參與者的身分從群組通話撥出 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 支援早期媒體 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 一般 | 使用音訊測試服務測試您的麥克風、喇叭和相機 (可以透過呼叫 8:echo123 取得) | ✔️ | ✔️ | ✔️ | ✔️ |
| 裝置管理 | 要求使用音訊和/或視訊的權限 | ✔️ | ✔️ | ✔️ | ✔️ |
| 取得相機清單 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 設定相機 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 取得選取的相機 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 取得麥克風清單 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 設定麥克風 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 取得選取的麥克風 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 取得喇叭清單 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 設定喇叭 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 取得選取的喇叭 | ✔️ | ✔️ | ❌3 | ❌3 | |
| 影片轉譯 | 在許多位置轉譯單一視訊 (本機相機或遠端串流) | ✔️ | ✔️ | ✔️ | ✔️ |
| 設定/更新調整模式 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 轉譯遠端視訊串流 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 視訊效果 | 背景模糊 | ✔️ | ✔️ | ✔️ | ✔️ |
| 自訂背景影像 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 音訊效果 (部分機器翻譯) | 音樂模式 (部分機器翻譯) | ❌ | ✔️ | ✔️ | ✔️ |
| 回音消除 | ❌ | ✔️ | ✔️ | ✔️ | |
| 雜訊抑制 | ✔️ | ✔️ | ✔️ | ✔️ | |
| 自動增益控制 (AGC) | ❌ | ✔️ | ✔️ | ✔️ | |
| 通知 4 | 推播通知 | ✔️ | ✔️ | ✔️ | ✔️ |
| 自訂內容 | 將使用者對使用者 (UUI) 或自訂標頭新增至呼叫 | ✔️ | ❌ | ❌ | ❌ |
1「將其他人靜音」功能目前為公開預覽版。
2 可以使用原始媒體 API 來實現共享畫面功能。 若要深入了解，請造訪原始媒體存取快速入門指南。
3 通話 SDK 沒有針對這些函式的明確 API，您應該改用 Android 和 iOS OS API 來實現。
4 原生平台中 TTL 的最大值為 180 天 (15,552,000 秒)，而最小值為 5 分鐘 (300 秒)。 CTE (自訂 Teams 端點)/M365 身分識別的 TTL 最大值為 24 小時 (86,400 秒)。
OS 和瀏覽器支援的 JavaScript 通話 SDK
下表顯示目前可用的一組受支援瀏覽器。 除非另有指示，否則我們支援瀏覽器的最新三個主要版本 (支援 Safari 的最新三個次要版本)。
| 平台 | Chrome | Safari | Edge | Firefox | Webview | Electron |
|---|---|---|---|---|---|---|
| Android | ✔️ | ❌ | ✔️ | ❌ | ✔️ | ❌ |
| iOS | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ |
| macOS | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ |
| Windows | ✔️ | ❌ | ✔️ | ✔️ | ❌ | ✔️ |
| Ubuntu/Linux | ✔️ | ❌ | ❌ | ❌ | ❌ | ❌ |
- iOS 或 Android 行動瀏覽器不支援傳出畫面共用。
- Firefox 支援處於公開預覽狀態。
- 目前，通話 SDK 僅支援 Android 上的 Android System WebView 和公開預覽版的 iOS WebView (WKWebView)。 其他作業系統平台上的其他類型的內嵌瀏覽器或 WebView 不受官方支援，例如 GeckoView、Chromium Embedded Framework (CEF) 和 Microsoft Edge WebView2。 在這些平台上執行 JavaScript 通話 SDK 的操作並未主動進行測試，其可能可以運作，也可能無法運作。
- Safari 上的 iOS 應用程式無法列舉/選取麥克風和喇叭裝置 (例如藍牙)。 只有 iOS 出現此問題，而作業系統會控制預設裝置選取。
呼叫用戶端 - 瀏覽器安全性模型
透過 HTTPS 使用 WebRTC
WebRTC API (例如 getUserMedia ) 需要透過 HTTPS 提供呼叫這些 API 的應用程式。 您可以使用 http://localhost 進行本機開發。
在 iframe 中內嵌通訊服務呼叫 SDK
各種瀏覽器中都已提供新的權限原則 (也稱為功能原則)。 此原則會控制應用程式如何透過跨原始 iframe 元素來存取裝置的相機和麥克風，進而影響呼叫案例。
如果要使用 iframe 來裝載來自不同網域的部分應用程式，必須將具有正確值的 allow 屬性新增至您的 iframe。
例如，此 iframe 允許相機和麥克風的存取：
<iframe allow="camera *; microphone *">
Android 通話 SDK 支援
- 支援 Android API 層級 21 或更高版本
- 支援 JAVA 7 或更高版本
- 支援 Android Studio 2.0
我們強烈建議您造訪支援的 Android 平台以識別和驗證您的案例
iOS 通話 SDK 支援
- 在建置時間支援 iOS 10.0+，以及在執行階段支援 iOS 12.0+
- Xcode 12.0+
- 支援 iPadOS 13.0+
通話持續時間上限
通話持續時間上限為 30 小時，達到 30 小時通話持續時間上限的參與者將會與通話中斷連線。
支援的傳入視訊串流數目
Azure 通訊服務的通話 SDK 支援下列串流設定：
| 限制 | Web | Windows/Android/iOS |
|---|---|---|
| 可以同時傳送的最大傳出本機串流數目 | 1 段影片和 1 個螢幕共用 | 1 段影片 + 1 個螢幕共用 |
| 可以同時轉譯的最大傳入遠端串流數目 | 在桌面瀏覽器上為 16 個視訊 + 1 個螢幕共用*，在網頁行動瀏覽器上為 4 個視訊 + 1 個螢幕共用 | 9 段影片 + 1 個螢幕共用 |
* 從 Azure 通訊服務 Web 通話 SDK 版本 1.16.3 開始，儘管通話 SDK 不會強制執行這些限制，但若超過限制，使用者可能會遇到效能降低的情況。 使用最佳視訊計數的 API 來判斷 Web 環境可支援的目前傳入視訊串流數目。 若要正確支援16個傳入影片，電腦至少應有16 GB RAM和4核心或更高的CPU，且不超過3年
支援的視訊解析度
Azure 通訊服務通話 SDK 會在通話期間自動調整視訊和螢幕共用串流的解析度。
注意
解析度可能會因通話中的參與者數目、用戶端可用的頻寬量、轉譯遠端視訊串流和其他整體通話參數的本機參與者的硬體功能而有所不同。
Azure 通訊服務通話 SDK 支援傳送下列影片解析度
| 最大視訊解析度 | WebJS | iOS | Android | Windows |
|---|---|---|---|---|
| 傳送視訊 | 720P | 720P | 720P | 1080P |
| 傳送螢幕共用 | 1080P | 1080P | 1080P | 1080P |
| 接收遠端視訊串流或螢幕共用 | 1080P | 1080P | 1080P | 1080P |
通話支援上的參與者數目
- 群組通話、會議室或 Teams + ACS 通話最多可容納 350 位使用者。
- 通話規模達到 100 位以上參與者，系統只會顯示開啟相機的前 4 位最主要說話者。
- 當通話中的人數超過 100 位時，可檢視的傳入視訊呈現數會從 4x4 (16 個傳入視訊) 自動下降至 2x2 (4 個傳入視訊)。
- 當使用者人數低於 100 位時，支援的傳入影片數目會恢復為 4x4 (16 個傳入影片)。
通話 SDK 逾時
下列逾時適用於通訊服務通話 SDK：
| 動作 | 逾時 (單位秒) |
|---|---|
| 重新連線/移除參與者 | 60 |
| 從通話 (開始/停止視訊或螢幕共用) 新增或移除新形式 | 40 |
| 通話轉接作業逾時 | 60 |
| 1：1 通話建立逾時 | 85 |
| 群組通話建立逾時 | 85 |
| PSTN 通話建立逾時 | 115 |
| 將 1：1 通話升階為群組通話逾時 | 115 |
下一步
如需詳細資訊，請參閱下列文章：
- 熟悉一般通話流程
- 深入了解通話類型
- 深入了解呼叫自動化 API，可讓您建置以伺服器為基礎的通話工作流程，以路由和控制用戶端應用程式的呼叫。
- 規劃您的 PSTN 解決方案