腾讯云 RTC SDK - 自动播放受限处理建议

简介

浏览器为了防止网页自动播放音视频对用户造成干扰，对音视频的自动播放功能做了限制：在用户与网页产生交互（例如点击、触摸页面等）之前，网页将被禁止播放带有声音的媒体。在 iOS 10+ 中，如果开启了省电模式，无声音的媒体也会被禁止播放。

受上述浏览器自动播放策略影响，在使用 TRTC Web SDK 时，可能会出现播放无声的问题。最常见的场景是：您的产品设计中，支持用户刷新页面后，无需用户点击，可自动进房拉流播放。

本文主要介绍如何解决因自动播放策略限制，导致播放失败的问题。

方案一：使用 SDK 提供的自动播放弹窗

默认情况下，当出现自动播放失败时，SDK 会弹窗引导用户与页面产生交互。当产生交互后，SDK 会主动调用接口恢复播放。

优点：业务侧无需做任何处理，简单高效。
缺点：SDK 提供的弹窗不一定符合业务产品设计要求，此时可考虑使用方案二。

SDK 提供的弹窗适配桌面端和移动端浏览器，样式如下：

SDK 会根据 navigator.language 的值来切换中英文弹窗提示。
当用户点击"确认"时，SDK 自动调用相关接口来恢复播放。
为尽可能保证弹窗处于最上层展示，其 z-index 值为 1500。

方案二：自定义处理自动播放限制

如果您希望完全控制自动播放失败时的用户体验，可以按照以下步骤来实现：

步骤 1：关闭 SDK 默认弹窗

在调用 trtc.enterRoom 接口时，将 enableAutoPlayDialog 参数设置为 false：

await trtc.enterRoom({
  // ... 其他参数
  enableAutoPlayDialog: false
});

步骤 2：监听自动播放失败事件（必做）

监听 AUTOPLAY_FAILED 事件来处理自动播放失败的情况。SDK 会自动监听用户的点击行为，在用户点击后自动恢复播放。

trtc.on(TRTC.EVENT.AUTOPLAY_FAILED, event => {
  // 在此处添加您的自定义处理逻辑
  // 例如：显示自定义提示框，引导用户点击页面
});

步骤 3：主动恢复播放（可选）

从版本 5.9.0 开始支持

在某些特殊场景下（如在 iframe 中或使用特定前端框架时），您可能需要主动调用恢复播放方法。此时可以使用事件中提供的 resume 方法：

trtc.on(TRTC.EVENT.AUTOPLAY_FAILED, (event) => {
  showCustomDialog(event);
});
function showCustomDialog(event) {
  const { userId, resume } = event;
  // 受限的用户 id 为 userId，resume 是恢复这个用户播放的函数
  // 需要显示一个自定义按钮，提示 userId 播放受限，在按钮点击回调里调用 'resume()'
}

重要提示

某些浏览器可能在每次播放前都会检查用户交互状态，因此可能多次触发自动播放失败事件。
在 iOS 微信浏览器和小程序 webview 中有特殊要求：
- 首次播放远端流时，必须在用户点击事件的回调函数中直接调用播放接口
- 不能使用 setTimeout 等异步方式调用播放接口，否则会导致播放失败
iframe 嵌入场景：如果将 TRTC SDK 嵌入在 iframe 中运行，需要注意以下限制：
- 父页面的点击事件无法穿透到 iframe 内部。如果用户只点击了父页面（iframe 外部），iframe 内的 document 无法捕获该点击事件，SDK 自动恢复播放的监听不会被触发。
- 父页面建议为 iframe 添加 allow="autoplay" 属性，以授权 iframe 内页面使用自动播放能力。但 allow="autoplay" 不等于关闭浏览器自动播放策略，它只是允许 iframe 尝试自动播放；对于有声媒体，浏览器仍可能要求用户先与 iframe 内页面产生交互。
- 如果使用 SDK 默认弹窗，请确保用户可以点击 iframe 内部的 SDK 弹窗来恢复播放。
- 如果需要自定义交互体验，可以关闭 SDK 默认弹窗（enableAutoPlayDialog: false），监听 AUTOPLAY_FAILED 事件，并在 iframe 内部展示自定义按钮，引导用户点击后调用事件中的 resume() 方法恢复播放。

Webview 中关闭自动播放策略限制

在 Android 和 iOS Webview 中的默认自动播放策略可能和浏览器中的不一致，您可以参考如下文档，在您的 App 中关闭自动播放限制。

Android Webview 关闭自动播放限制：调用 setMediaPlaybackRequiresUserGesture(false) 关闭自动播放限制。
iOS Webview 关闭自动播放限制：设置 mediaTypesRequiringUserActionForPlayback 为 WKAudiovisualMediaTypeNone

Tutorial: 自动播放受限处理建议