小鱼小程序服务和SDK方案重构之后,存在一定的变化,详细内容如下:
提示
小鱼小程序SDK v3.x 是一个向下兼容的版本,因整体改动较大,我们争取做到详细的测试,若在项目中因特殊场景产生的集成问题,可以随时和小鱼易连进行沟通解决;
在开始升级改动之前,建议先整体浏览小程序SDK v3.8文档和API介绍,并详细阅读布局和请流针对布局能力的改动介绍,或者可以直接运行v3.8版本的小程序SDK Demo查看自动布局和自定义布局的效果;
此处将介绍项目中将SDK从 v1.x 迁移到 v3.x 的UI模式的改动详情,请详细阅读;
v3.8版本开始,启用新服务和域名,在微信公众平台-开发管理-开发设置中配置新域名:
request合法域名:https://wxrtc.xylink.com
socket合法域名:wss://wxrtc.xylink.com
提示
注意,v1.x版本配置的:official.opensso.tencent-cloud.com 和 prdtxlive.xylink.com 可以移除;
SDK v1.x的包名 xylink-sdk
更改为 @xylink/xy-mp-sdk
,请先移除之前的npm包,重新安装最新的beta npm包:
# 移除旧包
$ npm uninstall xylink-sdk
# 安装新包
$ npm install @xylink/xy-mp-sdk --save
如果是yarn,则使用remove和add命令移除和安装;
安装完成后,记得在微信开发者工具上重新构建npm模块:工具->构建npm;
变更
组件的加载路径:
【旧方式】v1.x版本加载组件:
"usingComponents": {
"xylink-room": "xylink-sdk"
},
【新方式】v3.x版本加载组件,并新增屏幕横屏(必须配置)和自定义导航条(可选,如果希望使用系统默认的导航条,可以不用配置):
"usingComponents": {
"xylink-room": "@xylink/xy-mp-sdk/component"
},
"pageOrientation": "landscape",
"navigationStyle": "default"
其中:
pageOrientation
配置为landscape
代表横屏显示小程序页面;navigationStyle
配置default
代表使用系统导航条,设置为custom
代表自定义导航条,即不显示小程序自带的顶部导航条,由用户在UI上自行实现;createClient
中container的offset设置自动布局下画面容器的上/下/左/右的偏移量,更好的适配异性屏幕;提示
由于整体UI组件和屏幕都设置为横屏模式,所以针对自动布局,UI组件内部会处理元素的位置和大小计算、移除之前的元素旋转样式,并作展示;
针对自定义布局的业务,需要开发者重新计算参会者的位置和大小,移除元素的旋转样式。
提示
iOS 16.x系统以上,在手机开启竖屏锁定的情况下,微信小程序接收小鱼设备画面旋转90度,建议提示用户开启自动旋转规避此问题;
微信会在下一个新版本修复此问题,建议后面升级微信新版本;
【旧方式】v1.x在使用组件前需要引入room.js
,调用登录和呼叫方法,才可完成入会:
import xylink from 'xylink-sdk/common/room.js'
// 可选项,私有云环境配置域名,公有云不需要调用,需要在Login前调用:
xylink.setDomain(wsDomain, requestDomain);
// 小鱼登录方法
xylink.login(token, (response) => {
// ....
})
// 小鱼呼叫会议方法
xylink.makeCall(number, password, name, (response) => {
// 响应makeCall状态,如果为200,可以进行隐藏呼叫Loading页面,执行start方法通知组件内部进行一系列入会操作
const { code, message } = response;
if (code === 200) {
// 隐藏Loading
this.setData({
meetingLoading: false,
});
// 通知内部事件开始做入会准备,连接WSS、启动事件推送
this.xylinkRoomComponent.start();
} else {
// 呼叫失败,提示信息
this.showToast(message);
}
})
【新方式】v3.x版本开始,SDK包中将不再包含room.js
文件模块,由XYRTC
模块提供的createClient()
方法创建client
实例,并调用对外的方法,详细对外的方法参见API参考:
1、导入并创建XYClient实例:
提示
XYRTC.createClient()创建了一个单例对象client,在多个小程序页面之间共享一个实例,可以重复调用获取实例;
import XYRTC from "@xylink/xy-mp-sdk";
Page({
// 页面加载时触发
onLoad(option) {
// 保存到当前页面的实例上,后续需要调用client内部的方法
this.XYClient = XYRTC.createClient({
// 自动布局下针对画面容器上下左右的偏移量
container: {
offset: [0, 0, 0, 0]
}
});
},
})
2、【可选项】针对私有云环境配置服务域名:
// 公有云不需要调用,如需要调用,请在Login前调用:
// eg: wxrtc.xylink.com
this.XYClient.setServer(server);
3、调用XYClient实例上的登录方法:
this.XYClient.login(token, this.onCallbackGetNumber);
// onCallbackGetNumber回调函数的逻辑不变
4、调用XYClient实例上的呼叫makeCall方法,此处有两处改动:
this.XYClient.makeCall({ number, password, displayName }, (response) => {
// 最新的逻辑仅需要处理异常呼叫入会即可,其他逻辑不需要再处理
const { code, message } = response;
if (code !== 200) {
this.showToast({ title: message }, () => {
// 退出呼叫页面
wx.navigateBack({ delta: 1 });
});
}
});
1、移除组件对外的所有方法:start、switchCamera、setDebug;
新版本SDK下,无需通过this.selectComponent()
获取
的实例,旧版本对外提供的三个方法因此存在变动:
2、新增方法:hangup
新版本下,提供了主动挂断会议方法(hangup),方便用户在需要退会时主动调用。在此之前是根据组件的销毁事件自动调用,再部分场景下,可能会有一定的延迟性。
1、新增connected事件
新增事件,之前由callStatus提供,新版本将入会成功的事件单独抽离,接收到此消息后,即代表成功加入会议;
onRoomEvent(event) {
const { type, detail } = event.detail;
switch (type) {
case 'connected':
// 加入会议成功,隐藏呼叫等待页面
this.setData({ meetingLoading: false, });
break;
// 其他处理...
}
}
2、新增disconnected事件
新增事件,之前由callStatus提供,新版本将各种原因需要进行退会处理的事件单独抽离为disconnected
事件,开发者监听此事件,收到后需要处理退出会议操作;
onRoomEvent(event) {
const { type, detail } = event.detail;
switch (type) {
case "disconnected":
// 逻辑同之前一致,收到后判断是否有message,存在则提示并退会,不存在直接退出会议
// 方法见Demo示例程序
this.disConnectMeeting(detail);
break;
}
}
3、新增permission事件
新增麦克风和摄像头授权错误事件,UI模式下开发者暂时不需要额外处理此事件,内部会尝试进行重新授权操作,如果最终失败,则进行退会处理;
4、新增eventClick事件
UI模式下会上报点击当前画面的参会者信息;之前由event事件提供;
5、新增eventDoubleClick事件
UI模式下会上报双击当前画面的参会者信息;新版本新增事件;
6、新增eventLongPress事件
UI模式下会上报长按当前画面的参会者信息,之前由event事件提供;
7、新增memoryReport事件
之前由event事件上报,新版本单独抽离此事件,开发者收到此事件后,提示用户内存占用过高,可能导致画面卡顿或者小程序被微信杀掉问题;
8、新增audioStatus事件
新增麦克风实时状态事件,建议监听并设置对应的麦克风状态,以避免因会控操作等原因造成的本地麦克风状态不一致问题;
1、callStatus
callStatus事件移除,对应内部两个状态:connected
和 disconnected
事件将单独上报;
2、roomExit
roomExit事件是因组件异常导致的退会,和disconnected
事件属同一类型,所以合并到disconnected
上统一上报;
3、permissionFail
permissionFail事件只有在麦克风和摄像头授权错误时推送,新版本下统一更名为:permission
;
4、event
event事件移除,UI模式下新增eventClick
、eventDoubleClick
、eventLongPress
三个事件,分别代表画面被点击、双击、常按事件,并上报画面对应的参会者信息;
此步骤将详细介绍SDK Demo中会议界面样式的变动,具体到各个开发者自己的业务中,需要单独适配;
在新版本SDK在UI模式下,整体切换到横屏模式,所以样式需要由部分调整:
1、会议下方功能操作条样式调整:
// 旧方式
// 因为旧方式下,页面是竖屏方式布局,所以设定了宽度为10vw,高度100vh,通过内部元素旋转模拟出横屏效果
.xylink-operate-box {
position: fixed;
// ...其他样式
width: 10vw;
height: 100vh;
}
// 新方式
// 新方式下,由于屏幕整体设置为横屏模式,所以正常布局即可
.xylink-operate-box {
position: fixed;
// ...其他样式
width: 100vw;
height: 40px;
// 新增层级控制
z-index: 100;
}
2、会议下方功能操作条移除wxml元素中class为trans90的旋转类:
// 旧方式
<view class="xylink-operate-box xylink-operate-left">
<view bindtap="onSwitchPosition" class="trans90">
{{ devicePosition === 'front' ? "前置" : "后置" }}
</view>
<view bindtap="onChangeMuted" class="trans90">{{ muted ? "静音" : "取消静音" }}</view>
<view bindtap="onSwitchCamera" class="trans90">{{ camera ? "关闭视频" : "开启视频" }}</view>
<view bindtap="onStopMeeting" class="trans90">挂断</view>
</view>
// 新方式
<view class="xylink-operate-box xylink-operate-left">
<view bindtap="onSwitchPosition" class="">
{{ devicePosition === 'front' ? "前置" : "后置" }}
</view>
<view bindtap="onChangeMuted" class="">{{ muted ? "静音" : "取消静音" }}</view>
<view bindtap="onSwitchCamera" class="">{{ camera ? "关闭视频" : "开启视频" }}</view>
<view bindtap="onStopMeeting" class="">挂断</view>
</view>
因会议页面屏幕切换为横屏模式,坐标起始点位置和方向发生变化,需要调整tempalte中指定参会者的postion字段,详情改动见拉流和布局(v3.8+)文档;
如上是整体迁移到新版本小程序SDK的改动,如果在迁移过程中存在问题,请及时和我们沟通反馈,我们将积极解答问题;