사용자 대상 진단

2025-06-06

Azure Communication Services에서 호출을 사용할 때 고객에게 영향을 미치는 문제가 발생할 수 있습니다. 이 문제 해결을 돕기 위해, Azure Communication Services는 호출의 다양한 속성을 검사하여 문제가 무엇인지 확인할 수 있는 "UFD(사용자 연결 진단)"이라는 기능을 제공합니다. 사용자 연결 진단은 사용자 환경이 불량할 수 있는 기본 문제(예: 네트워크 불량, 사용자가 마이크 음소거)로 인해 발생할 수 있는 이벤트입니다. 사용자 연결 진단이 실행된 후, 최종 사용자에게 기본 문제가 있을 수 있다는 피드백을 제공하는 것이 좋습니다. 그러나 사용자 연결 진단 출력은 정보만 제공하며, 호출 스택은 실행되는 사용자 연결 진단을 기반으로 변경 작업을 수행하지 않습니다.

로컬 대 원격 사용자 대면 진단

UFD(사용자 연결 진단)는 프로그래밍 방식 API를 통해 디바이스를 호출하는 사용자에서 발생하는 사용자에게 영향을 미치는 이벤트를 노출할 수 있습니다. Azure Communication Services 내에는 UFD를 사용하고 생성하는 두 가지 방법, 즉 로컬 UFD 및 원격 UFD가 있습니다. 로컬 UFD는 로컬 사용자의 휴대폰 또는 브라우저에서 생성됩니다. 원격 UFD는 원격 참가자의 환경에서 발생하는 이벤트로, 로컬 사용자가 원격 사용자의 환경에 영향을 미치는 이벤트를 로컬에서 소비하고 볼 수 있게 합니다.

중요합니다

이 문서에 설명된 기능은 현재 프라이빗 미리 보기로 제공됩니다. 프라이빗 미리 보기에는 아직 공개적으로 사용할 수 없는 테스트 목적으로 SDK 및 설명서에 대한 액세스 권한이 포함되어 있습니다. 양식을 작성하여 Azure Communication Services에 대한 미리 보기 접근 권한을 얻어 얼리 어답터로 신청하세요.

참고 항목

SDK를 호출하는 공개 미리 보기 버전 1.34.1-beta.2 이상에서는 SDK를 호출하는 WebJS에서 원격 UFD를 보낼 수 있습니다. 호출 SDK에 의해 내보낸 로컬 UFDS는 일반적인 가용성 상태에 있습니다.

UFD(사용자 연결 진단)를 사용하면 로컬 또는 원격 참가자가 오디오 비디오 통화 품질에 영향을 주는 문제가 발생하는 경우를 확인할 수 있습니다. UFD는 네트워크 조건, 디바이스 기능 및 미디어 성능에 대한 실시간 진단을 제공합니다. 이 진단 정보는 개발자가 연결 불량, 음소거된 마이크 또는 낮은 대역폭과 같은 문제를 식별하는 데 도움이 됩니다. UFD는 이러한 문제를 자동으로 해결하지는 않지만 애플리케이션에서 사용자에게 사전 피드백을 제공하여 인터넷 연결 확인 또는 디바이스 설정 조정과 같은 솔루션을 제안할 수 있습니다. 이 데이터에 따라 사용자는 문제 자체를 수정하거나(예: 네트워크가 약한 경우 끄기 비디오) 사용자 인터페이스를 통해 정보를 표시할 수 있습니다.

원격 UFD 및 로컬 UFD 사용에는 몇 가지 사소한 차이점이 있습니다. 이러한 차이점은 다음과 같습니다.

호출 SDK는 개인 정보 보호 문제로 인해 원격 UFD를 통해 speakingWhileMicrophoneIsMuted를 노출하지 않습니다.
호출 SDK는 통화 시 최대 20명의 참가자까지 UFD를 노출하고 스트리밍합니다. 참가자 수가 20명을 초과하면 원격 UFD 의 전송을 제한하고 중단하여 이러한 이벤트로 네트워크 오버로드를 방지합니다.
호출 SDK는 고유 클라이언트에서 들어오는 분당 3개의 원격 UFD 이벤트만 볼 수 있도록 필터링합니다.
클라이언트 SDK 관점에서 로컬 UFD가 원격으로 전송되는 기능을 사용하도록 설정해야 합니다.

진단 값

다음과 같은 사용자 대상 진단을 사용할 수 있습니다.

네트워크 값

이름	설명	사용 가능한 값:	사용 사례	완화 단계
네트워크 없음	사용 가능한 네트워크가 없습니다.	- 사용 가능한 네트워크가 없어서 호출을 시작할 수 없으면 `True`로 설정됩니다. - ICE 후보가 있는 경우 `False`로 설정됩니다.	디바이스가 네트워크에 연결되지 않았습니다.	통화에 음성 통화를 유지할 수 있는 신뢰 가능한 인터넷 연결이 있는지 확인합니다. 자세한 내용은 네트워크 최적화 섹션을 참조하세요.
네트워크 릴레이에 접근할 수 없습니다.	네트워크에 문제가 있습니다.	- 네트워크에 Azure Communication Services 릴레이에 연결하도록 허용하지 않는 제약 조건이 있으면 `True`로 설정됩니다. - 새 호출 시 `False`로 설정됩니다.	활성 통화 중일 때 WiFi 신호가 불안정하게 켜졌다 꺼집니다.	방화벽 규칙 및 네트워크 라우팅을 통해 클라이언트가 Microsoft 턴 서버에 연결할 수 있는지 확인합니다. 자세한 내용은 방화벽 구성 섹션을 참조하세요.
네트워크 재연결	연결이 끊겼고 클라이언트가 네트워크에 다시 연결됩니다.	- 네트워크 연결이 끊어지면 `Bad`로 설정됩니다. - 미디어 전송 연결이 끊어지면 `Poor`로 설정됩니다. - 새 세션이 연결되면 `Good`으로 설정됩니다.	낮은 대역폭, 인터넷 없음	통화에 음성 통화를 유지할 수 있는 신뢰 가능한 인터넷 연결이 있는지 확인합니다. 자세한 내용은 네트워크 대역폭 요구 사항 섹션을 참조하세요.
네트워크 수신 품질	들어오는 스트림 품질에 대한 표시기입니다.	- 스트림 수신에 `Bad` 심각한 문제가 있는 경우로 설정합니다. - 스트림을 받는 데 경미한 문제가 있으면 `Poor`로 설정됩니다. - 스트림을 받는 데 문제가 없으면 `Good`으로 설정됩니다.	낮은 대역폭	통화에 음성 통화를 유지할 수 있는 신뢰 가능한 인터넷 연결이 있는지 확인합니다. 자세한 내용은 네트워크 대역폭 요구 사항 섹션을 참조하세요. 가용 인터넷 대역폭을 절약할 수 있도록 최종 사용자에게 카메라를 끄는 것이 좋겠다고 제안합니다.
네트워크 전송 품질	들어오는 스트림 품질에 대한 표시기입니다.	문제가 심각하여 스트림을 보낼 수 없는 경우, `Bad`로 설정하십시오. - 스트림을 보내는 데 경미한 문제가 있으면 `Poor`로 설정됩니다. - 스트림을 보내는 데 문제가 없으면 `Good`으로 설정됩니다.	낮은 대역폭	통화에 음성 통화를 유지할 수 있는 신뢰 가능한 인터넷 연결이 있는지 확인합니다. 자세한 내용은 네트워크 대역폭 요구 사항 섹션을 참조하세요. 또한 가용 인터넷 대역폭을 절약할 수 있도록 최종 사용자에게 카메라를 끄는 것이 좋겠다고 제안합니다.

오디오 값

이름	설명	사용 가능한 값:	사용 사례	완화 단계
스피커 장치가 나열되지 않음	사용자 시스템에 오디오 출력 디바이스(스피커)가 없습니다.	- 시스템에 스피커 디바이스가 없고 스피커 선택이 지원되는 경우 `True`로 설정됩니다. - 시스템에 스피커 디바이스가 1개 이상 있고 스피커를 선택할 수 있으면 `False`로 설정됩니다.	모든 스피커가 플러그가 뽑혀 있습니다.	값이 `True`로 설정된 경우 최종 사용자에게 현재 통화 세션에 사용할 수 있는 스피커가 없다는 시각적 알림을 제공하는 것이 좋습니다.
마이크가 음소거된 상태에서 말하기	음소거 상태에서 말합니다.	- 로컬 마이크가 음소거되고 로컬 사용자가 말하는 경우 `True`로 설정됩니다. - 로컬 사용자가 말하기를 중지하거나 마이크를 음소거 해제할 때 `False`로 설정됩니다. * 참고: 현재 이 옵션은 오디오 수준 샘플이 WebRTC 통계에서 가져온이므로 Safari에서 지원되지 않습니다. 오디오 값 'speakingWhileMicrophoneIsMuted'는 원격 UFD로 사용할 수 없습니다.	통화하는 동안 마이크를 음소거하고 마이크에 대고 말합니다.	값이 설정된 `True` 경우 최종 사용자에게 대화 중일 수 있다는 시각적 알림을 제공하고 오디오가 음소거되었음을 깨닫지 못하는 것을 고려합니다.
마이크 장치가 나열되지 않음	사용자 시스템에 오디오 캡처 디바이스(마이크)가 없습니다.	- 시스템에 마이크 디바이스가 없는 경우 `True`로 설정됩니다. - 시스템에 마이크 디바이스가 1개 이상 있으면 `False`로 설정됩니다.	모든 마이크는 통화 중에 연결이 끊어집니다.	값이 `True`로 설정된 경우 최종 사용자에게 현재 통화 세션에 마이크가 없다는 시각적 알림을 제공하는 것이 좋습니다. 자세한 내용은 디바이스 관리자 섹션에서 마이크 사용 섹션을 참조하세요.
마이크가 작동하지 않음	마이크가 작동하지 않습니다.	- 마이크 디바이스가 시스템에서 사용하지 않도록 설정되었거나 다른 프로세스에서 사용되고 있기 때문에 로컬 오디오 스트림 전송을 시작하지 못한 경우 `True`로 설정됩니다. 이 UFD가 발생하는 데 약 10초가 걸립니다. - 마이크가 오디오 스트림을 다시 성공적으로 보내기 시작하면 `False`로 설정됩니다.	마이크를 사용할 수 없습니다. 시스템에서 마이크 액세스가 사용하지 않도록 설정되었습니다.	값이 `True`로 설정된 경우 최종 사용자에게 마이크에 문제가 있다는 시각적 알림을 제공합니다.
마이크가 예상치 못하게 음소거됨	마이크가 음소거되었습니다.	- 마이크가 예기치 않게 음소거 상태가 되면 `True`로 설정됩니다. - 마이크가 오디오 스트림을 성공적으로 보내기 시작하면 `False`로 설정됩니다.	마이크가 시스템에서 음소거되었습니다. 대부분의 경우는 사용자가 모바일 디바이스에서 Azure Communication Services 통화 중이며 전화가 걸려올 때 발생합니다. 대부분의 경우 운영 체제는 사용자가 전화를 받을 수 있도록 Azure Communication Services 통화를 음소거합니다.	값이 `True`로 설정된 경우 최종 사용자에게 전화가 걸려왔기 때문에 통화가 음소거되었다는 시각적 알림을 제공합니다. 자세한 내용은 OS에서 Azure Communication Services 통화를 음소거 섹션을 참조하세요.
마이크 권한이 거부되었습니다	디바이스의 볼륨이 낮거나 macOS에서 거의 무음입니다.	- 시스템 설정(오디오)에서 오디오 권한이 거부되면 `True`로 설정됩니다. - 스트림이 성공적으로 획득되면 `False`로 설정됩니다. 참고: 이 진단은 macOS에서만 작동합니다.	설정에서 마이크 사용 권한이 사용하지 않도록 설정되었습니다.	값이 `True`로 설정된 경우 최종 사용자에게 Azure Communication Services 통화에 마이크를 사용할 수 있는 권한을 사용하지 않았다는 시각적 알림을 제공합니다.

카메라 값

이름	설명	사용 가능한 값:	사용 사례	완화 단계
카메라 정지	카메라가 5초 넘게 프레임 생성을 중지합니다.	- 로컬 비디오 스트림이 중지된 경우 `True`로 설정합니다. 이 진단은 원격 쪽 사용자가 화면에서 중지된 비디오를 보거나 원격 참가자의 화면에서 비디오가 렌더링되지 않음을 의미합니다. - 중지가 끝나고 사용자가 정상적으로 비디오를 볼 수 있는 경우 `False`로 설정됩니다.	통화 중에 카메라가 손실되었거나 네트워크가 잘못되면서 카메라가 정지되었습니다.	값이 설정 `True`되면 최종 사용자에게 원격 참가자 네트워크가 잘못되었을 수 있다는 알림을 제공하는 것이 좋습니다. 사용자가 대역폭을 절약하기 위해 카메라를 끄도록 제안합니다. 자세한 내용은 Azure Communication Services 통화에 필요한 인터넷 기능에 대한 네트워크 대역폭 요구 사항 섹션을 참조하세요.
카메라 시작 실패	일반 카메라 오류입니다.	- 카메라 디바이스가 시스템에서 사용하지 않도록 설정되었거나 다른 프로세스에서 사용되고 있기 때문에 로컬 비디오 전송을 시작하지 못한 경우 `True`로 설정됩니다. - 선택한 카메라 디바이스가 로컬 비디오를 다시 보낼 경우 `False`로 설정됩니다.	카메라 오류	값이 `True`로 설정된 경우 최종 사용자에게 카메라가 시작되지 않는다는 시각적 알림을 제공합니다.
카메라 시작 시간 초과	카메라가 잘못된 상태인 일반적인 시나리오입니다.	- 카메라 디바이스가 비디오 스트림 전송을 시작하는 동안 시간이 초과될 경우 `True`로 설정됩니다. - 선택한 카메라 디바이스가 로컬 비디오를 다시 보낼 경우 `False`로 설정됩니다.	카메라 오류	값이 `True`로 설정된 경우 최종 사용자에게 카메라에 문제가 있을 수 있다는 시각적 알림을 제공합니다. (알림 제거를 위해 값이 `False`로 다시 설정된 경우).
카메라 권한이 거부되었습니다	설정에서 카메라 사용 권한이 거부되었습니다.	- 시스템 설정(비디오)에서 카메라 권한이 거부되면 `True`로 설정됩니다. - 스트림이 성공적으로 획득되면 `False`로 설정됩니다. 참고: 이 진단은 macOS Chrome에서만 작동합니다.	설정에서 카메라 사용 권한이 사용하지 않도록 설정되었습니다.	값이 `True`로 설정된 경우 최종 사용자에게 Azure Communication Services 호출에 카메라를 사용할 수 있는 권한을 사용하지 않았다는 시각적 알림을 제공합니다.
예기치 않게 카메라가 멈췄습니다.	카메라 오작동	- 마이크가 예기치 않게 음소거 상태가 되면 `True`로 설정됩니다. - 마이크가 오디오 스트림을 다시 성공적으로 보내기 시작하면 `False`로 설정됩니다.	카메라가 제대로 작동하는지 확인합니다.	값이 `True`로 설정된 경우 최종 사용자에게 카메라에 문제가 있을 수 있다는 시각적 알림을 제공합니다. (알림 제거를 위해 값이 `False`로 다시 설정된 경우).

기타 값

이름	설명	사용 가능한 값:	사용 사례	완화 단계
화면 공유 녹화 비활성화됨	설정의 기본 설정에서 시스템 화면 공유가 거부되었습니다.	- 시스템 설정(공유)에서 화면 공유 권한이 거부되면 `True`로 설정됩니다. - 스트림이 성공적으로 획득되면 `False`로 설정됩니다. 참고: 이 진단은 macOS.Chrome에서만 작동합니다.	설정에서 화면 녹화가 사용하지 않도록 설정되었습니다.	값이 `True`로 설정된 경우, 사용자에게 그들이 Azure Communication Services 호출에 대해 화면 공유 권한을 활성화하지 않았다는 시각적 알림을 제공하십시오.
캡처 시작 실패	시스템 화면 공유에 실패했습니다.	- 화면 캡처를 시작하지 못하면 `True`로 설정됩니다. - 화면 캡처가 성공적으로 시작되면 `False`로 설정됩니다.		값이 `True`로 설정된 경우 최종 사용자에게 화면 공유에 문제가 있을 수 있다는 시각적 알림을 제공합니다. (알림 제거를 위해 값이 `False`로 다시 설정된 경우).
캡처 장치가 예기치 않게 중지되었습니다	시스템 화면 공유 오작동	- 화면 캡처가 예기치 않게 중지됨 상태가 되면 `True`로 설정됩니다. - 화면 캡처가 성공적으로 다시 캡처하기 시작하면 `False`로 설정됩니다.	화면 공유가 올바르게 작동하는지 확인	값이 `True`로 설정된 경우 최종 사용자에게 화면 공유를 중지하는 문제가 있을 수 있다는 시각적 알림을 제공합니다. (알림 제거를 위해 값이 `False`로 다시 설정된 경우).

진단 액세스

사용자 연결 진단은 핵심 Call API의 확장된 기능입니다. 여기서 인터페이스에 UserFacingDiagnosticsFeature 대해 자세히 이해할 수 있습니다.

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

로컬 사용자 관련 진단 이벤트

각 진단에는 다음 데이터가 있습니다.

진단은 로컬 컴퓨터에서 실행된 UFD 진단의 유형입니다. 예를 들어 NetworkSendQuality 또는 DeviceSpeakWhileMuted의 UFD.
값이 DiagnosticQuality 또는 DiagnosticFlag입니다
DiagnosticQuality = enum { Good = 1, Poor = 2, Bad = 3 }.
DiagnosticFlag = true | false

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}`);
        }
    }
};


// Subscribe to the `diagnosticChanged` event to monitor when any local user-facing diagnostic changes.
userFacingDiagnostics.network.on('diagnosticChanged', diagnosticChangedListener);
userFacingDiagnostics.media.on('diagnosticChanged', diagnosticChangedListener);

원격 사용자 대면 진단 이벤트에 액세스

호출 시 모든 참가자에게 원격 UFD를 전송하려면 각 클라이언트에서 함수를 사용하도록 설정해야 합니다. 클라이언트별로 활성화하거나 비활성화할 수 있습니다. 사용하도록 설정하면 클라이언트는 사용 및 처리를 위해 로컬 UFD를 모든 참가자에게 원격으로 전송하기 시작합니다. 참가자 수가 20명을 초과하면 로컬 클라이언트에서 원격 UFD의 전송이 중지됩니다. 이 측정값은 UFD 트래픽으로 인한 과도한 네트워크 대역폭 소비를 방지하기 위해 구현됩니다.

// Start the local client to send its local UFD to all participants (send local UFD to remote clients).
remoteUfdsFeature.startSendingDiagnostics();
// Stop sending local UFDs to remote clients.
remoteUfdsFeature.stopSendingDiagnostics();

아래 RemoteParticipantDiagnosticsData 코드 샘플의 경우 다음과 같은 데이터가 연결되어 있습니다.

diagnostic 에는 원격 컴퓨터에서 전송된 진단 데이터 UFD 배열이 포함되어 있습니다. 예를 들어 NetworkSendQuality의 UFD.
해당 요소의 값은 다음과 DiagnosticQualityDiagnosticFlag같이 정의됩니다.
DiagnosticQuality = enum { Good = 1, Poor = 2, Bad = 3 }.
DiagnosticFlag = true | false
배열의 valueType = DiagnosticQuality | DiagnosticFlag

const remoteDiagnosticChangedListener = (diagnosticInfo: RemoteParticipantDiagnosticsData) => {
    for (const diagnostic of diagnosticInfo.diagnostics) {
        if (diagnostic.valueType === 'DiagnosticQuality') {
            if (diagnostic.value === SDK.DiagnosticQuality.Bad) {
                console.error(`${diagnostic.diagnostic} is bad quality`);

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

        } else if (diagnostic.valueType === 'DiagnosticFlag') {
            console.error(`${diagnostic.diagnostic} diagnostic flag raised`);
        }
    }
};

// Subscribe to the `diagnosticChanged` event to monitor when any local user-facing diagnostic changes.
userFacingDiagnostics.remote.on('diagnosticChanged', remoteDiagnosticChangedListener);

수신된 최신 사용자 인터페이싱 진단 이벤트를 발생시킵니다.

호출 SDK에서 발생하는 최신 진단 값을 생성하는 샘플 코드는 다음과 같습니다. 진단이 정의되지 않은 경우 UFD가 발동되지 않은 상태를 의미합니다.

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}`
);