@ylink-sdk/wechat-miniprogram
v1.0.12
Published
## 简介
Downloads
6
Readme
亿联会议微信小程序SDK
简介
通过@ylink-sdk/wechat-miniprogram,开发者可快速开发出基于亿联会议体系架构的会议小程序。
快速上手
集成SDK
安装SDK库
# 通过yarn安装 $ yarn add @ylink-sdk/wechat-miniprogram # 通过npm安装 $ npm install @ylink-sdk/wechat-miniprogram
提示:在通过npm/yarn安装/升级完成SDK库之后,需要执行构建npm操作,在工具菜单栏中执行:工具->构建 npm
升级库
# 通过yarn安装 $ yarn upgrade @ylink-sdk/wechat-miniprogram # 通过npm安装 $ npm update @ylink-sdk/wechat-miniprogram
加入入会功能,在需入会的js文件中引用sdk的方法
import ylink from '@ylink-sdk/wechat-miniprogram/lib.js'; Page({ data: { meeting: { meetingNum: '', displayName: '', pwd: '', }, ... }, ... onJoinMeeting() { ylink.join({ meetingNum: this.data.meeting.meetingNum, pwd: this.data.meeting.pwd, displayName: this.data.meeting.displayName }, (result) => { if (result.bizCode === 900200) { // 跳转至<ylink-room />引用的会议界面 wx.navigateTo({url: '/pages/meeting/index'}); } else { // 异常提示,开发者可基于业务码表进行映射提示 wx.showToast({ title: result.bizCode, icon: 'none', duration: 2000, }); } }); } })
加入会议功能,在需要会议功能的wxml使用组件,js中引用sdk的方法
在需引入组件的页面目录下,配置相应页面的xxx.json文件:
{ "usingComponents": { "ylink-room": "@ylink-sdk/wechat-miniprogram" }, // 会议界面布局默认是按照横屏模式来布局的 "pageOrientation": "landscape" }
在wxml文件中使用
<ylink-room />
组件,组件中的配置变量请参见API概览:<ylink-room id="ylink-room" beauty="{{8}}" handup="{{handup}}" muted="{{muted}}" camera="{{camera}}" hideSmallView="{{hideSmallView}}" devicePosition="{{devicePosition}}" bindonRoomEvent="onRoomEvent"> </ylink-room>
在Page中定义data属性及引入sdk方法
Page({ onReady() { // 缓存sdk <ylink-room/>组件节点context,为后续调用组件内部方法用 this.ylinkRoom = this.selectComponent('#ylink-room'); // 通知内部事件开始做初始化准备,启动RoomEvent this.ylinkRoom.start(); }, data: { devicePosition: 'front', handup: false, muted: false, camera: true, hideSmallView: false }, // 非常重要,基本业务处理都是基于此事件的通知进行处理。详细事件请参见API概览 onRoomEvent(ms) { console.log('### onRoomEvent ###', ms); const {event, body} = ms.detail; if (event === 'xxx') { // handle } else if (event === 'xxx') { // handle } } })
API概览
SDK提供了以下2个功能模块:
- lib.js 入会前的对接配置等
<ylink-room/>
组件,用于视频会议的控制
以下内容主体围绕这两部分进行说明
lib.js
在使用<ylink-room />
标签前需要先调用lib.js
的一些方法,才可完成入会。
import ylink from '@ylink-sdk/wechat-miniprogram/lib.js';
API总览
|方法|描述| |-|-| |setBaseURL|设置请求服务地址| |join|加入会议| |getMeeting|获取会议实例,可用于获取更多会议信息及会控|
API详述
setBaseURL
修改请求服务地址,需要在join之前进行设置(非必须),默认是线上环境(https://meetings.ylyun.com/wechat-app)。
ylink.setBaseURL(url: string): void;
join
加入会议,调用结果将在callback进行回调,入会成功时将返回{bizCode: 900200, user: {xxx}},异常时将返回{bizCode: 90xxxx, message: xxx},开发者可基于bizCode进行相关的提示和业务处理,具体的bizCode说明可查看的后面业务码表。
ylink.join(params: ParamsJoin, callback: (result: { bizCode: number; message?: string; user?: Record<string, any> }) => void): void;
- ParamsJoin参数说明
| 参数 | 类型 | 必须 | 说明 | | ----------- | ------ | ---- | ------------------------------------------ | | appId | string | √ | 鉴权key | | signature | string | √ | 鉴权认证信息,生成方式详见提供的DEMO的文档 | | timestamp | string | √ | 鉴权用的13位时间戳 | | meetingNum | string | √ | 亿联会议会议号 | | pwd | string | | 亿联会议会议密码,会议有设置密码,则必需 | | displayName | string | √ | 显示名,必需 |
- 示例
ylink.join({
appId: 'xxx',
signature: 'xxx',
timestamp: 'xxx',
meetingNum: 'xxx',
pwd: 'xxx',
displayName: 'xxx'
}, (result) => {
if (result.bizCode === 900200) {
wx.navigateTo({url: '/pages/meeting/index'});
} else {
wx.showToast({
title: result.bizCode,
icon: 'none',
duration: 2000,
});
}
});
<ylink-room />
<ylink-room />
标签是基于<live-pusher />
和<live-player />
实现的用于视频会议的微信小程序自定义组件。
- 组件属性
| 属性值 | 类型 | 可选值 | 默认值 | 说明 | | -------------- | -------- | ---------- | ------ | ------------------------------------------------------------ | | beauty | Number | 0-9 | 6 | 美颜,0 表示关闭,支持动态设置 | | muted | Boolean | true/false | false | 禁音,true代表关闭麦克风,false代表开启麦克风,支持动态设置 | | camera | Boolean | true/false | true | 开/关摄像头,true代表开启摄像头,false代表关闭摄像头,支持动态设置 | | handup | Boolean | true/false | false | 举手,当会议模式为申请发言时或入会者为观众时,此配置才生效,true代表举手状态,false代表手放下状态,支持动态设置 | | devicePosition | String | front/back | front | 使用前置/后置摄像头采集本地视频,front代表前置摄像头,back代表后置摄像头,支持动态设置 | | hideSmallView | Boolean | true/false | false | 是否隐藏小视图画面,支持动态设置 | | onRoomEvent | Function | N/A | | 必要,监听事件通知,详见下方 |
- 事件通知
<ylink-room />
标签通过onRoomEvent返回内部事件,用于外部的业务自定义处理,如角色变更提示,请求开启视频的弹窗,字幕显示等,使用方式如下:
<!-- wxml文件引用组件 -->
<ylink-room ... bindonRoomEvent="onRoomEvent" />
// 在js中定义接收函数
onRoomEvent(ms: IEventMS) {
const { event, body } = ms.detail;
if (event === 'xxx') {
// handle
}
}
// 主要接收ms.detail用于业务处理
interface IEventMS {
...
detail: {
// 事件类型
event: string;
// 事件内容
body: {
// 新值
newVal: any;
// 旧值
oldVal: any;
// 异常错误码
bizCode?: number;
}
}
}
事件列表:
| 事件名称 | 说明 | 事件内容(body) | | -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | | roleChange | 入会用户角色变更,由远端主持人调整入会用户的身份引起 | body: ROLE; ROLE: coHost(主持人)/attendee(与会者)/audience(观众) | | audioChange | 入会用户音频状态(麦克风)变更,自身操作或远端主持人操作引起 | body: {deviceOn: boolean;sendOn: boolean;opBy:number}deviceOn:设备状态;sendOn:媒体状态;opBy:操作者(1表示远端,可基于此条件进行提示) | | handupChange | 入会用户举手状态变更,自身操作或远端主持人操作引起 | body: boolean; | | setAudio | 远端主持人请求开启音频 | body: {cred: string; sendOn: boolean;operator:{userID:number;}}cred:请求开启的凭证,当用户允许时需通过组件方法setAVCred传递给组件内 | | videoChange | 入会用户视频状态(摄像头)变更,自身操作或远端主持人操作引起 | body: {deviceOn: boolean;sendOn: boolean;}deviceOn:设备状态;sendOn:媒体状态;opBy:操作者(1表示远端,可基于此条件进行提示) | | setVideo | 远端主持人请求开启视频 | body: {cred: string; sendOn: boolean;operator:{userID:number;}}cred:请求开启的凭证,当用户允许时需通过组件方法setAVCred传递给组件内 | | displayNameChange | 入会用户显示名变更,由远端主持人操作引起 | body: string; | | spotlightVideoChange | 设置/取消入会用户为焦点视频变更,由远端主持人操作引起 | body: boolean; | | lobbyChange | 入会用户进入/离开等候室变更,会议配置或远端主持人操作引起 | body: boolean; | | barrageChange | 字幕消息变更,由远端主持人操作引起 | body: {position: string; contentType:string; content:string;}position:显示位置(top/medium/bottom);contentType:内容格式(text/plain|text/enriched);content:内容 | | leave | 入会用户离会 | body: {bizCode: number; reasonCode:number; message: string;} | | meetingChange | 会议信息变更通知,主要用于通知入会用户重新获取会议数据 | null |
- 组件方法
获取组件实例
通过小程序提供的this.selectComponent()方法获取组件实例,通过组件实例可以调用组件内部的方法详细方法可见下方方法总览;
const ylinkRoom = this.selectComponent('#ylink-room');
ylinkRoom.start();
组件方法总览
| 方法 | 说明 | | ---------- | ---------------------------------------------------- | | start | 开始执行组件内部初始化操作 | | setAVCred | 设置开启音视频媒体的凭证,当远端主持人请求开启时传递 | | getMeeting | 获取当前会议数据 | | setDebug | 设置日志输出 |
组件方法详述
start
初始化组件及内部事件,必需
ylinkRoom.start(): void;
setAVCred
设置请求打开音频或视频的认证cred
ylinkRoom.setAVCred(cred: string): void;
setDebug
设置日志输出,参数isConsole:输出sdk内部日志到调试台,默认true;isLog:输出sdk内部日志到小程序微信公众平台系统,默认false
ylinkRoom.setDebug(isConsole: boolean; isLog: boolean): void;
getMeeting
获取当前会议相关信息
ylinkRoom.getMeeting(): Meeting;
Meeting返回信息说明:
| 属性 | 说明 | | ---------------- | ------------------------------------------------------------ | | meetingNum | 会议号 | | createType | 会议创建类型,vmr(云会议),scheduled(预约会议),meetNow(即时会议) | | meetingType | 会议类型,meeting(云会议室), webinar(研讨会) | | pwd | 会议密码 | | startTime | 会议实际开启时间(第一个媒体入会的时间),单位毫秒 | | subject | 会议主题 | | lock | 会议是否锁定 | | speakingMode | 发言模式,free(自由发言),handUp(举手发言) | | participantCount | 已入会用户数量统计 | | recording.status | 录制状态,stopped:关闭 starting:正在开始 started:已开始 paused:已暂停 | | me | 自身信息 |
me信息说明
| 属性 | 说明 | | ---------------- | ------------------------ | | userID | 用户ID | | audio | 音频状态 | | video | 视频状态 | | displayName | 用户显示名 | | isHandUp | 是否举手 | | isInLobby | 是否在等候室 | | joinTime | 入会时间 | | role | 用户角色 | | handUpTime | 举手时间 | | isSpotlightVideo | 用户是否被设置为焦点视频 | | barrage | 字幕消息 |
- 组件slot
组件提供了一个插槽,用于用户自定义视频等待界面的UI。如无特殊需求,可不用设置,组件内部有默认的UI
使用方式如下:
<!-- wxml文件引用组件 -->
<ylink-room ...>
<!-- 插槽,开发者可自定义显示UI -->
<view slot="wait">
<view class="icon-wait" />
<view>请等待</view>
</view>
</ylink-room>
- 特殊-等候室
当入会用户在等候室时。组件的页面UI将展示为空,开发者可基于此自定义等候室的UI界面
业务码(bizCode)
| 业务码 | 说明 | | ------ | ---------------------------------------------------------- | | 900200 | 操作成功 | | 900400 | 请求参数不正确 | | 900403 | 该请求被禁止 | | 900408 | 请求超时,请稍候重试 | | 900500 | 服务器繁忙,请稍候重试 | | 900501 | 不支持该操作 | | 900503 | 服务不可用 | | 900511 | 服务器内部错误 | | 901100 | 您购买的服务已到期 | | 901304 | 会议未开始或已结束 | | 901305 | 会议已锁住 | | 901306 | 用户被从会议中移出 | | 901307 | 会议被结束 | | 901308 | 申请会议号失败 | | 901309 | 会议密码错误 | | 901310 | 会议互动端口上限 | | 901311 | 会议广播端口上限 | | 901314 | 主持人结束会议 | | 901315 | 只有一个与会者在会议中,超时结束会议 | | 901316 | 主持人未入会,会议中止 | | 901317 | 无其他参会者入会,会议中止 | | 901318 | 会议被删除,结束会议 | | 901319 | 服务不可用,移出使用相应服务的用户 | | 901320 | 被主持人移出会议 | | 901322 | 该会议成员不存在 | | 901326 | 媒体版本过于陈旧 | | 901336 | 检查用户名是否包含非法字符 | | 901337 | 限制账号登入 | | 901338 | 管理员删除会议,会议结束 | | 901339 | 主持人正在进行另一场会议,请稍后加入 | | 901341 | 会议尚未开始,请稍后呼入 | | 901344 | 主持人未加入会议,请稍候 | | 901349 | 允许等候室成员入会 | | 901350 | 会议成员移入等候室 | | 901351 | 观众切换为与会者 | | 901352 | 与会者切换为观众 | | 901353 | 会议已开启不允许参会者在主持人之前加入,至少存在一位主持人 | | 901354 | 不允许在主持人之前进入会议 | | 901356 | 会议禁止参会者入会 | | 901357 | 观众允许发言 | | 901358 | 观众禁止发言 | | 901359 | 用户主动离开会议 | | 901362 | 用户主动退出会议 | | 901364 | 会议已开启仅登录身份才能入会 | | 901376 | 已有与会者在会议中,无法重复加入 | | 901407 | 查询不到会议 | | 901403 | 会议室不存在 | | 901435 | 无可用的微信小程序入会服务包,请企业管理员购买 | | 901438 | 会议端口不足,无法加入会议 | | 901451 | 小程序入会服务容量不足,请使用其他方式加入会议 |