自动播放受限处理方式

功能说明

为了提升用户体验并避免网页音视频自动播放打扰用户，浏览器对自动播放 (Autoplay) 功能进行了限制，禁止在用户未进行交互（如点击、触摸）前播放有声音的媒体。尽管纯视频通常不受此限制，但在某些环境（如 iOS Safari 的低电量模式或 iOS WKWebView，例如微信浏览器）下，纯视频的自动播放也可能受到限制。

为了解决这一问题，小鱼易连Web SDK提供了相关功能和API，用于处理音视频播放失败的情况，并指导开发者通过用户交互恢复音视频的播放。

参考

实现方法

自动播放失败时解除Autoplay限制

监听自动播放失败事件：play-failed，当音/视频因自动播放限制而无法播放时，会触发该事件，并通过type字段返回失败的媒体类型（video 或 audio）。开发者可以通过监听该事件，提示用户与页面交互以恢复播放。

提示

由于存在多个音视频轨道，一旦自动播放失败，可能会触发多次事件。为避免重复提示，建议使用状态管理机制，确保只引导用户进行一次交互以触发播放。这样可以减少冗余操作，提升用户体验。

与用户交互重新播放：通过用户点击或触摸等交互操作后，根据上报的媒体类型，调用相应的playAudio或 playVideo 方法，确保音频或视频流能够重新正常播放。

引导用户交互操作示例图如下：

提前引导用户进行交互

在进入会议之前，引导用户主动与页面进行交互，例如在点击“加入会议”按钮时播放音频资源，以避免自动播放失败。但是由于各大浏览器在自动播放策略上的实现存在差异，仍可能出现播放失败的情况。因此仍需监听播放失败事件、与用户交互触发播放等机制，确保音视频能够正常播放（第一步）。

示例代码

监听play-failed事件，显示提示按钮；

let audioPlayFailedCount = 0；

XYClient.on('play-failed', (data: XYPlayFailedInfo) => {
  const { type } = data;
  
  if (type === 'video') {
    // video组件显示播放按钮，用户点击后，调用playVideo方法，重新播放视频
    return;
  }

  if (type === 'audio') {
    if(audioPlayFailedCount === 0) {
       // 引导用户点击页面，如弹框按钮等，支持用户点击，调用playAudio方法，重新播放音频
       audioPlayFailedCount = 1;
    }
  }
})

点击按钮后，调用playAudio或playVideo方法，进行重新播放所有音频或视频；

const playVideo = () => {
  try {
    await XYClient.playVideo();
  } catch(error) {
    console.warn('play video error');
  }
}

const playAudio = () => {
  try {
    await XYClient.playAudio();
  } catch(error) {
    console.warn('plau audio error);
  }
}
  
<button onclick="playVideo">重新播放</button>          
<button onclick="playAudio">一键收听</button>

API 参考

2025-01-06 15:39:25

导出PDF文档