你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
最佳做法:Azure 通信服务呼叫 SDK
本文介绍了与 Azure 通信服务呼叫 SDK 相关的最佳做法。
Azure 通信服务 Web JavaScript SDK 最佳做法
本部分介绍了与 Azure 通信服务 JavaScript 语音和视频呼叫 SDK 相关的最佳做法。
JavaScript 语音和视频呼叫 SDK
当 Azure 通信服务呼叫正在进行时,插入麦克风或从设备管理器启用麦克风
如果通话开始时没有可用的麦克风,然后一个麦克风变为可用时,将引发“noMicrophoneDevicesEnumerated”通话诊断事件。
发生这种情况时,应用程序应调用 askDevicePermission
以获得用户同意来枚举设备。 然后,用户将能够将麦克风静音/取消静音。
释放视频流呈现器视图
当不再需要时,通信服务应用程序应释放 VideoStreamRendererView
或其父级 VideoStreamRenderer
实例。
挂断对 onbeforeunload 事件的呼叫
onbeforeunload
事件发出时,应用程序应调用 call.hangup
。
处理移动设备上多个选项卡上的多个呼叫
应用程序不应同时连接到来自多个浏览器选项卡的呼叫,因为由于设备上麦克风和相机的资源分配,这可能会导致未定义的行为。 建议开发人员在后台完成呼叫后始终挂断呼叫,然后再启动新的呼叫。
来电时处理操作系统静音呼叫。
在 Azure 通信服务通话中(适用于 iOS 和 Android),如果有来电或激活了语音助理,操作系统会自动将用户的麦克风和相机静音。 在 Android 上,通话在电话呼叫结束后自动取消静音,视频会重新开始。 在 iOS 上,则要求用户再次执行“取消静音”和“启动视频”操作。 可以通过质量事件 microphoneMuteUnexpectedly
来侦听麦克风意外静音的通知。 请注意,为了能够正确地重新加入通话,需要使用 SDK 1.2.3-beta.1 或更高版本。
const latestMediaDiagnostic = call.api(SDK.Features.Diagnostics).media.getLatest();
const isIosSafari = (getOS() === OSName.ios) && (getPlatformName() === BrowserName.safari);
if (isIosSafari && latestMediaDiagnostic.microphoneMuteUnexpectedly && latestMediaDiagnostic.microphoneMuteUnexpectedly.value) {
// received a QualityEvent on iOS that the microphone was unexpectedly muted - notify user to unmute their microphone and to start their video stream
}
应用程序应调用 call.startVideo(localVideoStream);
来启动视频流,并且应该使用 this.currentCall.unmute();
取消音频的静音。
设备管理
可以使用 Azure 通信服务 SDK 来管理设备和媒体操作。
- 应用程序不应使用本机浏览器 API(如
getUserMedia
或getDisplayMedia
)来获取 SDK 之外的流。 如果这样做,则必须在使用DeviceManager
或其他设备管理 API 之前,通过通信服务 SDK 手动释放媒体流。
请求设备权限
可以使用 SDK 请求设备权限:
- 应用程序应使用
DeviceManager.askDevicePermission
来请求对音频和/或视频设备的访问权限。 - 如果用户拒绝访问,
DeviceManager.askDevicePermission
将在后续呼叫时对给定的设备类型(音频或视频)返回“false”,即使在页面刷新后也是如此。 在这种情况下,应用程序必须检测到用户之前曾拒绝访问,并指示用户手动重置或明确授予对给定设备类型的访问权限。
另一个进程正在使用相机
- 在 Windows Microsoft Chrome 和 Windows Edge 上,如果在视频开启的情况下开始/加入/接受通话,并且除运行 Web SDK 的浏览器外的其他进程正在使用相机设备,则只能开启语音通话,不能进行视频通话。 这将引发 cameraStartFailed UFD,因为另一进程正在使用相机,导致相机无法启动。 这同样适用于在通话中途打开视频的情况。 你可以在另一个进程中关闭相机,令该进程释放相机设备,然后从通话中再次启动视频,此时则能开启视频通话,远程参与者也能看到你的视频。
- 这在 macOS Chrome 和 macOS Safari 中都不是问题,因为 OS 会让进程/线程共享相机设备。
- 在移动设备上,如果进程 A 请求使用相机设备,而此时进程 B 正在使用相机,则进程 A 将占用相机设备,进程 B 将停用相机
- 在 iOS Safari 上,不能为同一选项卡或跨选项卡的多个通话客户端开启相机。 任何通话客户端在使用相机时,都会从上一次使用它的任何通话客户端中接管相机。 上次使用相机的通话客户端将获取 cameraStoppedUnexpectedly UFD。
屏幕共享
关闭应用程序不会阻止其共享
例如,假设从 Chromium 对 Microsoft Teams 应用程序进行屏幕共享。 然后,选择 Teams 应用程序上的“X”按钮将其关闭。 Teams 应用程序不会关闭,它仍将在后台运行。 你甚至可以在桌面栏的右下角看到图标。 由于 Teams 应用程序仍在运行,这意味着它仍在进行屏幕共享,通话中的远程参与者仍可以看到正在共享的 Teams 应用程序。 若要停止对应用程序进行屏幕共享,必须右键单击桌面栏上的图标,然后单击退出。 或者,必须单击浏览器上的“停止共享”按钮。 或调用 SDK 的 Call.stopScreenSharing() API。
Safari 只能进行全屏共享
Safari 仅允许对整个屏幕进行屏幕共享。 而 Chromium 则不同,它允许对全屏、特定桌面应用或特定浏览器标签页进行屏幕共享。
macOS 上的屏幕共享权限
若要在 macOS Safari 或 macOS Chrome 中进行屏幕共享,必须在 OS 菜单中向浏览器授予屏幕录制权限:“系统首选项”->“安全和隐私”->“屏幕录制”。
Azure 通信服务本机 SDK 最佳做法
本部分介绍了与 Azure 通信服务语音和视频通话本机 SDK 相关的最佳做法。
支持的平台
下面是确保通话本机 SDK 的最佳功能的最低 OS 平台要求。
应用请求设备权限
若要使用通话本机 SDK 进行呼叫或接收呼叫,必须授权每个平台访问设备资源。 作为开发人员,应提示用户提供访问权限并确保已启用。 使用者会授权这些访问权限,因此请验证他们以前是否被授予了权限。
配置日志
根据日志文件检索教程实现日志记录比以往任何时候都更加重要。 详细的日志有助于诊断特定于满足最低 SDK 条件的设备模型或 OS 版本的问题。 我们不建议开发人员在没有日志的情况下开始配置日志 API,因为 Microsoft 支持团队无法帮助调试和排查通话问题。
跟踪通话 ID
CallID
是通话的唯一 ID。 它可标识来自单个通话期间连接的所有参与者和终结点的相关事件,在大多数情况下,你可用它来查看日志,Microsoft 支持团队会要求你提供该 ID 以帮助对通话进行故障排除。 你应跟踪在应用中配置的遥测中的 CallID
,可以按照故障排除指南中的准则了解如何针对每个平台进行检索。
订阅 UFD(面向用户的诊断)和媒体质量统计信息
- 面向用户的诊断 (UFD) 可用于检查通话的各种属性,以确定通话期间可能出现的影响客户的问题。
- 媒体质量统计信息可检查传入和传出呼叫指标的低级别音频、视频和屏幕共享质量指标。 我们建议在通话结束后收集数据并将其发送到管道引入。
错误处理
如果在通话或实现期间出现任何错误,则方法将返回包含错误代码的错误对象。 使用这些错误对象进行适当的错误处理并显示警报至关重要。 通话状态还会返回错误代码,以帮助确定通话失败的原因。 可参考故障排除指南来解决任何问题。
管理视频流
请确保 UI 上不再显示视频时释放 VideoStreamRendererView
。 使用 VideoStreamType
确定流的类型。
常规内存管理
预分配资源。 在应用的启动阶段(而不是按需)初始化通话客户端和任何必要的资源。 此方法可减少启动通话时的延迟。
正确释放。 确保在使用后正确释放所有通话对象,以释放系统资源并避免内存泄漏。 请确保取消订阅事件,防止内存泄漏。
另一个进程正在使用相机或麦克风
请务必注意,如果多个进程同时尝试访问相机或麦克风,则请求访问的第一个过程将控制设备。 因此,第二个进程将立即失去对相机或麦克风的访问权限。
使用 UI 库优化应用大小
由于某些原因,在软件开发中优化库的大小至关重要,尤其是在应用程序变得越来越复杂和资源密集型的情况下。
应用程序性能:较小的库可减少应用程序必须加载、分析和执行的代码量。 这可以显著提高应用程序的启动时间和整体性能,尤其是在资源有限的设备上。
内存使用率:通过最小化库大小,可以减少应用程序的运行时内存占用。 对于移动设备而言,这一点非常重要,因为移动设备的内存往往有限。 内存使用率较低可以减少系统崩溃,提高多任务性能。
后续步骤
有关详细信息,请参阅以下文章: