사전 호출 진단

아티클
02/13/2024

Important

Azure Communication Services의 이 기능은 현재 미리 보기 상태입니다.

미리 보기 API 및 SDK는 서비스 수준 계약 없이 제공됩니다. 프로덕션 워크로드에는 사용하지 않는 것이 좋습니다. 일부 기능은 지원되지 않거나 기능이 제한될 수 있습니다.

자세한 내용은 Microsoft Azure 미리 보기에 대한 보충 사용 약관을 검토하세요.

사전 호출 API를 사용하면 개발자가 클라이언트가 Azure Communication Services 호출에 참여할 준비가 되었는지 프로그래밍 방식으로 유효성을 검사할 수 있습니다. 사전 통화 API는 통화 SDK를 통해 액세스할 수 있습니다. 디바이스, 연결 및 통화 품질을 포함한 여러 진단을 제공합니다. 사전 호출 API는 Web(JavaScript)에서만 사용할 수 있습니다. 앞으로 여러 플랫폼에서 이러한 기능을 사용할 예정입니다. 사전 호출 API를 보려는 플랫폼에 대한 피드백을 제공해 주세요.

필수 조건

활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
Node.js 활성 LTS(장기 지원) 버전이 권장됩니다.
활성 Communication Services 리소스 Communication Services 리소스 만들기
호출 클라이언트를 인스턴스화하기 위한 사용자 액세스 토큰입니다. 사용자 액세스 토큰 만들기 및 관리 방법에 대해 알아봅니다. 또한 Azure CLI를 사용하고 연결 문자열과 함께 다음 명령을 실행하여 사용자 및 액세스 토큰을 만들 수 있습니다. (Azure Portal을 통해 리소스에서 연결 문자열을 가져와야 합니다.)
```
az communication identity token issue --scope voip --connection-string "yourConnectionString"
```
자세한 내용은 Azure CLI를 사용하여 액세스 토큰 만들기 및 관리를 참조하세요.

사전 호출 API에 액세스

Important

사전 호출 진단은 통화 SDK 버전 1.9.1-beta.1부터 사용할 수 있습니다. 다음 지침을 시도할 때 해당 버전을 사용해야 합니다.

사전 호출 API에 액세스하려면 callClient를 초기화하고 Azure Communication Services 액세스 토큰을 프로비전해야 합니다. 여기에서 PreCallDiagnostics 기능과 startTest 메서드에 액세스할 수 있습니다.

import { CallClient, Features} from "@azure/communication-calling";
import { AzureCommunicationTokenCredential } from '@azure/communication-common';

const callClient = new CallClient(); 
const tokenCredential = new AzureCommunicationTokenCredential("INSERT ACCESS TOKEN");
const preCallDiagnosticsResult = await callClient.feature(Features.PreCallDiagnostics).startTest(tokenCredential);

실행이 완료되면 개발자는 결과 개체에 액세스할 수 있습니다.

진단 결과

사전 호출 API는 디바이스 권한, 가용성 및 호환성, 통화 품질 통계 및 통화 중 진단과 같은 세부 정보를 포함하여 디바이스의 전체 진단을 반환합니다. 결과는 PreCallDiagnosticsResult 개체로 반환됩니다.


export declare type PreCallDiagnosticsResult  = {
    deviceAccess: Promise<DeviceAccess>;
    deviceEnumeration: Promise<DeviceEnumeration>;
    inCallDiagnostics: Promise<InCallDiagnostics>;
    browserSupport?: Promise<DeviceCompatibility>;
    id: string;
    callMediaStatistics?: Promise<MediaStatsCallFeature>;
};

preCallDiagnosticsResult 상수를 사용하여 개별 결과 개체에 액세스할 수 있습니다. 개별 테스트에 대한 결과는 테스트가 완료되면 반환되며 대부분의 테스트 결과는 즉시 사용할 수 있습니다. inCallDiagnostics 테스트를 사용하는 경우 테스트가 동영상 및 오디오의 품질의 유효성을 검사하므로 결과가 최대 1분까지 걸릴 수 있습니다.

브라우저 지원

브라우저 호환성 확인. Browser 및 OS 호환성을 확인하고 Supported 또는 NotSupported 값을 다시 제공합니다.


const browserSupport =  await preCallDiagnosticsResult.browserSupport;
  if(browserSupport) {
    console.log(browserSupport.browser)
    console.log(browserSupport.os)
  }

테스트에 실패하고 사용자가 사용 중인 브라우저가 NotSupported인 경우 이를 해결하는 가장 쉬운 방법은 사용자에게 지원되는 브라우저로 전환하도록 요청하는 것입니다. 설명서에서 지원되는 브라우저를 참조하세요.

참고 항목

알려진 문제: browser support 테스트는 올바른 값을 반환해야 하는 경우 Unknown을 반환합니다.

디바이스 액세스

권한 확인. 권한 관점에서 동영상 및 오디오 디바이스를 사용할 수 있는지 확인합니다. audio 및 video 디바이스에 boolean 값을 제공합니다.


  const deviceAccess =  await preCallDiagnosticsResult.deviceAccess;
  if(deviceAccess) {
    console.log(deviceAccess.audio)
    console.log(deviceAccess.video)
  }

테스트가 실패하고 오디오 및 동영상에 대한 권한이 false인 경우 사용자는 계속해서 통화에 참여하면 안 됩니다. 대신 사용자에게 권한을 사용하도록 설정하라는 메시지를 표시해야 합니다. 이를 위해서는 사용 중인 OS, 버전 및 브라우저에 따라 권한 액세스에 액세스하는 방법에 대한 구체적인 지침을 제공하는 것이 가장 좋습니다. 권한에 대한 자세한 내용은 권장 사항을 확인합니다.

장치 열거형

디바이스 가용성. 마이크, 카메라 및 스피커 디바이스가 시스템에서 검색되고 사용할 준비가 되었는지 확인합니다. Available 또는 NotAvailable 값을 다시 제공합니다.


  const deviceEnumeration = await preCallDiagnosticsResult.deviceEnumeration;
  if(deviceEnumeration) {
    console.log(deviceEnumeration.microphone)
    console.log(deviceEnumeration.camera)
    console.log(deviceEnumeration.speaker)
  }

디바이스를 사용할 수 없는 경우 사용자는 계속해서 통화에 참여하면 안 됩니다. 오히려 헤드셋, 카메라 또는 스피커가 제대로 연결되었는지 확인하기 위해 디바이스 연결을 확인하라는 메시지가 사용자에게 표시되어야 합니다. 장치 관리에 대한 자세한 내용은 설명서를 확인합니다.

InCall 진단

오디오 및 동영상에 대한 통화 메트릭을 확인하기 위해 빠른 통화를 수행하고 결과를 다시 제공합니다. 연결(connected, 부울), 대역폭 품질(bandWidth, 'Bad' | 'Average' | 'Good') 및 오디오 및 동영상(diagnostics)에 대한 호출 진단을 포함합니다. 진단은 jitter, packetLoss 및 rtt가 제공되며 결과는 간단한 품질 등급('Bad' | 'Average' | 'Good')을 사용하여 생성됩니다.

InCall 진단은 미디어 품질 통계를 사용하여 품질 점수를 계산하고 문제를 진단합니다. 사전 호출 진단 중에 전체 미디어 품질 통계 집합을 사용할 수 있습니다. 이 통계에는 프로그래밍 방식으로 사용할 수 있는 동영상 및 오디오 메트릭의 원시 값이 포함됩니다. InCall 진단은 모든 원시 데이터를 처리할 필요 없이 결과를 사용할 수 있도록 미디어 품질 통계 위에 편의 계층을 제공합니다. 액세스 방법은 미디어 통계 섹션을 참조하세요.


  const inCallDiagnostics =  await preCallDiagnosticsResult.inCallDiagnostics;
  if(inCallDiagnostics) {    
    console.log(inCallDiagnostics.connected)
    console.log(inCallDiagnostics.bandWidth)
    console.log(inCallDiagnostics.diagnostics.audio)
    console.log(inCallDiagnostics.diagnostics.video)
  }

이 단계에서 주의해야 할 여러 실패 지점이 있습니다. API에서 제공하는 값은 서비스에서 요구하는 임계값을 기반으로 합니다. 원시 임계값은 미디어 품질 통계 설명서에서 찾을 수 있습니다.

연결에 실패하면 사용자에게 네트워크 연결을 다시 확인하라는 메시지가 표시되어야 합니다. 연결 실패는 DNS, 프록시 또는 방화벽과 같은 네트워크 상태로 인해 발생할 수도 있습니다. 권장 네트워크 설정에 대한 자세한 내용은 설명서를 참조하세요.
대역폭이 Bad인 경우 사용자에게 다른 네트워크를 시도하거나 현재 네트워크에서 대역폭 가용성을 확인하라는 메시지가 표시되어야 합니다. 다른 고대역폭 작업이 일어나지 않도록 합니다.

미디어 통계

지터, 패킷 손실, rtt 등과 같은 품질 메트릭에 대한 세분화된 통계를 위해 callMediaStatistics는 preCallDiagnosticsResult 기능의 일부로 제공됩니다. 링크된 문서에서 사용 가능한 메트릭의 전체 목록 및 설명을 참조하세요. 통화 미디어 통계를 구독하여 전체 컬렉션을 가져올 수 있습니다. 이 통계는 InCall 진단 결과를 계산하는 데 사용되며 추가 분석을 위해 세분화하여 사용할 수 있는 원시 메트릭입니다.


const mediaStatsCollector = callMediaStatistics.startCollector(); 

mediaStatsCollector.on('mediaStatsEmitted', (mediaStats: SDK.MediaStats) => { 
    // process the stats for the call. 
    console.log(mediaStats);
});

가격 책정

사전 호출 진단 테스트가 실행되면 백그라운드에서 통화 시간을 사용하여 진단을 실행합니다. 테스트는 약 30초 동안 지속되며, 참가자당 분당 $0.004의 표준 요율로 청구되는 30초의 통화를 사용합니다. 사전 호출 진단의 경우 요금은 참가자 1명 x 30초 = $0.002입니다.

다음을 통해 공유