|
| 1 | +--- |
| 2 | +title: Azure Communication Services pre-call diagnostics |
| 3 | +titleSuffix: An Azure Communication Services concept document |
| 4 | +description: Overview of the pre-call diagnostic API feature. |
| 5 | +author: yassirbisteni |
| 6 | +manager: bobgao |
| 7 | +services: azure-communication-services |
| 8 | +ms.author: ybisteni |
| 9 | +ms.date: 22/11/2024 |
| 10 | +ms.topic: conceptual |
| 11 | +ms.service: azure-communication-services |
| 12 | +--- |
| 13 | + |
| 14 | +# Pre-Call diagnostics |
| 15 | + |
| 16 | +[!INCLUDE [Public Preview Disclaimer](../../includes/public-preview-include.md)] |
| 17 | + |
| 18 | +The pre-call API feature enables developers to programmatically validate a client’s readiness to join an Azure Communication Services call. You can only access pre-call features using the Calling SDK. The pre-call diagnostic feature provides multiple diagnostics including device, connection, and call quality. The pre-call diagnotic feature is available only for Web (JavaScript). We plan to enable these capabilities across platforms in the future. Provide us with [feedback](../../support.md) about which platforms you want to see pre-call diagnostics enabled. |
| 19 | + |
| 20 | +## Pre-Call diagnostics accesss |
| 21 | + |
| 22 | +To access pre-call diagnostics, you need to initialize a `CallClient`, and provision an Azure Communication Services access token. Then you can access the `PreCallDiagnostics` feature and the `startTest` method. |
| 23 | + |
| 24 | +```swift |
| 25 | +let acsToken: String; |
| 26 | +do |
| 27 | +{ |
| 28 | + let options = CommunicationTokenRefreshOptions(initialToken: acsToken, |
| 29 | + refreshProactively: true, |
| 30 | + tokenRefresher: tokenRefresher) |
| 31 | + credentials = try CommunicationTokenCredential(withOptions: options) |
| 32 | +} |
| 33 | +catch |
| 34 | +{ |
| 35 | + return nil |
| 36 | +} |
| 37 | + |
| 38 | +let options = CallClientOptions() |
| 39 | +callClient = CallClient(options: options) |
| 40 | + |
| 41 | +preCallDiagnosticsFeature = callClient.feature(Features.preCallDiagnostics) |
| 42 | + |
| 43 | +preCallDiagnosticsCallClientFeatureObserver = PreCallDiagnosticsCallClientFeatureObserver(view: self) |
| 44 | +preCallDiagnosticsFeature.delegate = preCallDiagnosticsCallClientFeatureObserver |
| 45 | +preCallDiagnosticsFeature.startTest(credentials, withCompletionHandler: { error in |
| 46 | + |
| 47 | +}) |
| 48 | + |
| 49 | +class PreCallDiagnosticsCallClientFeatureObserver: NSObject, PreCallDiagnosticsCallClientFeatureDelegate |
| 50 | +{ |
| 51 | + private var view: HomeView |
| 52 | + |
| 53 | + init(view: HomeView) |
| 54 | + { |
| 55 | + self.view = view |
| 56 | + } |
| 57 | + |
| 58 | + func diagnosticsCallClientFeature(_ preCallDiagnosticsCallClientFeature: PreCallDiagnosticsCallClientFeature, |
| 59 | + didDiagnosticsReady args: PreCallDiagnosticsReadyEventArgs) |
| 60 | + { |
| 61 | + view.onPreCallDiagnosticsReady(args: args) |
| 62 | + } |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +Once it finishes running, developers can access the result object. |
| 67 | + |
| 68 | +## Diagnostic results |
| 69 | + |
| 70 | +Pre-call diagnostics returns a full diagnostic of the device including details like availability and compatibility, call quality statistics, and in-call diagnostics. The results are returned as a `PreCallDiagnosticsReadyEvent` object. |
| 71 | + |
| 72 | +```swift |
| 73 | +func onPreCallDiagnosticsReady(args: PreCallDiagnosticsReadyEventArgs) -> Void |
| 74 | +{ |
| 75 | + let diagnostics = args.diagnostics |
| 76 | + let mediaStatsReport = diagnostics.mediaStatisticsReport; |
| 77 | + |
| 78 | + if let outgoingStatsList = mediaStatsReport.outgoingStatistics |
| 79 | + { |
| 80 | + let videoStatsList = outgoingStatsList.videoStatistics; |
| 81 | + let screenShareStatsList = outgoingStatsList.screenShareStatistics; |
| 82 | + let audioStatsList = outgoingStatsList.audioStatistics; |
| 83 | + } |
| 84 | + |
| 85 | + if let incomingStatsList = mediaStatsReport.incomingStatistics |
| 86 | + { |
| 87 | + let videoStatsList = incomingStatsList.videoStatistics; |
| 88 | + let screenShareStatsList = incomingStatsList.screenShareStatistics; |
| 89 | + let audioStatsList = incomingStatsList.audioStatistics; |
| 90 | + } |
| 91 | +} |
| 92 | +``` |
| 93 | + |
| 94 | +You can access individual result objects using the `PreCallDiagnosticsReadyEvent` type. Results for individual tests are returned as they're completed with many of the test results being available immediately. The results might take up to 1 minute as the test validates the quality of the video and audio. |
| 95 | + |
| 96 | +### Device permissions |
| 97 | + |
| 98 | +The permission check determines whether video and audio devices are available from a permissions perspective. Provides `boolean` value for `audio` and `video` devices. |
| 99 | + |
| 100 | +```swift |
| 101 | +let permissionList = preCallDiagnosticsFeature?.devicePermissions() |
| 102 | +``` |
| 103 | + |
| 104 | +## Pricing |
| 105 | + |
| 106 | +When the pre-call diagnostic test runs behind the scenes, it uses calling minutes to run the diagnostic. The test lasts for roughly 30 seconds, using up 30 seconds of calling time which is charged at the standard rate of $0.004 per participant per minute. For the case of pre-call diagnostics, the charge is for 1 participant x 30 seconds = $0.002. |
| 107 | + |
| 108 | +## Next steps |
| 109 | + |
| 110 | +- [Check your network condition with the diagnostics tool](../developer-tools/network-diagnostic.md) |
| 111 | +- [Explore User-Facing Diagnostic APIs](../voice-video-calling/user-facing-diagnostics.md) |
| 112 | +- [Enable Media Quality Statistics in your application](../voice-video-calling/media-quality-sdk.md) |
| 113 | +- [Consume call logs with Azure Monitor](../analytics/logs/voice-and-video-logs.md) |
0 commit comments