通话事件说明
有 3 种情况需要注册通话事件监听:
- 主动发起单人通话时,给
caller.call
方法传入listener
参数。 - 主动发起多人通话时,给
caller.callInGroup
方法传入listener
参数。 - 触发来电监听后,从
onSession
函数的参数里拿到session
实例后注册。
主动发起呼叫时注册
发起单人通话
caller.call
方法的 listener
参数对应要监听的事件,CallLib SDK 内部会把这些事件监听注册到 caller.call
方法产生的 session
实例上。
API 参考:call
/**
* 单呼,发起呼叫, 如果成功后会产生一个新的session
* @param targetId 被呼叫一方的用户 id (必填)
* @param mediaType 1->音频呼叫 or 2->音视频呼叫 (必填)
* @param listener session对象上注册的事件, 主动发起 call 成功后会产生一个新的session, 这个 session 上要注册的事件 (必填)
* @param constraints 获取音频或音视频资源时的参数 可选
* @param params.channelId 组织 Id 可选
*/
const { code, session } = await caller.call({
targetId: this.targetId,
mediaType,
listener: {
/**
* 当远端用户已开始响铃,表示对方已收到呼叫请求 (必填)
* @param sender 已响铃的用户
* @param session 当前的 session 对象
*/
onRinging: (sender: ISenderInfo, session: RCCallSession) => {
const { userId } = sender;
},
/**
* 当远端用户同意接听 (必填)
* @param sender 远端用户
* @param session 当前的 session 对象
*/
onAccept: (sender: ISenderInfo, session: RCCallSession) => {
const { userId } = sender;
},
/**
* 当有远端用户挂断 (必填)
* @param sender 远端用户
* @param reason 挂断的原因
* @param session 当前的 session 对象
*/
onHungup: (sender: ISenderInfo, reason: RCCallEndReason, session: RCCallSession) => {
const { userId } = sender;
},
/**
* 本端资源或远端资源已获取,track为本地音频或音视频, track不可设置成 Vue 组件的响应式数据 (必填)
* @param track 本端资源或远端资源
* @param session 当前的 session 对象
*/
onTrackReady: (track: RCTrack, session?: RCCallSession) => {
// track.isLocalTrack() 是否为本地资源
// track.isAudioTrack() 是否为音频
// track.isVideoTrack() 是否为视频
// track.getUserId() 产生该 track 的用户id
// 播放音频。如果为远端音频,建议直接播放。如为本端音频,建议不播放,以减少回音。
if (track.isAudioTrack() && !track.isLocalTrack()) {
track.play();
}
// 视频在对应的容器里播放
if (track.isVideoTrack()) {
const video = document.getElementById(
"video" + user.userId
) as HTMLVideoElement;
track.play(video);
}
},
/**
* 群组通话中有其他人被邀请加入
* @param sender 发送者 (必填)
* @param invitedUsers 被邀请的用户列表
* @param session 当前的 session 对象
*/
onMemberModify: (sender: ISenderInfo, invitedUsers: IInvitedUsers[], session: RCCallSession) => {
},
/**
* 通话类型改变时触发,例如: 从视频变成音频通话, (必填)
* @param sender 发送者
* @param mediaType 1为音频通话 2为视频通话
* @param session 当前的 session 对象
*/
onMediaModify: (sender: ISenderInfo, mediaType: RCCallMediaType, session: RCCallSession) => {
},
/**
* 对方静音后触发 (必填)
* @param muteUser 已静音的用户
* @param session 当前的 session 对象
*/
onAudioMuteChange: (muteUser: IMuteUser, session: RCCallSession) => {
},
/**
* 对方禁用视频后触发 (必填)
* @param muteUser 已禁用视频的用户
* @param session 当前的 session 对象
*/
onVideoMuteChange: (muteUser: IMuteUser, session: RCCallSession) => {
},
},
});
if (code === RCCallErrorCode.SUCCESS) {
// do something
}
发起多人通话
caller.callInGroup
方法的 listener
参数对应要监听的事件,CallLib SDK 内部会把这些事件监听注册到 caller.callInGroup
方法产生的 session
实例上。
API 参考:callInGroup
/**
* 发起群组呼叫, 如果成功后会产生一个新的session
* @param targetId 群组 Id (必填)
* @param userIds 被呼叫的群内成员 Id (必填)
* @param mediaType 0->音频呼叫 or 2->音视频呼叫 (必填)
* @param listener 新 session 对象上注册的事件, 主动发起 call 成功后会产生一个新的session, 这个 session 上要注册的事件 (必填)
* @param constraints 获取音频或音视频资源时的参数 (可选)
* @param channelId 组织 Id (可选)
*/
const { code, session } = await caller.callInGroup({
targetId: this.targetId,
userIds,
mediaType,
listener: {
/**
* 当远端用户已开始响铃,表示对方已收到呼叫请求 (必填)
* @param sender 已响铃的用户
* @param session 当前的 session 对象
*/
onRinging: (sender: ISenderInfo, session: RCCallSession) => {
const { userId } = sender;
},
/**
* 当远端用户同意接听 (必填)
* @param sender 远端用户
* @param session 当前的 session 对象
*/
onAccept: (sender: ISenderInfo, session: RCCallSession) => {
const { userId } = sender;
},
/**
* 当有远端用户挂断 (必填)
* @param sender 远端用户
* @param reason 挂断的原因
* @param session 当前的 session 对象
*/
onHungup: (sender: ISenderInfo, reason: RCCallEndReason, session: RCCallSession) => {
const { userId } = sender;
},
/**
* 本端资源或远端资源已获取,track为本地音频或音视频, track不可设置成 Vue 组件的响应式数据 (必填)
* @param track 本端资源或远端资源
* @param session 当前的 session 对象
*/
onTrackReady: (track: RCTrack, session?: RCCallSession) => {
// track.isLocalTrack() 是否为本地资源
// track.isAudioTrack() 是否为音频
// track.isVideoTrack() 是否为视频
// track.getUserId() 产生该 track 的用户id
// 播放音频。如果为远端音频,建议直接播放。如为本端音频,建议不播放,以减少回音。
if (track.isAudioTrack() && !track.isLocalTrack()) {
track.play();
}
// 视频在对应的容器里播放
if (track.isVideoTrack()) {
const video = document.getElementById(
"video" + user.userId
) as HTMLVideoElement;
track.play(video);
}
},
/**
* 群组通话中有其他人被邀请加入
* @param sender 发送者 (必填)
* @param invitedUsers 被邀请的用户列表
* @param session 当前的 session 对象
*/
onMemberModify: (sender: ISenderInfo, invitedUsers: IInvitedUsers[], session: RCCallSession) => {
},
/**
* 通话类型改变时触发,例如: 从视频变成音频通话, (必填)
* @param sender 发送者
* @param mediaType 1为音频通话 2为视频通话
* @param session 当前的 session 对象
*/
onMediaModify: (sender: ISenderInfo, mediaType: RCCallMediaType, session: RCCallSession) => {
},
/**
* 对方静音后触发 (必填)
* @param muteUser 已静音的用户
* @param session 当前的 session 对象
*/
onAudioMuteChange: (muteUser: IMuteUser, session: RCCallSession) => {
},
/**
* 对方禁用视频后触发 (必填)
* @param muteUser 已禁用视频的用户
* @param session 当前的 session 对象
*/
onVideoMuteChange: (muteUser: IMuteUser, session: RCCallSession) => {
},
},
});
if (code === RCCallErrorCode.SUCCESS) {
// do something
}
接到通话邀请时注册
触发来电监听后,从 onSession
的参数可以取到来电通话的 session
实例,需要注册通话过程中的事件监听。
API 参考:registerSessionListener
参数说明:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
onRinging | function | 是 | 当远端用户已开始响铃, 该函数有 2 个参数: sender 是发送者,session 是通话实例。这时用户可以在业务层做响铃的 UI 展示。 |
onAccept | function | 是 | 当远端用户已同意接听, 该函数有 2 个参数: sender 是发送者,session 是通话实例。这时用户可以把 UI 的‘响铃’变成‘通话中’。 |
onHungup | function | 是 | 当有远端用户挂断, 该函数有 3 个参数: sender 是发送者,reason 是挂断原因,session 是通话实例。这时用户可以在 UI 层提示‘xxx已挂断’。 |
onTrackReady | function | 是 | 当本端资源或远端资源已获取, 该函数有 2 个参数:track 是本端资源或远端资源, session 是通话实例。这时用户可以用拿到的 track 播放音频、视频。 |
onMemberModify | function | 是 | 群组通话中有其他人被邀请加入, 该函数有 3 个参数: sender 是发送者,invitedUsers 是被邀请的用户列表, session 是通话实例。这时用户可以在 UI 层提示‘xxx加入通话’。 |
onMediaModify | function | 是 | 通话类型改变时触发, 该函数有3个参数: sender 是发送者,mediaType 通话类型, session 是通话实例。这时用户可以在 UI 层提示‘已降级成音频通话’。 |
onAudioMuteChange | function | 是 | 对方静音后触发, 该函数有2个参数: muteUser 是已静音的用户, session 是通话实例。这时用户可以在 UI 层提示‘xxx已静音’。 |
onVideoMuteChange | function | 是 | 对方禁用视频后触发, 该函数有2个参数: muteUser 是已禁用视频的用户, session 是通话实例。这时用户可以在 UI 层提示‘xxx已禁用视频’。 |
以下是事件监听函数的参数说明:
-
sender
参数说明:参数 类型 必填 说明 sender.userId string 是 发送者 userId sender.name string 否 用户名 sender.portraitUri string 否 用户头像地址 sender.extra string 否 用户信息中的附加信息 -
invitedUsers
参数类型为Array<IInvitedUsers>
。IInvitedUsers
的参数说明同sender
。 -
muteUser
参数说明:参数 类型 必填 说明 muteUser.userId string 是 发送者 userId muteUser.muted boolean 是 资是否禁用 muteUser.kind string 否 被禁用的资源类型 muteUser.trackId string 否 被禁用的资源ID -
reason
参数详见挂断通话的原因
示例代码:
/**
* 在 session 实例上注册事件监听
*/
session.registerSessionListener({
/**
* 当远端用户已开始响铃
* @param sender 已响铃的用户
* @param session 当前的 session 对象
*/
onRinging: (sender: ISenderInfo, session: RCCallSession) => {
const { userId } = sender;
},
/**
* 当远端用户已同意 接听
* @param sender 远端用户
* @param session 当前的 session 对象
*/
onAccept: (sender: ISenderInfo, session: RCCallSession) => {
const { userId } = sender;
},
/**
* 当有远端用户挂断
* @param sender 远端用户
* @param reason 挂断的原因
* @param session 当前的 session 对象
*/
onHungup: (sender: ISenderInfo, reason: RCCallEndReason, session: RCCallSession) => {
const { userId } = sender;
},
/**
* 本端资源或远端资源已获取,track为本地音频或音视频, track不可设置成 Vue 组件的响应式数 据
* @param track 本端资源或远端资源
* @param session 当前的 session 对象
*/
onTrackReady: (track: RCTrack, session?: RCCallSession) => {
// track.isLocalTrack() 是否为本地资源
// track.isAudioTrack() 是否为音频
// track.isVideoTrack() 是否为视频
// track.getUserId() 产生该 track 的用户id
// 播放音频。如果为远端音频,建议直接播放。如为本端音频,建议不播放,以减少回音。
if (track.isAudioTrack() && !track.isLocalTrack()) {
track.play();
}
// 视频在对应的容器里播放
if (track.isVideoTrack()) {
const video = document.getElementById(
"video" + user.userId
) as HTMLVideoElement;
track.play(video);
}
},
/**
* 群组通话中有其他人被邀请加入
* @param sender 发送 者
* @param invitedUsers 被邀请的用户列表
* @param session 当前的 session 对象
*/
onMemberModify: (sender: ISenderInfo, invitedUsers: IInvitedUsers[], session: RCCallSession) => {
},
/**
* 通话类型改变时触发,例如: 从视频变成音频通话,
* @param sender 发送者
* @param mediaType 1为音频通话 2为视频通话
* @param session 当前的 session 对象
*/
onMediaModify: (sender: ISenderInfo, mediaType: RCCallMediaType, session: RCCallSession) => {
},
/**
* 对方静音后触发
* @param muteUser 已静音的用户
* @param session 当前的 session 对象
*/
onAudioMuteChange: (muteUser: IMuteUser, session: RCCallSession) => {
},
/**
* 对方禁用视频后触发
* @param muteUser 已禁用视频的用户
* @param session 当前的 session 对象
*/
onVideoMuteChange: (muteUser: IMuteUser, session: RCCallSession) => {
},
});
监听通话结束
需要在初始化 CallLib 客户端实例时,传入 onSessionClose
函数监听通话结束,从 onSessionClose
的参数里可以取到以下:
- 结束通话的 session 实例
- 通话结束后的汇总信息 (summaryInfo)
API 参考:install
summaryInfo
参数字段说明:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
conversationType | enum ConversationType { number } | 是 | 通话类型 1 单聊 3 群组 |
channelId | string | 是 | 组织 ID |
targetId | string | 是 | 目标 ID |
mediaType | enum RCCallMediaType { number } | 是 | 通话媒体类型。 1 为音频通话 2 为视频通话 |
beginTimestamp | number | 是 | 通话开始时间戳 |
beginTimestamp | number | 是 | 通话开始时间戳 |
endTimestamp | number | 是 | 通话结束时间戳 |
duration | number | 是 | 通话时长 单位:ms |
endReason | enum RCCallEndReason { number } | 是 | 通话结束原因 |
示例代码:
/**
* calllib 客户端初始化
*/
const caller: RCCallClient = RongIMLib.installPlugin(callInstaller, {
/**
* 监听通话结束
* 以下三条只要满足一条,就会触发onSessionClose
* 1、本端用户自己主动挂断
* 2、服务端把本端用户踢出 RTC 房间
* 3、房间里小于2个人
*
* @param {RCCallSession} session 被结束的 session 对象
* @param summaryInfo 结束一个 session 的后汇总信息
*/
onSessionClose: (session: RCCallSession, summaryInfo?: IEndSummary) => {
},
......
})