Skip to content

Commit caea06a

Browse files
ShawnJacksonShawnJackson
committed
edit pass: quality-and-diagnostics
1 parent f2ee3b7 commit caea06a

File tree

5 files changed

+162
-129
lines changed

5 files changed

+162
-129
lines changed

‎articles/communication-services/concepts/best-practices.md

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,9 @@ This article provides information about best practices related to the Azure Comm
2424
[!INCLUDE [Native](includes/best-practices-native.md)]
2525
::: zone-end
2626

27-
## Next steps
28-
For more information, see the following articles:
27+
## Related content
2928

3029
- [Improve and manage call quality](./voice-video-calling/manage-call-quality.md)
31-
- [Call Diagnostics](./voice-video-calling/call-diagnostics.md)
30+
- [Use Call Diagnostics to diagnose call problems](./voice-video-calling/call-diagnostics.md)
3231
- [Add voice calling to your app](../quickstarts/voice-video-calling/getting-started-with-calling.md)
33-
- [Use the UI Library for enhance calling experiences](./ui-library/ui-library-overview.md)
32+
- [Use the UI Library for enhanced calling experiences](./ui-library/ui-library-overview.md)

‎articles/communication-services/concepts/includes/best-practices-native.md

Lines changed: 36 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Azure Communication Services - best practices for Calling Native SDK
3-
description: Learn more about Azure Communication Service best practices for Calling Native SDK.
3+
description: Learn about Azure Communication Services best practices for the Calling Native SDK.
44
author: garchiro7
55
manager: chpalmer
66
services: azure-communication-services
@@ -11,47 +11,47 @@ ms.topic: include
1111
ms.service: azure-communication-services
1212
---
1313

14-
## Azure Communication Services native SDK best practices
14+
## Best practices for the Azure Communication Services Calling Native SDK
1515

16-
This section provides information about best practices associated with the Azure Communication Services voice and video calling native SDK.
16+
This section provides information about best practices associated with the Azure Communication Services Calling Native SDK for voice and video calling.
1717

18-
## Supported platforms
18+
### Supported platforms
1919

20-
Here are the minimum OS platform requirements to ensure optimal functionality of the Calling Native SDKs.
20+
Here are the minimum OS platform requirements to ensure optimal functionality of the Calling Native SDK.
2121

22-
### [iOS](#tab/ios)
22+
#### [iOS](#tab/ios)
2323

24-
- Support for iOS 10.0+ at build time, and iOS 12.0+ at run time.
25-
- Xcode 12.0+.
26-
- Support for **iPadOS** 13.0+.
24+
- Support for iOS 10.0+ at build time and iOS 12.0+ at runtime
25+
- Xcode 12.0+
26+
- Support for iPadOS 13.0+
2727

28-
### [Android](#tab/android)
28+
#### [Android](#tab/android)
2929

30-
- Support for Android API Level 21 or Higher.
31-
- Support for Java 7 or higher.
32-
- Support for Android Studio 2.0.
30+
- Support for Android API Level 21 or higher
31+
- Support for Java 7 or later
32+
- Support for Android Studio 2.0
3333

34-
We highly recommend identifying and validating your scenario by visiting the supported [Android platforms](../sdk-options.md?#android-platform-support)
34+
We highly recommend that you identify and validate your scenario by visiting the supported [Android platforms](../sdk-options.md?#android-platform-support).
3535

36-
### [Windows](#tab/windows)
36+
#### [Windows](#tab/windows)
3737

38-
- Support for UWP (Universal Windows Platform).
39-
- Support for WinUI 3.
38+
- Support for Universal Windows Platform (UWP)
39+
- Support for WinUI 3
4040

4141
---
4242

43-
## App request device permissions
43+
### Verify device permissions for app requests
4444

45-
To use the Calling Native SDKs for making or receiving calls, it's necessary to authorize each platform to access device resources. As a developer, you should prompt the user for access and ensure that are enabled. The consumer authorizes these access rights, so verify that they have been granted permission previously.
45+
To use the Calling Native SDK for making or receiving calls, it's necessary to authorize each platform to access device resources. As a developer, you should prompt the user for access and ensure that permissions are enabled. The consumer authorizes these access rights, so verify that they were granted permission previously.
4646

47-
### [iOS](#tab/ios)
47+
#### [iOS](#tab/ios)
4848

49-
- `NSMicrophoneUsageDescription` for microphone access.
50-
- `NSCameraUsageDescription` for camera access.
49+
- `NSMicrophoneUsageDescription` for microphone access
50+
- `NSCameraUsageDescription` for camera access
5151

52-
### [Android](#tab/android)
52+
#### [Android](#tab/android)
5353

54-
In the Application Manifest (`app/src/main/AndroidManifest.xml`). Verify the following lines:
54+
In the application manifest (`app/src/main/AndroidManifest.xml`), verify the following lines:
5555

5656
```xml
5757
<uses-permission android:name="android.permission.INTERNET" />
@@ -64,48 +64,48 @@ In the Application Manifest (`app/src/main/AndroidManifest.xml`). Verify the fol
6464
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
6565
```
6666

67-
### [Windows](#tab/windows)
67+
#### [Windows](#tab/windows)
6868

6969
Go to `Package.appxmanifest` and select capabilities:
7070

71-
- `Internet (Client)` & `Internet (Client & Server)` for network access.
72-
- `Microphone` to access the audio feed of the microphone.
73-
- `Webcam` to access the video feed of the camera.
71+
- `Internet (Client)` and `Internet (Client & Server)` for network access
72+
- `Microphone` to access the audio feed of the microphone
73+
- `Webcam` to access the video feed of the camera
7474

7575
---
7676

77-
## Configure the logs
77+
### Configure the logs
7878

7979
Implementing **logging** as per the [logs file retrieval tutorial](../../tutorials/log-file-retrieval-tutorial.md) is more critical than ever. Detailed logs help in diagnosing issues specific to device models or OS versions that meet the minimum SDK criteria. We encourage to the developers that start configuring the Logs API without the logs the Microsoft Support team **won't be able** to help debug and troubleshoot the calls.
8080

81-
## Track Call ID
81+
### Track Call ID
8282

8383
**`CallID`** is the unique ID for a call. It identifies correlated events from all of the participants and endpoints that connect during a single call, in Most cases you use it to review the logs and Microsoft Support team ask for it to help troubleshoot the calls. You **should** track the `CallID` in your telemetry that you configure in your app, you can follow the guidelines in the [troubleshooting guide](../troubleshooting-info.md) to understand how to retrieve it for each platform.
8484

85-
## Subscribe to UFD (User Facing Diagnostics) and media quality statistics
85+
### Subscribe to User Facing Diagnostics and media quality statistics
8686

8787
- [User Facing Diagnostics (UFD)](../voice-video-calling/user-facing-diagnostics.md) that can be used to examine various properties of a call to determine what the issue might be during the call that affects your customers.
8888
- [Media quality statistics](../voice-video-calling/media-quality-sdk.md) examine the low-level audio, video, and screen-sharing quality metrics for incoming and outgoing call metrics. We recommend that you collect the data and send it to your pipeline ingestion after your call ends.
8989

90-
## Error Handling
90+
### Manage error handling
9191

9292
If there are any errors during the call or implementation, the methods return error objects containing error codes. It's crucial to use these error objects for proper error handling and to display alerts. The call states also return error codes to help identify the reason behind call failure. You can refer to [the troubleshooting guide](../troubleshooting-info.md), to resolve any issues.
9393

94-
### Managing Video Streams
94+
### Manage video streams
9595

9696
Make sure to dispose of the `VideoStreamRendererView` when the video is no longer displayed on the UI. Use `VideoStreamType` to determine the type of the stream.
9797

98-
## General memory management
98+
### Conduct general memory management
9999

100100
**Preallocate Resources**. Initialize your calling client and any necessary resources during your app's startup phase rather than on demand. This approach reduces latency when starting a call.
101101

102102
**Dispose Properly**. Ensure that all call objects are correctly disposed of after use to free up system resources and avoid memory leaks. Make sure to unsubscribe from *events* preventing memory leaks.
103103

104-
## Camera or microphone being used by another process
104+
### Manage the behavior of a camera or microphone that another process is using
105105

106106
It's important to note that on mobile devices if multiple processes try to access the camera or microphone at the same time, the first process to request access will take control of the device. As a result, the second process will immediately lose access to it.
107107

108-
## Optimize the APP size using UI Library
108+
### Optimize the APP size using UI Library
109109

110110
Optimizing the size of libraries in software development is crucial for several reasons, particularly as applications become increasingly complex, and resource-intensive.
111111

‎articles/communication-services/concepts/includes/best-practices-web.md

Lines changed: 57 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Azure Communication Services - best practices for Calling Web SDK
3-
description: Learn more about Azure Communication Service best practices for Calling Web SDK.
3+
description: Learn about Azure Communication Services best practices for the Calling Web SDK.
44
author: srahaman
55
manager: akania
66
services: azure-communication-services
@@ -11,26 +11,31 @@ ms.topic: include
1111
ms.service: azure-communication-services
1212
---
1313

14-
## Azure Communication Services web JavaScript SDK best practices
15-
This section provides information about best practices associated with the Azure Communication Services JavaScript voice and video calling SDK.
14+
## Best practices for the Azure Communication Services Calling Web SDK
1615

17-
## JavaScript voice and video calling SDK
16+
This section provides information about best practices associated with the Azure Communication Services Calling Web (JavaScript) SDK for voice and video calling.
1817

19-
### Plug-in microphone or enable microphone from device manager when Azure Communication Services call in progress
20-
When there's no microphone available at the beginning of a call, and then a microphone becomes available, the "noMicrophoneDevicesEnumerated" call diagnostic event is raised.
21-
When it happens, your application should invoke `askDevicePermission` to obtain user consent to enumerate devices. Then user will then be able to mute/unmute the microphone.
18+
### Plug in a microphone or enable a microphone from the device manager when a call is in progress
2219

23-
### Dispose video stream renderer view
24-
Communication Services applications should dispose `VideoStreamRendererView`, or its parent `VideoStreamRenderer` instance, when it's no longer needed.
20+
When no microphone is available at the beginning of an Azure Communication Services call, and then a microphone becomes available, the change raises a `noMicrophoneDevicesEnumerated` diagnostic event. When that event happens, your application should invoke `askDevicePermission` to obtain user consent to enumerate devices. The user can then mute or unmute the microphone.
21+
22+
### Dispose of VideoStreamRendererView
23+
24+
Communication Services applications should dispose of `VideoStreamRendererView`, or its parent `VideoStreamRenderer` instance, when it's no longer needed.
25+
26+
### Hang up the call on an onbeforeunload event
2527

26-
### Hang up the call on onbeforeunload event
2728
Your application should invoke `call.hangup` when the `onbeforeunload` event is emitted.
2829

29-
### Handling multiple calls on multiple Tabs on mobile
30-
Your application shouldn't connect to calls from multiple browser tabs simultaneously as this can cause undefined behavior due to resource allocation for microphone and camera on the device. Developers are encouraged to always hang up calls when completed in the background before starting a new one.
30+
### Handle multiple calls on multiple tabs
31+
32+
Your application shouldn't connect to calls from multiple browser tabs simultaneously on mobile devices. This situation can cause undefined behavior due to resource allocation for the microphone and camera on a device. We encourage developers to always hang up calls when they're completed in the background before starting a new one.
33+
34+
### Handle the OS muting a call when a phone call comes in
35+
36+
During an Azure Communication Services call (for both iOS and Android), if a phone call comes in or the voice assistant is activated, the OS automatically mutes the user's microphone and camera. On Android, the call automatically unmutes and video restarts after the phone call ends. On iOS, unmuting and restarting the video require user action.
3137

32-
### Handle OS muting call when phone call comes in.
33-
While on an Azure Communication Services call (for both iOS and Android) if a phone call comes in or Voice assistant is activated, the OS will automatically mute the user's microphone and camera. On Android, the call automatically unmutes and video restarts after the phone call ends. On iOS, it requires user action to "unmute" and "start video" again. You can listen for the notification that the microphone was muted unexpectedly with the quality event of `microphoneMuteUnexpectedly`. Do note in order to be able to rejoin a call properly you need to use SDK 1.2.3-beta.1 or higher.
38+
You can use the quality event of `microphoneMuteUnexpectedly` to listen for the notification that the microphone was muted unexpectedly. Keep in mind that to rejoin a call properly, you need to use SDK 1.2.3-beta.1 or later.
3439

3540
```javascript
3641
const latestMediaDiagnostic = call.api(SDK.Features.Diagnostics).media.getLatest();
@@ -42,28 +47,49 @@ if (isIosSafari && latestMediaDiagnostic.microphoneMuteUnexpectedly && latestMed
4247

4348
Your application should invoke `call.startVideo(localVideoStream);` to start a video stream and should use `this.currentCall.unmute();` to unmute the audio.
4449

45-
### Device management
50+
### Manage devices
51+
4652
You can use the Azure Communication Services SDK to manage your devices and media operations.
47-
- Your application shouldn't use native browser APIs like `getUserMedia` or `getDisplayMedia` to acquire streams outside of the SDK. If you do, you have to manually dispose your media streams before using `DeviceManager` or other device management APIs via the Communication Services SDK.
53+
54+
Your application shouldn't use native browser APIs like `getUserMedia` or `getDisplayMedia` to acquire streams outside the SDK. If you do, you must manually dispose of your media streams before using `DeviceManager` or other device management APIs via the Communication Services SDK.
4855

4956
#### Request device permissions
50-
You can request device permissions using the SDK:
51-
- Your application should use `DeviceManager.askDevicePermission` to request access to audio and/or video devices.
52-
- If the user denies access, `DeviceManager.askDevicePermission` will return 'false' for a given device type (audio or video) on subsequent calls, even after the page is refreshed. In this scenario, your application must detect that the user previously denied access and instruct the user to manually reset or explicitly grant access to a given device type.
5357

58+
You can request device permissions by using the SDK. Your application should use `DeviceManager.askDevicePermission` to request access to audio and/or video devices.
59+
60+
If the user denies access, `DeviceManager.askDevicePermission` returns `false` for a particular device type (audio or video) on subsequent calls, even after the page is refreshed. In this scenario, your application must:
61+
62+
1. Detect that the user previously denied access.
63+
1. Instruct the user to manually reset or explicitly grant access to a particular device type.
64+
65+
#### Manage the behavior of a camera that another process is using
66+
67+
- **On Windows Chrome and Windows Microsoft Edge**: If you start, join, or accept a call with video on, and another process (other than the browser that the web SDK is running on) is using the camera device, the call is started with audio only and no video. A `cameraStartFailed` User Facing Diagnostics flag is raised because the camera failed to start.
68+
69+
The same situation applies to turning on video mid-call. You can turn off the camera in the other process so that that process releases the camera device, and then start video again from the call. The video then turns on for the call, and remote participants start seeing the video.
70+
71+
This problem doesn't exist in macOS Chrome or macOS Safari because the OS lets processes and threads share the camera device.
72+
73+
- **On mobile devices**: If a *ProcessA* requests the camera device while *ProcessB* is using it, then *ProcessA* overtakes the camera device and *ProcessB* stop using it.
74+
75+
- **On iOS Safari**: You can't have the camera on for multiple call clients on the same tab or across tabs. When any call client uses the camera, it overtakes the camera from any previous call client that was using it. The previous call client gets a `cameraStoppedUnexpectedly` User Facing Diagnostics flag.
76+
77+
### Manage screen sharing
78+
79+
#### Closing an application doesn't stop it from being shared
80+
81+
Let's say that from Chromium, you screen share the Microsoft Teams application. You then select the **X** button on the Teams application to close it. Although the window is closed, the Teams application keeps running in the background. The icon still appears on the desktop taskbar. Because the Teams application is still running, it's still being screen shared with remote participants.
82+
83+
To stop the application from being screen shared, you have to take one of these actions:
84+
85+
- Right-click the application's icon on the desktop taskbar, and then select **Quit**.
86+
- Select the **Stop sharing** button on the browser.
87+
- Call the SDK's `Call.stopScreenSharing()` API.
5488

55-
#### Camera being used by another process
56-
- On Windows Chrome and Windows Microsoft Edge, if you start/join/accept a call with video on and the camera device is being used by another process other than the browser that the web SDK is running on, then the call is started with audio only and no video. A cameraStartFailed UFD is raised because the camera failed to start since it was being used by another process. Same applies to turning video on mid-call. You can turn off the camera in the other process so that that process releases the camera device, and then start video again from the call and video will now turn on for the call and remote participants start seeing your video.
57-
- This isn't an issue in macOS Chrome nor macOS Safari because the OS will let processes/threads share the camera device.
58-
- On mobile devices, if a ProcessA requests the camera device and it's being used by ProcessB, then ProcessA overtakes the camera device and ProcessB stop using the camera device
59-
- On iOS safari, you can't have the camera on for multiple call clients within the same tab nor across tabs. When any call client uses the camera, it overtakes the camera from any previous call client that was using it. Previous call client gets a cameraStoppedUnexpectedly UFD.
89+
#### Safari can do only full-screen sharing
6090

61-
### Screen sharing
62-
#### Closing out of application doesn't stop it from being shared
63-
For example, lets say that from Chromium, you screen share the Microsoft Teams application. You then select on the "X" button on the Teams application to close it. The Teams application won't be closed and it will still be running in the background. You'll even still see the icon in the bottom right of your desktop bar. Since the Teams application is still running, that means that it's still being screen shared and the remote participant in the call can still see your Teams application being screen shared. In order to stop the application from being screen shared, you have to right click its icon on the desktop bar and then click on quit. Or you have to click on "Stop sharing" button on the browser. Or call the SDK's Call.stopScreenSharing() API.
91+
Safari allows screen sharing only for the entire screen. That behavior is unlike Chromium, which lets you screen share the full screen, a specific desktop app, or a specific browser tab.
6492

65-
#### Safari can only do full screen sharing
66-
Safari only allows to screen share the entire screen. Unlike Chromium, which lets you screen share full screen, specific desktop app, or specific browser tab.
93+
#### You can grant screen-sharing permissions on macOS
6794

68-
#### Screen sharing permissions on macOS
69-
In order to do screen sharing in macOS Safari or macOS Chrome, screen recording permissions must be granted to the browsers in the OS menu: "Systems Preferences" -> "Security & Privacy" -> "Screen Recording."
95+
To do screen sharing in macOS Safari or macOS Chrome, grant the necessary permissions to the browsers on the OS menu: **System Preferences** > **Security & Privacy** > **Screen Recording**.

0 commit comments

Comments
 (0)