使用者面向的診斷

發行項
03/20/2024

在 Azure 通訊服務中使用通話時，您可能會遇到對客戶造成影響的問題。為了協助解決此問題，Azure 通訊服務提供名為「使用者面向診斷」(UFD) 的功能，可用來檢查通話的各種屬性以判斷問題的可能成因。使用者面向診斷是接連引發的事件，可能表示因某項根本問題 (網路不穩定、使用者的麥克風靜音) 而導致使用者的體驗不佳。使用者面向診斷引發後，您應考慮將意見反應提供給終端使用者，指出他們可能有某項根本問題。不過，使用者面向診斷輸出僅供參考，且呼叫堆疊不會根據引發的使用者面向診斷進行任何變更。

診斷值

以下是使用者面向的可用診斷內容：

網路值

名稱	描述	可能值	使用案例	風險降低步驟
NoNetwork	沒有可用的網路。	- 當通話因為沒有網路可用而無法啟動時，會設為 `True`。 - 當有 ICE 候選項目存在時，請設定，會設為 `False`。	裝置未連線至網路。	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路最佳化一節。
networkRelaysNotReachable	網路問題。	- 當網路有限制，因而不允許您連線到 Azure 通訊服務轉送時，會設為 `True`。 - 在進行新通話時，會設為 `False`。	在通話期間，WiFi 訊號時好時壞。	請確保防火牆規則和網路路由允許用戶端連線到 Microsoft TURN 伺服器。如需詳細資訊，請參閱防火牆設定一節。
networkReconnect	連線已遺失，我們正在重新連線到網路。	- 當網路中斷連線時，會設為`Bad` - 當媒體傳輸連線中斷時，會設為 `Poor` - 在連線上新的工作階段時，會設為 `Good`。	低頻寬，無網際網路	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。
networkReceiveQuality	與傳入串流品質相關的指標。	- 在接收串流時若發生嚴重問題，會設為 `Bad`。 - 在接收串流時若發生輕微問題，會設為 `Poor`。 - 在接收串流時若未發生問題，會設為 `Good`。	低頻寬	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。建議終端使用者關閉其相機，以節省可用的網際網路頻寬。
networkSendQuality	與傳出串流品質相關的指標。	- 在傳送串流時若發生嚴重問題，會設為 `Bad`。 - 在傳送串流時若發生輕微問題，會設為 `Poor`。 - 在傳送串流時若未發生問題，會設為 `Good`。	低頻寬	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。同時也建議終端使用者關閉其相機，以節省可用的網際網路頻寬。

音訊值

名稱	描述	可能值	使用案例	風險降低步驟
noSpeakerDevicesEnumerated	使用者的系統上沒有音訊輸出裝置 (喇叭)。	- 當系統上沒有喇叭裝置但支援喇叭選取時，會設為 `True`。 - 當系統上至少有一個喇叭裝置且支援喇叭選取時，會設為 `False`。	所有喇叭都未插入	值設為 `True` 時，請考慮提供視覺通知給終端使用者，告知目前的通話工作階段沒有可用的喇叭。
speakingWhileMicrophoneIsMuted	在靜音時說話。	- 當本機麥克風靜音但本機使用者正在說話時，會設為 `True`。 - 當本機使用者停止說話或取消麥克風靜音時，會設為 `False`。 * 注意：Safari 目前不支援此選項，因為音訊層級樣本取自 WebRTC 統計資料。	在通話期間，將您的麥克風設為靜音，並對其說話。	值設為 `True` 時，請考慮為終端使用者提供視覺通知，告知他們可能正在交談而未察覺音訊已靜音。
noMicrophoneDevicesEnumerated	使用者系統上沒有音訊擷取裝置 (麥克風)	- 當系統上沒有麥克風裝置時，會設為 `True`。 - 當系統上至少有一個麥克風裝置時，會設為 `False`。	在通話期間所有麥克風都未插入。	值設為 `True` 時，請考慮為終端使用者提供視覺通知，告知其目前的通話工作階段沒有麥克風。如需詳細資訊，請參閱從裝置管理員啟用麥克風一節。
microphoneNotFunctioning	麥克風無法運作。	- 當我們無法開始傳送本機音訊串流，因為麥克風裝置可能已在系統中停用，或是其他程序正在使用時，會設為 `True`。這個 UFD 大約需要 10 秒的時間才會引發。 - 當麥克風開始再次成功傳送音訊串流時，會設為 `False`。	沒有可用的麥克風，系統中的麥克風存取已停用	值設為 `True` 時，請為終端使用者提供視覺通知，告知其麥克風發生問題。
microphoneMuteUnexpectedly	麥克風靜音	- 當麥克風意外進入靜音狀態時，會設為 `True`。 - 當麥克風開始成功傳送音訊串流時，會設為 `False`	系統將麥克風靜音。大多數情況發生在使用者在行動裝置上使用 Azure 通訊服務通話，而有電話打進來時。在大部分情況下，作業系統會將 Azure 通訊服務通話靜音，讓使用者可以接聽電話。	值設為 `True` 時，請為終端使用者提供視覺通知，告知由於有來電，其通話已靜音。如需詳細資訊，請參閱如何以最佳方式處理 OS 將 Azure 通訊服務通話靜音一節。
microphonePermissionDenied	macOS 的裝置音量很小或幾乎沒有聲音。	- 當系統設定 (音訊) 拒絕音訊權限時，會設為 `True`。 - 在成功取得串流時設為 `False`。注意：此診斷僅適用於 macOS。	[設定] 中已停用麥克風權限。	值設為 `True` 時，請為終端使用者提供視覺通知，告知他們沒有為 Azure 通訊服務通話啟用使用麥克風的權限。

相機值

名稱	描述	可能值	使用案例	風險降低步驟
cameraFreeze	相機停止產生畫面超過 5 秒。	- 當本機視訊串流凍結時，會設為 `True`。此診斷表示遠端會在畫面上看到您的視訊凍結，或表示遠端參與者未在其畫面上轉譯您的視訊。 - 當凍結結束時且使用者可以依正常方式查看您的視訊時，會設為 `False`。	相機在通話期間遺失，或網路不佳導致相機凍結。	值設為 `True` 時，請考慮為終端使用者提供通知，告知遠端參與者網路可能狀況不佳 (可能建議他們關閉相機以節省頻寬)。如需詳細資訊，請參閱網路頻寬需求一節，了解 Azure 通訊服務通話所需的網際網路能力。
cameraStartFailed	一般的相機失敗。	- 當我們無法開始傳送本機視訊，因為相機裝置可能已在系統中停用，或是其他程序正在使用時，會設為 `True`。 - 當所選的相機裝置再次成功傳送本機視訊時，會設為 `False`。	相機失敗	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機無法啟動。
cameraStartTimedOut	相機處於不良狀態的常見案例。	- 若相機裝置在開始傳送視訊串流時逾時，會設為 `True`。 - 當所選的相機裝置再次成功傳送本機視訊時，會設為 `False`。	相機失敗	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機可能發生問題。 (當值設回 `False`，請移除通知)。
cameraPermissionDenied	相機權限在設定中遭拒。	- 當系統設定 (視訊) 拒絕相機權限時，會設為 `True`。 - 在成功取得串流時設為 `False`。注意：此診斷僅適用於 macOS Chrome。	相機權限在設定中遭到停用。	值設為 `True` 時，請為終端使用者提供視覺通知，告知他們沒有為 Azure 通訊服務通話啟用使用相機的權限。
cameraStoppedUnexpectedly	相機故障	- 當相機意外進入停止狀態時，會設為 `True`。 - 當相機開始再次成功傳送視訊串流時，會設為 `False`。	檢查相機是否正常運作。	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機可能發生問題。 (當值設回 `False`，請移除通知)。

其他值

名稱	描述	可能值	使用案例	風險降低步驟
screenshareRecordingDisabled	[設定] 中的喜好設定拒絕系統畫面共用。	- 當系統設定 (共用) 拒絕畫面共用權限時，會設為 `True`。 - 在成功取得串流時設為 `False`。注意：此診斷僅適用於 macOS Chrome。	[設定] 中已停用螢幕錄製。	值設為 `True` 時，請為終端使用者提供視覺通知，告知他們沒有為 Azure 通訊服務通話啟用共用螢幕的權限。
capturerStartFailed	系統螢幕共用失敗。	- 當無法開始擷取畫面時，會設為 `True`。 - 當擷取螢幕可順利啟動時，會設為 `False`。		值設為 `True` 時，請為終端使用者提供視覺通知，告知共用其畫面時可能發生問題。 (當值設回 `False` 時，請移除通知)。
capturerStoppedUnexpectedly	系統螢幕共用故障	- 當螢幕擷取器意外進入停止狀態時，會設為 `True`。 - 當螢幕擷取器開始再次成功擷取時，會設為 `False`。	檢查螢幕共用是否正常運作	值設為 `True` 時，請為終端使用者提供視覺通知，告知可能發生問題而導致畫面共用停止。 (當值設回 `False`，請移除通知)。

存取診斷

使用者面向診斷是核心 Call API 的擴充功能，可讓您診斷作用中的通話。

const userFacingDiagnostics = call.feature(Features.UserFacingDiagnostics);

使用者面向診斷事件

訂閱 diagnosticChanged 事件，以監視任何使用者面向的診斷變更。

/**
 *  Each diagnostic has the following data:
 * - diagnostic is the type of diagnostic, e.g. NetworkSendQuality, DeviceSpeakWhileMuted, etc...
 * - value is DiagnosticQuality or DiagnosticFlag:
 *     - DiagnosticQuality = enum { Good = 1, Poor = 2, Bad = 3 }.
 *     - DiagnosticFlag = true | false.
 * - valueType = 'DiagnosticQuality' | 'DiagnosticFlag'
 */
const diagnosticChangedListener = (diagnosticInfo: NetworkDiagnosticChangedEventArgs | MediaDiagnosticChangedEventArgs) => {
    console.log(`Diagnostic changed: ` +
        `Diagnostic: ${diagnosticInfo.diagnostic}` +
        `Value: ${diagnosticInfo.value}` +
        `Value type: ${diagnosticInfo.valueType}`);

    if (diagnosticInfo.valueType === 'DiagnosticQuality') {
        if (diagnosticInfo.value === DiagnosticQuality.Bad) {
            console.error(`${diagnosticInfo.diagnostic} is bad quality`);

        } else if (diagnosticInfo.value === DiagnosticQuality.Poor) {
            console.error(`${diagnosticInfo.diagnostic} is poor quality`);
        }

    } else if (diagnosticInfo.valueType === 'DiagnosticFlag') {
        if (diagnosticInfo.value === true) {
            console.error(`${diagnosticInfo.diagnostic}`);
        }
    }
};

userFacingDiagnostics.network.on('diagnosticChanged', diagnosticChangedListener);
userFacingDiagnostics.media.on('diagnosticChanged', diagnosticChangedListener);

取得最新的使用者面向診斷

取得最新引發的診斷值。如果診斷未定義，這是因為診斷值從未受到引發。

const latestNetworkDiagnostics = userFacingDiagnostics.network.getLatest();

console.log(
  `noNetwork: ${latestNetworkDiagnostics.noNetwork.value}, ` +
    `value type = ${latestNetworkDiagnostics.noNetwork.valueType}`
);

console.log(
  `networkReconnect: ${latestNetworkDiagnostics.networkReconnect.value}, ` +
    `value type = ${latestNetworkDiagnostics.networkReconnect.valueType}`
);

console.log(
  `networkReceiveQuality: ${latestNetworkDiagnostics.networkReceiveQuality.value}, ` +
    `value type = ${latestNetworkDiagnostics.networkReceiveQuality.valueType}`
);

const latestMediaDiagnostics = userFacingDiagnostics.media.getLatest();

console.log(
  `speakingWhileMicrophoneIsMuted: ${latestMediaDiagnostics.speakingWhileMicrophoneIsMuted.value}, ` +
    `value type = ${latestMediaDiagnostics.speakingWhileMicrophoneIsMuted.valueType}`
);

console.log(
  `cameraStartFailed: ${latestMediaDiagnostics.cameraStartFailed.value}, ` +
    `value type = ${latestMediaDiagnostics.cameraStartFailed.valueType}`
);

console.log(
  `microphoneNotFunctioning: ${latestMediaDiagnostics.microphoneNotFunctioning.value}, ` +
    `value type = ${latestMediaDiagnostics.microphoneNotFunctioning.valueType}`
);

診斷值

以下是使用者面向的可用診斷內容：

網路值

名稱	描述	可能值	使用案例	風險降低步驟
networkUnavailable	沒有可用的網路。	- 當通話因為沒有網路可用而無法啟動時，會設為 `True`。 - 當有 ICE 候選項目存在時，請設定，會設為 `False`。	裝置未連線至網路。	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路最佳化一節。
networkRelaysUnreachable	網路問題。	- 當網路有限制，因而不允許您連線到 Azure 通訊服務轉送時，會設為 `True`。 - 在進行新通話時，會設為 `False`。	在通話期間，WiFi 訊號時好時壞。	請確保防火牆規則和網路路由允許用戶端連線到 Microsoft TURN 伺服器。如需詳細資訊，請參閱防火牆設定一節。
networkReconnectionQuality	連線已遺失，我們正在重新連線至網路。	- 當網路中斷連線時，會設為`Bad` - 當媒體傳輸連線中斷時，會設為 `Poor` - 在連線上新的工作階段時，會設為 `Good`。	低頻寬，無網際網路	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。
networkReceiveQuality	與傳入串流品質相關的指標。	- 在接收串流時若發生嚴重問題，會設為 `Bad`。 - 在接收串流時若發生輕微問題，會設為 `Poor`。 - 在接收串流時若未發生問題，會設為 `Good`。 - 只有在通話中有作用中的音訊流程時 (這表示參與者已主動說話一段時間)，才會顯示。	低頻寬	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。建議終端使用者關閉其相機，以節省可用的網際網路頻寬。
networkSendQuality	與傳出串流品質相關的指標。	- 在傳送串流時若發生嚴重問題，會設為 `Bad`。 - 在傳送串流時若發生輕微問題，會設為 `Poor`。 - 在傳送串流時若未發生問題，會設為 `Good`。 - 類似於接收品質診斷，只有在通話中有作用中的音訊流程時 (這表示參與者已主動說話一段時間)，才會顯示。但是，這僅適用於一對一通話，因為需使用對方的資訊來驗證品質。對方必須傳達已接收的資料。	低頻寬	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。同時也建議終端使用者關閉其相機，以節省可用的網際網路頻寬。

音訊值

名稱	描述	可能值	使用案例	風險降低步驟
noSpeakerDevicesAvailable	使用者的系統上沒有音訊輸出裝置 (喇叭)。	- 當系統上沒有喇叭裝置但支援喇叭選取時，會設為 `True`。 - 當系統上至少有一個喇叭裝置且支援喇叭選取時，會設為 `False`。	所有喇叭都未插入	值設為 `True` 時，請考慮提供視覺通知給終端使用者，告知目前的通話工作階段沒有可用的喇叭。
speakingWhileMicrophoneIsMuted	在靜音時說話。	- 當本機麥克風靜音但本機使用者正在說話時，會設為 `True`。 - 當本機使用者停止說話或取消麥克風靜音時，會設為 `False`。 - 如果在一段特定時間內沒有任何使用者動作，因而觸發此診斷事件，此事件可以自動停用，以避免雜訊並提供更理想的使用者體驗。有新的靜音動作發生時，將會再次加以啟用。	在通話期間，將您的麥克風設為靜音，並對其說話。	值設為 `True` 時，請考慮為終端使用者提供視覺通知，告知他們可能正在交談而未察覺音訊已靜音。
noMicrophoneDevicesAvailable	使用者系統上沒有音訊擷取裝置 (麥克風)	- 當系統上沒有麥克風裝置時，會設為 `True`。 - 當系統上至少有一個麥克風裝置時，會設為 `False`。	在通話期間所有麥克風都未插入。	值設為 `True` 時，請考慮為終端使用者提供視覺通知，告知其目前的通話工作階段沒有麥克風。如需詳細資訊，請參閱從裝置管理員啟用麥克風一節。
microphoneNotFunctioning	麥克風無法運作。	- 當我們無法開始傳送本機音訊串流，因為麥克風裝置可能已在系統中停用，或是其他程序正在使用時，會設為 `True`。這個 UFD 大約需要 10 秒的時間才會引發。 - 當麥克風開始再次成功傳送音訊串流時，會設為 `False`。	沒有可用的麥克風，系統中的麥克風存取已停用	值設為 `True` 時，請為終端使用者提供視覺通知，告知其麥克風發生問題。
microphoneMuteUnexpectedly	麥克風靜音	- 當麥克風意外進入靜音狀態時，會設為 `True`。 - 當麥克風開始成功傳送音訊串流時，會設為 `False`	系統將麥克風靜音。大多數情況發生在使用者在行動裝置上使用 Azure 通訊服務通話，而有電話打進來時。在大部分情況下，作業系統會將 Azure 通訊服務通話靜音，讓使用者可以接聽電話。	值設為 `True` 時，請為終端使用者提供視覺通知，告知由於有來電，其通話已靜音。如需詳細資訊，請參閱如何以最佳方式處理 OS 將 Azure 通訊服務通話靜音一節。
microphonePermissionDenied	macOS 的裝置音量很小或幾乎沒有聲音。	- 當系統設定 (音訊) 拒絕音訊權限時，會設為 `True`。 - 在成功取得串流時設為 `False`。注意：此診斷僅適用於 macOS。	[設定] 中已停用麥克風權限。	值設為 `True` 時，請為終端使用者提供視覺通知，告知他們沒有為 Azure 通訊服務通話啟用使用麥克風的權限。

相機值

名稱	描述	可能值	使用案例	風險降低步驟
cameraFrozen	相機停止產生畫面超過 5 秒。	- 當本機視訊串流凍結時，會設為 `True`。此診斷表示遠端會在畫面上看到您的視訊凍結，或表示遠端參與者未在其畫面上轉譯您的視訊。 - 當凍結結束時且使用者可以依正常方式查看您的視訊時，會設為 `False`。	相機在通話期間遺失，或網路不佳導致相機凍結。	值設為 `True` 時，請考慮為終端使用者提供通知，告知遠端參與者網路可能狀況不佳 (可能建議他們關閉相機以節省頻寬)。如需詳細資訊，請參閱網路頻寬需求一節，了解 Azure 通訊服務通話所需的網際網路能力。
cameraStartFailed	一般的相機失敗。	- 當我們無法開始傳送本機視訊，因為相機裝置可能已在系統中停用，或是其他程序正在使用時，會設為 `True`。 - 當所選的相機裝置再次成功傳送本機視訊時，會設為 `False`。	相機失敗	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機無法啟動。
cameraStartTimedOut	相機處於不良狀態的常見案例。	- 若相機裝置在開始傳送視訊串流時逾時，會設為 `True`。 - 當所選的相機裝置再次成功傳送本機視訊時，會設為 `False`。	相機失敗	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機可能發生問題。 (當值設回 `False`，請移除通知)。
cameraPermissionDenied	相機權限在設定中遭拒。	- 當系統設定 (視訊) 拒絕相機權限時，會設為 `True`。 - 在成功取得串流時設為 `False`。注意：此診斷僅適用於 macOS Chrome。	相機權限在設定中遭到停用。	值設為 `True` 時，請為終端使用者提供視覺通知，告知他們沒有為 Azure 通訊服務通話啟用使用相機的權限。
cameraStoppedUnexpectedly	相機故障	- 當相機意外進入停止狀態時，會設為 `True`。 - 當相機開始再次成功傳送視訊串流時，會設為 `False`。	檢查相機是否正常運作。	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機可能發生問題。 (當值設回 `False`，請移除通知)。

僅原生

名稱	描述	可能值	使用案例	風險降低步驟
speakerVolumeIsZero	裝置 (喇叭) 的音量為零。	- 當喇叭音量為零時，會設為 `True`。 - 當喇叭音量不是零時，會設為 `False`。	未聽到通話參與者的音訊。	值設為 `True` 時，表示您可能誤將音量設為最低 (零)。
speakerMuted	喇叭裝置已靜音。	- 當喇叭裝置靜音時，會設為 `True`。 - 當喇叭裝置未靜音時，會設為 `False`。	未聽到通話參與者的音訊。	值設為 `True` 時，表示您可能誤將喇叭靜音。
speakerBusy	喇叭已在使用中。裝置正以獨佔模式使用，或裝置正以共用模式使用，而來電者要求以獨佔模式使用裝置。	- 當喇叭裝置串流擷取逾時 (音訊) 時，會設為 `True`。 - 當喇叭擷取成功時，會設為 `False`。	未透過喇叭聽到通話參與者的音訊。	值設為 `True` 時，請為終端使用者提供視覺通知，讓他們能夠檢查另一個應用程式是否使用喇叭，並嘗試加以關閉。
speakerNotFunctioning	喇叭無法運作 (無法初始化音訊裝置用戶端，或裝置進入非作用中狀態達 5 秒以上)	- 當喇叭無法使用，或裝置串流擷取逾時 (音訊) 時，會設為 `True`。 - 當喇叭擷取成功時，會設為 `False`。	未透過喇叭聽到通話參與者的音訊。	請嘗試檢查喇叭裝置的狀態。
microphoneBusy	麥克風已在使用中。裝置正以獨佔模式使用，或裝置正以共用模式使用，而來電者要求以獨佔模式使用裝置。	- 當麥克風裝置串流擷取逾時 (音訊) 時，會設為 `True`。 - 當麥克風擷取成功時，會設為 `False`。	通話中的其他參與者聽不到您的音訊。	值設為 `True` 時，請為終端使用者提供視覺通知，讓他們能夠檢查另一個應用程式是否使用麥克風，並嘗試加以關閉。

存取診斷

使用者面向診斷是核心 Call API 的擴充功能，可讓您診斷作用中的通話。

DiagnosticsCallFeature diagnosticsCallFeature = call.feature(Features.LOCAL_USER_DIAGNOSTICS);

使用者面向診斷事件

取得功能物件，並將接聽程式新增至診斷事件。

DiagnosticsCallFeature diagnosticsCallFeature = call.feature(Features.LOCAL_USER_DIAGNOSTICS);

/* NetworkDiagnostic */
FlagDiagnosticChangedListener listener = (FlagDiagnosticChangedEvent args) -> {
  Boolean mediaValue = args.getValue();
  // Handle new value for no network diagnostic.
};

NetworkDiagnostics networkDiagnostics = diagnosticsCallFeature.getNetworkDiagnostics();
networkDiagnostics.addOnNetworkUnreachableChangedListener(listener);

// To remove listener for network quality event
networkDiagnostics.removeOnNetworkUnreachableChangedListener(listener);

// Quality Diagnostics
DiagnosticsCallFeature diagnosticsCallFeature = call.feature(Features.LOCAL_USER_DIAGNOSTICS);
QualityDiagnosticChangedListener listener = (QualityDiagnosticChangedEvent args) -> {
  DiagnosticQuality diagnosticQuality = args.getValue();
  // Handle new value for network reconnect diagnostic.
};

NetworkDiagnostics networkDiagnostics = diagnosticsCallFeature.getNetworkDiagnostics();
networkDiagnostics.addOnNetworkReconnectionQualityChangedListener(listener);

// To remove listener for media flag event
networkDiagnostics.removeOnNetworkReconnectionQualityChangedListener(listener);

/* MediaDiagnostic */
DiagnosticsCallFeature diagnosticsCallFeature = call.feature(Features.LOCAL_USER_DIAGNOSTICS);
FlagDiagnosticChangedListener listener = (FlagDiagnosticChangedEvent args) -> {
  Boolean mediaValue = args.getValue();
  // Handle new value for speaker not functioning diagnostic.
};

MediaDiagnostics mediaDiagnostics = diagnosticsCallFeature.getMedia();
mediaDiagnostics.addOnIsSpeakerNotFunctioningChangedListener(listener);

// To remove listener for media flag event
mediaDiagnostics.removeOnIsSpeakerNotFunctioningChangedListener(listener);

取得最新的使用者面向診斷

取得目前的通話中最新引發的診斷值。如果我們仍未收到診斷的值，則會擲回例外狀況。

DiagnosticsCallFeature diagnosticsCallFeature = call.feature(Features.LOCAL_USER_DIAGNOSTICS);
NetworkDiagnostics networkDiagnostics = diagnosticsCallFeature.getNetwork();
MediaDiagnostics mediaDiagnostics = diagnosticsCallFeature.getMedia();

NetworkDiagnosticValues latestNetwork = networkDiagnostics.getLatestDiagnostics();
Boolean lastNetworkValue = latestNetwork.isNetworkUnavailable(); // null if there isn't a value for this diagnostic.
DiagnosticQuality lastReceiveQualityValue = latestNetwork.getNetworkReceiveQuality(); //  UNKNOWN if there isn't a value for this diagnostic.

MediaDiagnosticValues latestMedia = networkDiagnostics.getLatestDiagnostics();
Boolean lastSpeakerNotFunctionValue = latestMedia.isSpeakerNotFunctioning(); // null if there isn't a value for this diagnostic.

// Use the last values ...

診斷值

以下是使用者面向的可用診斷內容：

網路值

名稱	描述	可能值	使用案例	風險降低步驟
networkUnavailable	沒有可用的網路。	- 當通話因為沒有網路可用而無法啟動時，會設為 `True`。 - 當有 ICE 候選項目存在時，請設定，會設為 `False`。	裝置未連線至網路。	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路最佳化一節。
networkRelaysUnreachable	網路問題。	- 當網路有限制，因而不允許您連線到 Azure 通訊服務轉送時，會設為 `True`。 - 在進行新通話時，會設為 `False`。	在通話期間，WiFi 訊號時好時壞。	請確保防火牆規則和網路路由允許用戶端連線到 Microsoft TURN 伺服器。如需詳細資訊，請參閱防火牆設定一節。
networkReconnectionQuality	連線已遺失，我們正在重新連線至網路。	- 當網路中斷連線時，會設為`Bad` - 當媒體傳輸連線中斷時，會設為 `Poor` - 在連線上新的工作階段時，會設為 `Good`。	低頻寬，無網際網路	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。
networkReceiveQuality	與傳入串流品質相關的指標。	- 在接收串流時若發生嚴重問題，會設為 `Bad`。 - 在接收串流時若發生輕微問題，會設為 `Poor`。 - 在接收串流時若未發生問題，會設為 `Good`。 - 只有在通話中有作用中的音訊流程時 (這表示參與者已主動說話一段時間)，才會顯示。	低頻寬	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。建議終端使用者關閉其相機，以節省可用的網際網路頻寬。
networkSendQuality	與傳出串流品質相關的指標。	- 在傳送串流時若發生嚴重問題，會設為 `Bad`。 - 在傳送串流時若發生輕微問題，會設為 `Poor`。 - 在傳送串流時若未發生問題，會設為 `Good`。 - 類似於接收品質診斷，只有在通話中有作用中的音訊流程時 (這表示參與者已主動說話一段時間)，才會顯示。但是，這僅適用於一對一通話，因為需使用對方的資訊來驗證品質。對方必須傳達已接收的資料。	低頻寬	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。同時也建議終端使用者關閉其相機，以節省可用的網際網路頻寬。

音訊值

名稱	描述	可能值	使用案例	風險降低步驟
noSpeakerDevicesAvailable	使用者的系統上沒有音訊輸出裝置 (喇叭)。	- 當系統上沒有喇叭裝置但支援喇叭選取時，會設為 `True`。 - 當系統上至少有一個喇叭裝置且支援喇叭選取時，會設為 `False`。	所有喇叭都未插入	值設為 `True` 時，請考慮提供視覺通知給終端使用者，告知目前的通話工作階段沒有可用的喇叭。
speakingWhileMicrophoneIsMuted	在靜音時說話。	- 當本機麥克風靜音但本機使用者正在說話時，會設為 `True`。 - 當本機使用者停止說話或取消麥克風靜音時，會設為 `False`。 - 如果在一段特定時間內沒有任何使用者動作，因而觸發此診斷事件，此事件可以自動停用，以避免雜訊並提供更理想的使用者體驗。有新的靜音動作發生時，將會再次加以啟用。	在通話期間，將您的麥克風設為靜音，並對其說話。	值設為 `True` 時，請考慮為終端使用者提供視覺通知，告知他們可能正在交談而未察覺音訊已靜音。
noMicrophoneDevicesAvailable	使用者系統上沒有音訊擷取裝置 (麥克風)	- 當系統上沒有麥克風裝置時，會設為 `True`。 - 當系統上至少有一個麥克風裝置時，會設為 `False`。	在通話期間所有麥克風都未插入。	值設為 `True` 時，請考慮為終端使用者提供視覺通知，告知其目前的通話工作階段沒有麥克風。如需詳細資訊，請參閱從裝置管理員啟用麥克風一節。
microphoneNotFunctioning	麥克風無法運作。	- 當我們無法開始傳送本機音訊串流，因為麥克風裝置可能已在系統中停用，或是其他程序正在使用時，會設為 `True`。這個 UFD 大約需要 10 秒的時間才會引發。 - 當麥克風開始再次成功傳送音訊串流時，會設為 `False`。	沒有可用的麥克風，系統中的麥克風存取已停用	值設為 `True` 時，請為終端使用者提供視覺通知，告知其麥克風發生問題。
microphoneMuteUnexpectedly	麥克風靜音	- 當麥克風意外進入靜音狀態時，會設為 `True`。 - 當麥克風開始成功傳送音訊串流時，會設為 `False`	系統將麥克風靜音。大多數情況發生在使用者在行動裝置上使用 Azure 通訊服務通話，而有電話打進來時。在大部分情況下，作業系統會將 Azure 通訊服務通話靜音，讓使用者可以接聽電話。	值設為 `True` 時，請為終端使用者提供視覺通知，告知由於有來電，其通話已靜音。如需詳細資訊，請參閱如何以最佳方式處理 OS 將 Azure 通訊服務通話靜音一節。
microphonePermissionDenied	macOS 的裝置音量很小或幾乎沒有聲音。	- 當系統設定 (音訊) 拒絕音訊權限時，會設為 `True`。 - 在成功取得串流時設為 `False`。注意：此診斷僅適用於 macOS。	[設定] 中已停用麥克風權限。	值設為 `True` 時，請為終端使用者提供視覺通知，告知他們沒有為 Azure 通訊服務通話啟用使用麥克風的權限。

相機值

名稱	描述	可能值	使用案例	風險降低步驟
cameraFrozen	相機停止產生畫面超過 5 秒。	- 當本機視訊串流凍結時，會設為 `True`。此診斷表示遠端會在畫面上看到您的視訊凍結，或表示遠端參與者未在其畫面上轉譯您的視訊。 - 當凍結結束時且使用者可以依正常方式查看您的視訊時，會設為 `False`。	相機在通話期間遺失，或網路不佳導致相機凍結。	值設為 `True` 時，請考慮為終端使用者提供通知，告知遠端參與者網路可能狀況不佳 (可能建議他們關閉相機以節省頻寬)。如需詳細資訊，請參閱網路頻寬需求一節，了解 Azure 通訊服務通話所需的網際網路能力。
cameraStartFailed	一般的相機失敗。	- 當我們無法開始傳送本機視訊，因為相機裝置可能已在系統中停用，或是其他程序正在使用時，會設為 `True`。 - 當所選的相機裝置再次成功傳送本機視訊時，會設為 `False`。	相機失敗	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機無法啟動。
cameraStartTimedOut	相機處於不良狀態的常見案例。	- 若相機裝置在開始傳送視訊串流時逾時，會設為 `True`。 - 當所選的相機裝置再次成功傳送本機視訊時，會設為 `False`。	相機失敗	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機可能發生問題。 (當值設回 `False`，請移除通知)。
cameraPermissionDenied	相機權限在設定中遭拒。	- 當系統設定 (視訊) 拒絕相機權限時，會設為 `True`。 - 在成功取得串流時設為 `False`。注意：此診斷僅適用於 macOS Chrome。	相機權限在設定中遭到停用。	值設為 `True` 時，請為終端使用者提供視覺通知，告知他們沒有為 Azure 通訊服務通話啟用使用相機的權限。
cameraStoppedUnexpectedly	相機故障	- 當相機意外進入停止狀態時，會設為 `True`。 - 當相機開始再次成功傳送視訊串流時，會設為 `False`。	檢查相機是否正常運作。	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機可能發生問題。 (當值設回 `False`，請移除通知)。

僅原生

名稱	描述	可能值	使用案例	風險降低步驟
speakerVolumeIsZero	裝置 (喇叭) 的音量為零。	- 當喇叭音量為零時，會設為 `True`。 - 當喇叭音量不是零時，會設為 `False`。	未聽到通話參與者的音訊。	值設為 `True` 時，表示您可能誤將音量設為最低 (零)。
speakerMuted	喇叭裝置已靜音。	- 當喇叭裝置靜音時，會設為 `True`。 - 當喇叭裝置未靜音時，會設為 `False`。	未聽到通話參與者的音訊。	值設為 `True` 時，表示您可能誤將喇叭靜音。
speakerBusy	喇叭已在使用中。裝置正以獨佔模式使用，或裝置正以共用模式使用，而來電者要求以獨佔模式使用裝置。	- 當喇叭裝置串流擷取逾時 (音訊) 時，會設為 `True`。 - 當喇叭擷取成功時，會設為 `False`。	未透過喇叭聽到通話參與者的音訊。	值設為 `True` 時，請為終端使用者提供視覺通知，讓他們能夠檢查另一個應用程式是否使用喇叭，並嘗試加以關閉。
speakerNotFunctioning	喇叭無法運作 (無法初始化音訊裝置用戶端，或裝置進入非作用中狀態達 5 秒以上)	- 當喇叭無法使用，或裝置串流擷取逾時 (音訊) 時，會設為 `True`。 - 當喇叭擷取成功時，會設為 `False`。	未透過喇叭聽到通話參與者的音訊。	請嘗試檢查喇叭裝置的狀態。
microphoneBusy	麥克風已在使用中。裝置正以獨佔模式使用，或裝置正以共用模式使用，而來電者要求以獨佔模式使用裝置。	- 當麥克風裝置串流擷取逾時 (音訊) 時，會設為 `True`。 - 當麥克風擷取成功時，會設為 `False`。	通話中的其他參與者聽不到您的音訊。	值設為 `True` 時，請為終端使用者提供視覺通知，讓他們能夠檢查另一個應用程式是否使用麥克風，並嘗試加以關閉。

存取診斷

使用者面向診斷是核心 Call API 的擴充功能，可讓您診斷作用中的通話。

let userFacingDiagnostics = self.call?.feature(Features.localUserDiagnostics)

使用者面向診斷事件

實作 media 和 network 診斷來源的委派。分別是 MediaDiagnosticsDelegate 和 NetworkDiagnosticsDelegate。

extension CallObserver: MediaDiagnosticsDelegate {
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsCameraFrozen args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsSpeakerMuted args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsCameraStartFailed args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsSpeakerVolumeZero args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsSpeakerNotFunctioning args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsCameraPermissionDenied args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsMicrophoneNotFunctioning args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsCameraStartTimedOut args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsMicrophoneMutedUnexpectedly args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsZeroSpeakerDevicesAvailable args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...                            
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsZeroMicrophoneDevicesAvailable args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsSpeakingWhileMicrophoneIsMuted args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsSpeakerBusy args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func mediaDiagnostics(_ mediaDiagnostics: MediaDiagnostics,
                        didChangeIsMicrophoneBusy args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
}

extension CallObserver: NetworkDiagnosticsDelegate {
  func networkDiagnostics(_ networkDiagnostics: NetworkDiagnostics,
                          didChangeIsNetworkRelaysUnreachable args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func networkDiagnostics(_ networkDiagnostics: NetworkDiagnostics,
                          didChangeNetworkReconnectionQuality args: DiagnosticQualityChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func networkDiagnostics(_ networkDiagnostics: NetworkDiagnostics,
                          didChangeNetworkSendQuality args: DiagnosticQualityChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func networkDiagnostics(_ networkDiagnostics: NetworkDiagnostics,
                          didChangeIsNetworkUnavailable args: DiagnosticFlagChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
    
  func networkDiagnostics(_ networkDiagnostics: NetworkDiagnostics,
                          didChangeNetworkReceiveQuality args: DiagnosticQualityChangedEventArgs) {
    let newValue = args.value
    // Handle the diagnostic event value changed...
  }
}

保存對 media 和 network 診斷的參考，並設定委派對象來接聽事件。

self.mediaDiagnostics = userFacingDiagnostics?.media
self.networkDiagnostics = userFacingDiagnostics?.network
self.mediaDiagnostics?.delegate = self.callObserver
self.networkDiagnostics?.delegate = self.callObserver

注意

如果您已透過 SDK 啟用 CallKit 或在應用程式中實作 CallKit 整合，向 CallKit 回報靜音狀態可能會導致 OS 使應用程式基於隱私原因失去對麥克風的掌控權，這會導致 didIsSpeakingWhileMicrophoneIsMuted 事件無法如預期運作，因為我們無法從麥克風裝置擷取輸入偵測到使用者在說話。

取得最新的使用者面向診斷

取得最新引發的診斷值。如果我們仍未收到診斷的值，則會傳回 nil 或 .unknown。

let lastSpeakerNotFunctionValue = self.mediaDiagnostics.latest.isSpeakerNotFunctioning // Boolean?
let lastNetworkRelayNotReachableValue = self.networkDiagnostics.latest.networkRelaysUnreachable // Boolean?
let lastReceiveQualityValue = self.networkDiagnostics.latest.networkReceiveQuality // DiagnosticQuality (.good, .poor, .bad)
// or .unknown if there isn't a diagnostic for this.

診斷值

以下是使用者面向的可用診斷內容：

網路值

名稱	描述	可能值	使用案例	風險降低步驟
networkUnavailable	沒有可用的網路。	- 當通話因為沒有網路可用而無法啟動時，會設為 `True`。 - 當有 ICE 候選項目存在時，請設定，會設為 `False`。	裝置未連線至網路。	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路最佳化一節。
networkRelaysUnreachable	網路問題。	- 當網路有限制，因而不允許您連線到 Azure 通訊服務轉送時，會設為 `True`。 - 在進行新通話時，會設為 `False`。	在通話期間，WiFi 訊號時好時壞。	請確保防火牆規則和網路路由允許用戶端連線到 Microsoft TURN 伺服器。如需詳細資訊，請參閱防火牆設定一節。
networkReconnectionQuality	連線已遺失，我們正在重新連線至網路。	- 當網路中斷連線時，會設為`Bad` - 當媒體傳輸連線中斷時，會設為 `Poor` - 在連線上新的工作階段時，會設為 `Good`。	低頻寬，無網際網路	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。
networkReceiveQuality	與傳入串流品質相關的指標。	- 在接收串流時若發生嚴重問題，會設為 `Bad`。 - 在接收串流時若發生輕微問題，會設為 `Poor`。 - 在接收串流時若未發生問題，會設為 `Good`。 - 只有在通話中有作用中的音訊流程時 (這表示參與者已主動說話一段時間)，才會顯示。	低頻寬	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。建議終端使用者關閉其相機，以節省可用的網際網路頻寬。
networkSendQuality	與傳出串流品質相關的指標。	- 在傳送串流時若發生嚴重問題，會設為 `Bad`。 - 在傳送串流時若發生輕微問題，會設為 `Poor`。 - 在傳送串流時若未發生問題，會設為 `Good`。 - 類似於接收品質診斷，只有在通話中有作用中的音訊流程時 (這表示參與者已主動說話一段時間)，才會顯示。但是，這僅適用於一對一通話，因為需使用對方的資訊來驗證品質。對方必須傳達已接收的資料。	低頻寬	請確定通話具有可靠的網際網路連線，能夠維持語音電話。如需詳細資訊，請參閱網路頻寬需求一節。同時也建議終端使用者關閉其相機，以節省可用的網際網路頻寬。

音訊值

名稱	描述	可能值	使用案例	風險降低步驟
noSpeakerDevicesAvailable	使用者的系統上沒有音訊輸出裝置 (喇叭)。	- 當系統上沒有喇叭裝置但支援喇叭選取時，會設為 `True`。 - 當系統上至少有一個喇叭裝置且支援喇叭選取時，會設為 `False`。	所有喇叭都未插入	值設為 `True` 時，請考慮提供視覺通知給終端使用者，告知目前的通話工作階段沒有可用的喇叭。
speakingWhileMicrophoneIsMuted	在靜音時說話。	- 當本機麥克風靜音但本機使用者正在說話時，會設為 `True`。 - 當本機使用者停止說話或取消麥克風靜音時，會設為 `False`。 - 如果在一段特定時間內沒有任何使用者動作，因而觸發此診斷事件，此事件可以自動停用，以避免雜訊並提供更理想的使用者體驗。有新的靜音動作發生時，將會再次加以啟用。	在通話期間，將您的麥克風設為靜音，並對其說話。	值設為 `True` 時，請考慮為終端使用者提供視覺通知，告知他們可能正在交談而未察覺音訊已靜音。
noMicrophoneDevicesAvailable	使用者系統上沒有音訊擷取裝置 (麥克風)	- 當系統上沒有麥克風裝置時，會設為 `True`。 - 當系統上至少有一個麥克風裝置時，會設為 `False`。	在通話期間所有麥克風都未插入。	值設為 `True` 時，請考慮為終端使用者提供視覺通知，告知其目前的通話工作階段沒有麥克風。如需詳細資訊，請參閱從裝置管理員啟用麥克風一節。
microphoneNotFunctioning	麥克風無法運作。	- 當我們無法開始傳送本機音訊串流，因為麥克風裝置可能已在系統中停用，或是其他程序正在使用時，會設為 `True`。這個 UFD 大約需要 10 秒的時間才會引發。 - 當麥克風開始再次成功傳送音訊串流時，會設為 `False`。	沒有可用的麥克風，系統中的麥克風存取已停用	值設為 `True` 時，請為終端使用者提供視覺通知，告知其麥克風發生問題。
microphoneMuteUnexpectedly	麥克風靜音	- 當麥克風意外進入靜音狀態時，會設為 `True`。 - 當麥克風開始成功傳送音訊串流時，會設為 `False`	系統將麥克風靜音。大多數情況發生在使用者在行動裝置上使用 Azure 通訊服務通話，而有電話打進來時。在大部分情況下，作業系統會將 Azure 通訊服務通話靜音，讓使用者可以接聽電話。	值設為 `True` 時，請為終端使用者提供視覺通知，告知由於有來電，其通話已靜音。如需詳細資訊，請參閱如何以最佳方式處理 OS 將 Azure 通訊服務通話靜音一節。
microphonePermissionDenied	macOS 的裝置音量很小或幾乎沒有聲音。	- 當系統設定 (音訊) 拒絕音訊權限時，會設為 `True`。 - 在成功取得串流時設為 `False`。注意：此診斷僅適用於 macOS。	[設定] 中已停用麥克風權限。	值設為 `True` 時，請為終端使用者提供視覺通知，告知他們沒有為 Azure 通訊服務通話啟用使用麥克風的權限。

相機值

名稱	描述	可能值	使用案例	風險降低步驟
cameraFrozen	相機停止產生畫面超過 5 秒。	- 當本機視訊串流凍結時，會設為 `True`。此診斷表示遠端會在畫面上看到您的視訊凍結，或表示遠端參與者未在其畫面上轉譯您的視訊。 - 當凍結結束時且使用者可以依正常方式查看您的視訊時，會設為 `False`。	相機在通話期間遺失，或網路不佳導致相機凍結。	值設為 `True` 時，請考慮為終端使用者提供通知，告知遠端參與者網路可能狀況不佳 (可能建議他們關閉相機以節省頻寬)。如需詳細資訊，請參閱網路頻寬需求一節，了解 Azure 通訊服務通話所需的網際網路能力。
cameraStartFailed	一般的相機失敗。	- 當我們無法開始傳送本機視訊，因為相機裝置可能已在系統中停用，或是其他程序正在使用時，會設為 `True`。 - 當所選的相機裝置再次成功傳送本機視訊時，會設為 `False`。	相機失敗	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機無法啟動。
cameraStartTimedOut	相機處於不良狀態的常見案例。	- 若相機裝置在開始傳送視訊串流時逾時，會設為 `True`。 - 當所選的相機裝置再次成功傳送本機視訊時，會設為 `False`。	相機失敗	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機可能發生問題。 (當值設回 `False`，請移除通知)。
cameraPermissionDenied	相機權限在設定中遭拒。	- 當系統設定 (視訊) 拒絕相機權限時，會設為 `True`。 - 在成功取得串流時設為 `False`。注意：此診斷僅適用於 macOS Chrome。	相機權限在設定中遭到停用。	值設為 `True` 時，請為終端使用者提供視覺通知，告知他們沒有為 Azure 通訊服務通話啟用使用相機的權限。
cameraStoppedUnexpectedly	相機故障	- 當相機意外進入停止狀態時，會設為 `True`。 - 當相機開始再次成功傳送視訊串流時，會設為 `False`。	檢查相機是否正常運作。	值設為 `True` 時，請為終端使用者提供視覺通知，告知其相機可能發生問題。 (當值設回 `False`，請移除通知)。

僅原生

名稱	描述	可能值	使用案例	風險降低步驟
speakerVolumeIsZero	裝置 (喇叭) 的音量為零。	- 當喇叭音量為零時，會設為 `True`。 - 當喇叭音量不是零時，會設為 `False`。	未聽到通話參與者的音訊。	值設為 `True` 時，表示您可能誤將音量設為最低 (零)。
speakerMuted	喇叭裝置已靜音。	- 當喇叭裝置靜音時，會設為 `True`。 - 當喇叭裝置未靜音時，會設為 `False`。	未聽到通話參與者的音訊。	值設為 `True` 時，表示您可能誤將喇叭靜音。
speakerBusy	喇叭已在使用中。裝置正以獨佔模式使用，或裝置正以共用模式使用，而來電者要求以獨佔模式使用裝置。	- 當喇叭裝置串流擷取逾時 (音訊) 時，會設為 `True`。 - 當喇叭擷取成功時，會設為 `False`。	未透過喇叭聽到通話參與者的音訊。	值設為 `True` 時，請為終端使用者提供視覺通知，讓他們能夠檢查另一個應用程式是否使用喇叭，並嘗試加以關閉。
speakerNotFunctioning	喇叭無法運作 (無法初始化音訊裝置用戶端，或裝置進入非作用中狀態達 5 秒以上)	- 當喇叭無法使用，或裝置串流擷取逾時 (音訊) 時，會設為 `True`。 - 當喇叭擷取成功時，會設為 `False`。	未透過喇叭聽到通話參與者的音訊。	請嘗試檢查喇叭裝置的狀態。
microphoneBusy	麥克風已在使用中。裝置正以獨佔模式使用，或裝置正以共用模式使用，而來電者要求以獨佔模式使用裝置。	- 當麥克風裝置串流擷取逾時 (音訊) 時，會設為 `True`。 - 當麥克風擷取成功時，會設為 `False`。	通話中的其他參與者聽不到您的音訊。	值設為 `True` 時，請為終端使用者提供視覺通知，讓他們能夠檢查另一個應用程式是否使用麥克風，並嘗試加以關閉。

存取診斷

使用者面向診斷是核心 Call API 的擴充功能，可讓您診斷作用中的通話。

this.diagnosticsCallFeature = call.Features.LocalUserDiagnostics;

使用者面向診斷事件

實作診斷事件的接聽程式。

private async void Call__OnNetworkUnavailableChanged(object sender, FlagDiagnosticChangedEventArgs args)
{
  var value = args.Value;
  // Handle the diagnostic event value changed...
}

// Listen to other network diagnostics

private async void Call__OnMediaSpeakerNotFunctioningChanged(object sender, FlagDiagnosticChangedEventArgs args)
{
  var value = args.Value;
  // Handle the diagnostic event value changed...
}

// Listen to other media diagnostics

設定接聽事件的事件方法。

this.diagnosticsCallFeature = call.Features.LocalUserDiagnostics;
this.networkDiagnostics = diagnosticsCallFeature.Network;
this.mediaDiagnostics = diagnosticsCallFeature.Media;

this.networkDiagnostics.NetworkUnavailableChanged += Call__OnNetworkUnavailableChanged;
// Listen to other network events as well ... 

this.mediaDiagnostics.SpeakerNotFunctioningChanged += Call__OnMediaSpeakerNotFunctioningChanged;
// Listen to other media events as well ... 

// Removing listeners

this.networkDiagnostics.NetworkUnavailable -= Call__NetworkUnavailableChanged;
// Remove the other listeners as well ... 

this.mediaDiagnostics.SpeakerNotFunctioningChanged -= Call__OnMediaSpeakerNotFunctioningChanged;
// Remove the other listeners as well ...

取得最新的使用者面向診斷

取得目前的通話中最新引發的診斷值。如果我們仍未收到診斷的值，則會傳回 null 或 .unknown。

this.diagnosticsCallFeature = call.Features.LocalUserDiagnostics;
this.networkDiagnostics = diagnosticsCallFeature.Network;
this.mediaDiagnostics = diagnosticsCallFeature.Media;

bool? lastSpeakerNotFunctionValue = this.mediaDiagnostics.GetLatestDiagnostics().IsSpeakerNotFunctioning; // Boolean?
bool? lastNetworkRelayNotReachableValue = this.networkDiagnostics.GetLatestDiagnostics().IsNetworkRelaysUnreachable; // Boolean?
DiagnosticQuality lastReceiveQualityValue = this.networkDiagnostics.GetLatestDiagnostics().NetworkReceiveQuality; // DiagnosticQuality (.good, .poor, .bad)
// or .unknown if there isn't a diagnostic for this.

共用方式為

使用者面向的診斷

診斷值

網路值

音訊值

相機值

其他值

存取診斷

使用者面向診斷事件

取得最新的使用者面向診斷

診斷值

網路值

音訊值

相機值

僅原生

存取診斷

使用者面向診斷事件

取得最新的使用者面向診斷

診斷值

網路值

音訊值

相機值

僅原生

存取診斷

使用者面向診斷事件

取得最新的使用者面向診斷

診斷值

網路值

音訊值

相機值

僅原生

存取診斷

使用者面向診斷事件

取得最新的使用者面向診斷

意見反應

其他資源