You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Azure Communication Services - best practices
3
-
description: Learn more about Azure Communication Service best practices
3
+
description: Learn more about Azure Communication Service best practices.
4
4
author: srahaman
5
5
manager: akania
6
6
services: azure-communication-services
@@ -10,71 +10,24 @@ ms.date: 06/30/2021
10
10
ms.topic: conceptual
11
11
ms.service: azure-communication-services
12
12
ms.custom: devx-track-js
13
+
zone_pivot_groups: acs-plat-web-native
13
14
---
14
15
15
16
# Best practices: Azure Communication Services calling SDKs
16
17
This article provides information about best practices related to the Azure Communication Services calling SDKs.
17
18
18
-
## Azure Communication Services web JavaScript SDK best practices
19
-
This section provides information about best practices associated with the Azure Communication Services JavaScript voice and video calling SDK.
19
+
::: zone pivot="platform-web"
20
+
[!INCLUDE [Web](includes/best-practices-web.md)]
21
+
::: zone-end
20
22
21
-
## JavaScript voice and video calling SDK
22
-
23
-
### Plug-in microphone or enable microphone from device manager when Azure Communication Services call in progress
24
-
When there is no microphone available at the beginning of a call, and then a microphone becomes available, the "noMicrophoneDevicesEnumerated" call diagnostic event will be raised.
25
-
When this happens, your application should invoke `askDevicePermission` to obtain user consent to enumerate devices. Then user will then be able to mute/unmute the microphone.
26
-
27
-
### Dispose video stream renderer view
28
-
Communication Services applications should dispose `VideoStreamRendererView`, or its parent `VideoStreamRenderer` instance, when it is no longer needed.
29
-
30
-
### Hang up the call on onbeforeunload event
31
-
Your application should invoke `call.hangup` when the `onbeforeunload` event is emitted.
32
-
33
-
### Handling multiple calls on multiple Tabs on mobile
34
-
Your application should not 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.
35
-
36
-
### Handle OS muting call when phone call comes in.
37
-
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 will need to use SDK 1.2.3-beta.1 or higher.
if (isIosSafari &&latestMediaDiagnostic.microphoneMuteUnexpectedly&&latestMediaDiagnostic.microphoneMuteUnexpectedly.value) {
43
-
// received a QualityEvent on iOS that the microphone was unexpectedly muted - notify user to unmute their microphone and to start their video stream
44
-
}
45
-
```
46
-
47
-
Your application should invoke `call.startVideo(localVideoStream);` to start a video stream and should use `this.currentCall.unmute();` to unmute the audio.
48
-
49
-
### Device management
50
-
You can use the Azure Communication Services SDK to manage your devices and media operations.
51
-
- Your application shouldn't use native browser APIs like `getUserMedia` or `getDisplayMedia` to acquire streams outside of the SDK. If you do, you'll have to manually dispose your media stream(s) before using `DeviceManager` or other device management APIs via the Communication Services SDK.
52
-
53
-
#### Request device permissions
54
-
You can request device permissions using the SDK:
55
-
- Your application should use `DeviceManager.askDevicePermission` to request access to audio and/or video devices.
56
-
- 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.
57
-
58
-
59
-
#### Camera being used by another process
60
-
- On Windows Chrome and Windows 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 will be started with audio only and no video. A cameraStartFailed UFD will be 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 will start seeing your video.
61
-
- This is not an issue in macOS Chrome nor macOS Safari because the OS will let processes/threads share the camera device.
62
-
- On mobile devices, if a ProcessA requests the camera device and it is being used by ProcessB, then ProcessA will overtake the camera device and ProcessB will stop using the camera device
63
-
- On iOS safari, you cannot have the camera on for multiple call clients within the same tab nor across tabs. When any call client uses the camera, it will overtake the camera from any previous call client that was using it. Previous call client will get a cameraStoppedUnexpectedly UFD.
64
-
65
-
### Screen sharing
66
-
#### Closing out of application does not stop it from being shared
67
-
For example, lets say that from Chromium, you screen share the Microsoft Teams application. You then click on the "X" button on the Teams application to close it. The Teams application will not be closed and it will still be running in the background. You will even still see the icon in the bottom right of your desktop bar. Since the Teams application is still running, that means that it is 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 will have to right click its icon on the desktop bar and then click on quit. Or you will have to click on "Stop sharing" button on the browser. Or call the sdk's Call.stopScreenSharing() API.
68
-
69
-
#### Safari can only do full screen sharing
70
-
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.
71
-
72
-
#### Screen sharing permissions on macOS
73
-
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".
title: Azure Communication Services - best practices for Calling Native SDK
3
+
description: Learn more about Azure Communication Service best practices for Calling Native SDK.
4
+
author: garchiro7
5
+
manager: chpalmer
6
+
services: azure-communication-services
7
+
8
+
ms.author: jorgarcia
9
+
ms.date: 02/08/2024
10
+
ms.topic: include
11
+
ms.service: azure-communication-services
12
+
---
13
+
14
+
## Azure Communication Services native SDK best practices
15
+
16
+
This section provides information about best practices associated with the Azure Communication Services voice and video calling native SDK.
17
+
18
+
## Supported platforms
19
+
20
+
Here are the minimum OS platform requirements to ensure optimal functionality of the Calling Native SDKs.
21
+
22
+
### [iOS](#tab/ios)
23
+
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+.
27
+
28
+
### [Android](#tab/android)
29
+
30
+
- Support for Android API Level 21 or Higher.
31
+
- Support for Java 7 or higher.
32
+
- Support for Android Studio 2.0.
33
+
-**Android Auto** and **IoT devices running Android** are currently not supported.
34
+
35
+
### [Windows](#tab/windows)
36
+
37
+
- Support for UWP (Universal Windows Platform).
38
+
- Support for WinUI 3.
39
+
40
+
---
41
+
42
+
## App request device permissions
43
+
44
+
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 it's enabled. The consumer authorizes these access rights, so verify that they have been granted permission previously.
45
+
46
+
### [iOS](#tab/ios)
47
+
48
+
-`NSMicrophoneUsageDescription` for microphone access.
49
+
-`NSCameraUsageDescription` for camera access.
50
+
51
+
### [Android](#tab/android)
52
+
53
+
In the Application Manifest (`app/src/main/AndroidManifest.xml`). Verify the following lines:
Go to `Package.appxmanifest` and select capabilities:
69
+
70
+
-`Internet (Client)` & `Internet (Client & Server)` for network access.
71
+
-`Microphone` to access the audio feed of the microphone.
72
+
-`Webcam` to access the video feed of the camera.
73
+
74
+
---
75
+
76
+
## Configure the logs
77
+
78
+
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.
79
+
80
+
## Track Call ID
81
+
82
+
**`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.
83
+
84
+
## Subscribe to UFD (User Facing Diagnostics) and media quality statistics
85
+
86
+
-[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.
87
+
-[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.
88
+
89
+
## Error Handling
90
+
91
+
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.
92
+
93
+
### Managing Video Streams
94
+
95
+
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.
96
+
97
+
## General memory management
98
+
99
+
**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.
100
+
101
+
**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.
102
+
103
+
## Camera or microphone being used by another process
104
+
105
+
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.
title: Azure Communication Services - best practices for Calling Web SDK
3
+
description: Learn more about Azure Communication Service best practices for Calling Web SDK.
4
+
author: srahaman
5
+
manager: akania
6
+
services: azure-communication-services
7
+
8
+
ms.author: srahaman
9
+
ms.date: 06/30/2021
10
+
ms.topic: include
11
+
ms.service: azure-communication-services
12
+
---
13
+
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.
16
+
17
+
## JavaScript voice and video calling SDK
18
+
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.
22
+
23
+
### Dispose video stream renderer view
24
+
Communication Services applications should dispose `VideoStreamRendererView`, or its parent `VideoStreamRenderer` instance, when it's no longer needed.
25
+
26
+
### Hang up the call on onbeforeunload event
27
+
Your application should invoke `call.hangup` when the `onbeforeunload` event is emitted.
28
+
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.
31
+
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.
if (isIosSafari &&latestMediaDiagnostic.microphoneMuteUnexpectedly&&latestMediaDiagnostic.microphoneMuteUnexpectedly.value) {
39
+
// received a QualityEvent on iOS that the microphone was unexpectedly muted - notify user to unmute their microphone and to start their video stream
40
+
}
41
+
```
42
+
43
+
Your application should invoke `call.startVideo(localVideoStream);` to start a video stream and should use `this.currentCall.unmute();` to unmute the audio.
44
+
45
+
### Device management
46
+
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.
48
+
49
+
#### 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.
53
+
54
+
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.
60
+
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.
64
+
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.
67
+
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."
0 commit comments