小鱼易连Web SDK v3.x迁移到v4.x指南

说明

小鱼易连Web SDK 4.x版本，此版本是基于v3.x版本架构升级版本，整个改动内容较大，若在项目中因特殊场景产生的集成问题，可以随时和小鱼易连进行沟通解决；

v4.0全新版本升级改动内容概括如下：

全新架构设计的Web SDK模块，保证SDK的稳定运行；
全新架构设计的自定义Track轨道，智能化管控音视频流，支持管道流方式多AI流插件动态接入；
全新设计的设备管理模块，支持手动强制指定、自动降级切换、缓存历史设备、系统默认切换等智能切换行为，开会更顺心；
全新设计实现的分享功能、支持最新最全的采集配置、支持分享时切换源、暂停/恢复分享、30帧率高流畅画面、高分辨率采集等智能行为；
新版本新增20余个功能（轮询多画面、对话模式、焦点画面、统一鉴权登录、屏幕截图、音频旁路、实时音量等等）、20余项优化增强项，总有一项符合你的心意；
全新的完整且全面的集成文档，详细的介绍SDK内容，通过文档说明可快速集成Web SDK到你的项目中；
全新的集成步骤，简化集成操作，不在困惑方法的返回类型，一切都恰到好处；
其他内容见版本说明

在开始升级改动之前，建议先整体浏览介绍文档、视频通话、API介绍、和文档，或者可以直接运行 v4 版本的Web SDK Demo查看运行效果；

升级改动

因整体改动内容较多，在设计时也尽可能保证历史的兼容处理，但也存在一些流程变动无法兼容，因此请详细阅读此篇升级文档，完成项目版本升级操作；

1、升级版本

npm install @xylink/xy-rtc-sdk -S

提示

安装完成后，通过查看package.json文件查看版本是v4.0.0+版本即可；

2、创建 XYRTCClient 模块

【旧方式】

旧版本是通过创建 Client 模块执行后续操作，示例如下：

import xyRTC, { Client }from '@xylink/xy-rtc-sdk';

const client: Client = xyRTC.createClient({   
  clientId: 'xxx',
  clientSecret: 'xxx',
  extId: 'xxx',
  muteAudio: true,
  muteVideo: true,
  container: {
    elementId: 'xxx',
    offset: [0, 0],
  }
});

【新方式】

由 XYRTC.createClient 创建 XYRTCClient 模块执行后续操作，示例如下：

import XYRTC, { XYRTCClient }from '@xylink/xy-rtc-sdk';

const XYClient: XYRTCClient = XYRTC.createClient({
  clientId: 'xxx',
  clientSecret: 'xxx',
  extId: 'xxx',
  ...
});

具体改动内容：

1、Client模块类型变更：Client -> XYRTCClient；

2、参数调整：

extId 参数变为必填项，请务必填写正确的企业ID信息；
移除 wssServer、httpServer、logServer 参数，通过参数 server 配置服务器地址（IP/域名 + 端口，举例：cloudapi.xylink.com:443），仅需配置一个服务器地址即可，或通过调用 XYRTCClient.setServerAddress 方法设置服务器地址；
移除 muteAudio、muteVideo 参数，通过 XYRTCClient.makeCall 方法设置呼叫时是否静音、是否开启摄像头入会；
移除 __hideId，通过 XYRTCClient.makeCall 设置是否隐身入会；
移除 __monitorMode，通过 XYRTCClient.makeCall 设置是否开启巡课模式；
移除 localHide，通过 XYRTCClient.setFeatureConfig 方法的 enableHideLocalView 参数设置初始是否隐藏本地画面；

3、登录方法

【旧方式】

所有登录方法的错误信息通过 return 返回。示例：

const result = await client.loginExternalAccount({   
  displayName: 'ThirdName',  
  extId: 'xxx', 
  extUserId: 'xxx',
});

if (result.code !== 'XYSDK:950120') {    
  message.info('登录失败');     
  return;   
}

【新方式】

所有登录方法的错误信息通过 Promise.reject 上报，调用方法时可以通过 catch 处理错误信息，具体可参考API文档，示例：

try {  
  await XYClient.loginExternalAccount({     
    displayName: 'ThirdName',
    extId: 'xxx', 
    extUserId: 'xxx',
  });
} catch(error) {
  message.info(error.msg || '登录失败');
}

4、发起呼叫

【旧方式】

旧方式是通过调用 Client.makeCall 方法返回 callStatus 判断是否成功，如果 callStatus 的值为 true，则可继续后续流程，示例：

const callStatus = await client.current.makeCall({
  token: 'xxx',
  confNumber: 'xxx',
  password: 'xxx',
  displayName: 'xxx'
});

if (callStatus) {
  ...
}

【新方式】

新版本 XYRTCClient.makeCall 整体通过 Promise 函数处理结果，遇到错误时通过 catch 处理错误信息，否则正常执行后续操作，示例如下：

try {
  await XYClient.makeCall({
    confNumber: 'xxx',
    password: 'xxx',
    displayName: 'xxx',
    muteAudio: false,
    muteVideo: false
  });
} catch (error) {
  message.info(error.msg);
}

具体改动内容：

移除token参数，业务流程无需关注此参数，简化集成步骤；
新增__hideId参数，用于设置隐身入会；
新增__monitorMode参数，用户设置是否开启巡课模式；

5、创建Stream

【旧方式】

示例:

const stream = xyRTC.createStream();

await stream.current.init({
  devices: {
    audioInputValue: '',
    audioOutputValue: '',
    videoInValue: '',
  },
})

【新方式】

新版本通过 XYRTCClient.createVideoAudioTrack 创建 VideoAudioTrack 轨道方式管理音视频流，示例：

const videoAudioTrack = await XYClient.createVideoAudioTrack();

// 设备切换
videoAudioTrack.on('device', (e: IDeviceManagerChangeValue) => {});
// 设备权限
videoAudioTrack.current.on('permission', (e: ICurrentPermission) => {});
// Track错误事件
videoAudioTrack.current.on('track-error', (e: IReturnResult) => {});

await videoAudioTrack.capture({
  audioInputId: 'xxx',
  audioOutputId: 'xxx',
  videoInputId: 'xx'
});

具体改动内容：

XYRTC移除 Stream 模块，使用自定义Track轨道方式管理音视频流；
XYRTCClient移除 createStream 方法；
XYRTCClient新增 createVideoAudioTrack 方法，通过此方法创建 VideoAudioTrack 模块；
VideoAudioTrack模块提供 capture 方法采集摄像头和麦克风音视频流；
XYRTCClient移除device、permission事件，通过 VideoAudioTrack 模块的device、permission、track-error事件监听设备信息变化、权限变化和 Track 错误事件；

6、推送Stream

【旧方式】

基于上一步获取到Stream进行推流，示例：

client.publish(stream, { isSharePeople: true });

【新方式】

基于上一步获取到的videoAudioTrack，使用 XYRTCClient.publish 进行推流，示例：

 XYClient.publish(videoAudioTrack);

具体改动：

调用 XYRTCClient.publish 方法传递 videoAudioTrack 进行推流操作，无需其他参数；

7、布局

【旧方式】

自定义布局数据通过监听 custom-layout 事件上报数据，示例如下：

// 自定义布局 
client.on('custom-layout', (e:ILayout) => {});  

// 自动布局 
client.on('layout', (e:ILayout) => {});

【新方式】

统一通过 layout 事件上报，示例：

// 自动布局、自定义布局  
XYClient.on('layout', (e: ILayout) => {});

具体改动内容：

1、v4.x+版本，统一使用 layout 事件上报布局结果，不再区分布局方式；

2、事件回调参数变动

roster、rotate类型变化，增加null类型；
avatar 类型变成 LayoutAvatar，提供头像类型和值，包含名称头像和人物图像；
移除 textAvatar 属性；
增加 rotationInfo 属性，提供当前参会者的旋转信息
roster 数据结构变化，id替换成key，作为参会者的唯一ID

8、渲染视频

【旧方式】

监听 layout 事件，使用Layout列表数据进行视频渲染，layout.roster.id 作为Video的 id，示例：

layout
  .filter((item) => item.pollingState !== AutoState.NULL)
  .map((item: ILayout) => {
  const { id } = item.roster || {};
        
  return (
    <Video item={item} key={id} id={id} ... />
  );
})

【新方式】

监听 layout 事件，使用Layout列表数据进行视频渲染，layout.id 作为Video的 id ，具体可参考文档，示例：

layout
  .filter((item) => item.pollingState !== AutoState.NULL)
  .map((item: ILayout) => {
  const { id } = item || {};
        
  return (
    <Video item={item} key={id} id={id} ... />
  );
})

具体改动内容：

Video组件的key和id：由 roster.id 更换为 layout.id；
setVideoRenderer函数：参数 id 更换为参会者的 Layout Id；
forceFullScreen函数：参数 id 更换为参会者的 Layout Id；

9、共享内容

【旧方式】

旧方式通过创建 Stream 模块，调用 Stream.createContentStream 方法创建共享视频流，示例如下：

// 发起共享
const shareContent = async () => {
  try {
    if (stream && client) {
      const result = await stream.createContentStream({ screenAudio: true });
      if (result) {
        setLocalShareContent(true);
        stream.current.on('start-share-content', () => {
          client.publish(stream, { isShareContent: true });
        });
        stream.on('stop-share-content', () => {
          stopShareContent();
        });
      } else {
        message.info('分享屏幕失败');
      }
    } else {
      message.info('分享屏幕失败');
    }
  } catch (err: any) {
    if (err && err.code !== 'XYSDK:950501') {
      message.info(err.msg || '分享屏幕失败');
    }
  }
};

// 结束共享
const stopShareContent = () => {
  client.stopShareContent();
  setLocalShareContent(false);
};

【新方式】

新版本通过 XYRTCClient.createContentTrack 创建 ContentTrack 模块创建和管理共享音视频流，示例：

let contentTrack;

// 发起共享
const shareContent = async () => {
  try {
    // 创建Track
    contentTrack = await XYClient.createContentTrack();

    // 监听事件
    contentTrack.on('start-share-content', () => {
      XYClient.publish(contentTrack.current as ContentTrack);
    });

    // 监听事件
    contentTrack.on('stop-share-content', () => {
      stopShareContent();
    });

    contentTrack.on('track-error', (e: IReturnResult) => {
      const { msg = '' } = e;
      msg && message.info(msg);
    });

    // 采集共享视频流
    await contentTrack.capture({ screenAudio: true });

    setLocalShareContent(true);
  } catch (err) {
    stopShareContent();
  }
};

// 结束共享
const stopShareContent = () => {
  if (contentTrack) {
    contentTrack.close();
    contentTrack = null;
  }
};

具体改动内容：

XYRTC 移除 Stream 模块，使用自定义Track轨道方式管理共享音视频流；
调用 XYRTCClient.createContentTrack 方法创建 ContentTrack 模块，并调用 XYRTCClient.capture 方法采集视频流；
调用 XYRTCClient.publish 方法传递 ContentTrack 进行推流操作，无需其他参数；
通过ContentTrack模块监听start-share-content、stop-share-content事件；
ContentTrack模块新增track-error事件监听；

10、设备管理

新版本SDK不再导出 DeviceManager 模块，使用 XYRTCCilent 模块创建会前设备管理、预览等功能；

具体改动内容：

移除 DeviceManager 模块；
通过 VideoAudioTrack 模块调用 switchDevice、getAudioLevel方法；
移除 switchAutoDevice 方法，不再支持自动配置是否切换设备逻辑，由系统默认设备和指定设备两种模式替代；
移除 setAudioOutput 方法，统一通过 switchDevice 方法来切换麦克风、扬声器、摄像头；
移除 Client 中的监听事件 device、permission，通过 VideoAudioTrack 来监听获取对应的信息；
调整 setOutputAudioDevice 方法导出方式，由SDK直接导出；

11、其他方法

具体改动内容：

隐藏本地画面方法：Client.toggleLocal 更换为 XYRTCClient.setHideLocalView，此方法必须传入指定的参数；
隐身入会切换互动方法： XYRTCClient.toggleHideId 增加参数hideId；
优化内外网呼叫流程：移除Helper模块中的 detectLocator 方法，新方式仅需在 XYRTC.createClient 中配置 isSupportHybridCloud 为 true即可，SDK内部会自动做探测切换环境；
移除 XYRTC.setConfig 方法，无登录模式通过 XYRTCClient.setLoginTokenInfo 传入外部登录的网关token信息进行鉴权；
方法更名：getVideoInfoByRotaion -> getVideoInfoByRotation；
迁会事件名称更换：medie_changed_migrate -> media-changed-migrate；
移除 Client.closePreviewStream 方法；
移除 checkSupportMobileWebRTC 方法，统一使用 XYRTC.checkSupportWebRTC 方法做兼容检测；

12、TS类型

具体改动：

模块变更：Client -> XYRTCClient；
类型名称变更：IMackCall -> IMakeCall；
类型名称变更：SpeakersInfo -> XYSpeakersInfo；
类型名称变更：SpeakersInfoObj -> SpeakersInfoItem；
类型名称变更：ILayoutState -> XYLayoutState，内容增加 ANSWER_PHONE（接听电话中）、移除INVALID；
类型名称变更：Notification -> XYNotification；
IDeviceInfo 类型增加 isSelected、isDefault、key 属性；
移除 IStatus，统一使用 IReturnResult；
类型名称变更：unMuteVideoQueryToastValue -> XYUnMuteVideoQueryToastValue;

13、其他功能

详细变动和新增信息可查看更新日志；

2024-07-18 10:15:11

导出PDF文档