更新记录

3.2.0(2021-04-20)

  1. 新增多媒体资源下载接口(增值);
  2. 修复视频通话界面大小调整bug(增值);

3.1.1(2021-04-12)

  1. 修复和其他插件有相同依赖库情况下, 可能引起的打包冲突;
查看更多

平台兼容性

Android iOS
适用版本区间:4.4 - 11.0 适用版本区间:9 - 14

原生插件通用使用流程:

  1. 购买插件,选择该插件绑定的项目。
  2. 在HBuilderX里找到项目,在manifest的app原生插件配置中勾选模块,如需要填写参数则参考插件作者的文档添加。
  3. 根据插件作者的提供的文档开发代码,在代码中引用插件,调用插件功能。
  4. 打包自定义基座,选择插件,得到自定义基座,然后运行时选择自定义基座,进行log输出测试。
  5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项:使用HBuilderX2.7.14以下版本,如果同一插件且同一appid下购买并绑定了多个包名,提交云打包界面提示包名绑定不一致时,需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择


腾讯云IMPro

模块列表

IM即时通信

trtcCalling视频语音通话

trtcLiveRoom视频互动直播

trtcVoiceRoom语音聊天室

腾讯云IM

即时通信 IM 提供全球接入、单聊、群聊、好友管理、群组管理、资料关系链托管、帐号鉴权等全方位解决方案,并提供完备的 App 接入、后台管理接口,可以应用于社交沟通、互动直播、智能客服、物联网通信、企业通信、系统消息通知、游戏交流等场景

技术支持

IM产品接口众多,功能强大,接入复杂程度高,您可以先联系我们的技术支持。

我们的技术支持微信: ruanyunkeji001或ruanyunkeji002

接口列表

函数 功能
init 初始化
setSDKListener 设置SDK事件监听
login 登录
logout 退出登录
setSimpleMsgListener 设置简单消息的事件监听器
sendC2CTextMessage 发送单聊普通文本消息
sendC2CCustomMessage 发送单聊自定义(信令)消息
sendGroupTextMessage 发送群聊普通文本消息
sendGroupCustomMessage 发送群聊自定义(信令)消息
createImageMesssage 创建图片消息
sendMessage 发送消息,消息对象可以由 createXXXMessage 接口创建得来
revokeMessage 撤回消息,消息对象可以由 createXXXMessage 接口创建得来
getC2CHistoryMessageList 获取单聊(C2C)历史消息
getGroupHistoryMessageList 获取群组历史消息
markC2CMessageAsRead 设置单聊(C2C)消息已读
markGroupMessageAsRead 设置群组消息已读
deleteMessages 删除本地和云端消息
setGroupListener 设置群组监听器
createGroup 创建群组
joinGroup 加入群组
quitGroup 退出群组
dismissGroup 解散群组(仅群主和管理员可以解散)
getJoinedGroupList 获取已经加入的群列表
getGroupsInfo 拉取群资料
setGroupInfo 修改群资料
setReceiveMessageOpt 设置群消息接收选项
getGroupMemberList 获取群成员列表
getGroupMembersInfo 获取指定的群成员资料
setGroupMemberInfo 修改指定的群成员资料
muteGroupMember 禁言
inviteUserToGroup 邀请他人入群
kickGroupMember 踢人
setGroupMemberRole 切换群成员的角色
transferGroupOwner 转让群主
getGroupApplicationList 获取加群的申请列表
acceptGroupApplication 同意某一条加群申请
refuseGroupApplication 拒绝某一条加群申请
setConversationListener 设置会话监听器
getConversationList 获取会话列表
deleteConversation 删除会话
setConversationDraft 设置会话草稿
getUsersInfo 获取用户资料
setSelfInfo 修改个人资料
addToBlackList 屏蔽某人的消息(添加该用户到黑名单中)
deleteFromBlackList 取消某人的消息屏蔽(把该用户从黑名单中移除)
getBlackList 获取黑名单列表
setFriendListener 设置关系链与好友资料监听器
getFriendList 获取好友列表
getFriendsInfo 获取指定好友资料
setFriendInfo 设置指定好友资料
addFriend 添加好友
deleteFromFriendList 删除好友
getFriendApplicationList 获取好友申请列表
acceptFriendApplication 同意好友申请
refuseFriendApplication 拒绝好友申请
deleteFriendApplication 删除好友申请
createFriendGroup 新建好友分组
deleteFriendGroup 删除好友分组
getFriendGroupList 获取好友分组
renameFriendGroup 修改好友分组的名称
addFriendsToFriendGroup 添加好友到一个好友分组
deleteFriendsFromFriendGroup 从好友分组中删除好友

快速开始

腾讯云配置

这个步骤比较繁琐,可以联系我们上文中的客服进行指引

注册或登录腾讯云账号,并开通IM服务

联系我们上方技术客服进行测试体验。

加载模块

module的模块需要加载才能使用:

var Im = uni.requireNativePlugin("RY-TencentIMPro");

可以在下方代码里配置IM需要使用的变量,供后面函数调用使用:

data() {
    return {
        sdkAppId: 140xxxx797,
    }
}

初始化与监听

调用init接口即可完成初始化

init({params}, ret) 初始化

params:

参数 含义
sdkAppId 应用 Id
Im.init({
    sdkAppID: 140xxxx97,
    docPath: plus.io.convertLocalFileSystemURL('_doc')
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

setSDKListener({}, ret) 设置SDK监听回调

ret:

回调 含义
onUserSigExpired 在线时票据过期
onKickedOffline 当前用户被踢下线
Im.setSDKListener({}, (ret) => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

登录与登出

登录

只有在IM登录成功后,才能使用 IM SDK 的各项能力。

登录时机

以下场景需调用登录:

  • App 启动后首次使用 IM SDK 的能力时。
  • setSDKListener#onUserSigExpired 回调时,即登录票据已过期时,需要使用新的 UserSig 进行登录。
  • setSDKListener#onKickOffline 回调时,即当前用户被踢下线时,可以通过 UI 提示用户“您已经在其他端登录了当前账号,是否重新登录?” 如果用户选择“是”,就可以进行重新登录。

以下场景无需调用登录:

  • 用户的网络断开并重新连接后,不需要调用 login 函数,IM会自动上线。
  • 当一个登录过程在进行时,不需要进行重复登录。

多端登录

同样类型的两台手机不能同时登录一个帐号,例如两台苹果手机不能同时登录一个帐号。但是一台安卓手机和一台苹果手机会被认为是两端,可以同时登录。

login({params}, ret) 登录

params:

字段 含义
userId 用户Id
userSig 用户签名
var self = this;
Im.login({
    userId: self.userId,
    userSig: self.userSig
}, (ret) => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
})

logout({}, ret) 登出

Im.logout({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

消息收发

消息分类

腾讯云 IM 消息按照消息的发送目标可以分为:“单聊消息”(又称 “C2C 消息”)和“群聊消息” 两种

消息分类 API关键词 详细解释
单聊消息 C2CMessage 又称 C2C 消息,在发送时需要指定消息接收者的 UserID,只有接受者可以收到该消息。
群聊消息 GroupMessage 在发送时需要指定目标群组的 groupID,该群中的所有用户均能收到消息。

按照消息承载的内容可以分为:“文本消息”、“自定义(信令)消息”,“图片消息”、“视频消息”、“语音消息”、“文件消息”、“位置消息”、“群 Tips 消息”等几种类型。

消息分类 API关键词 详细解释
文本消息 TextElem 即普通的文字消息,该类消息会经过腾讯云 IM 的敏感词过滤。
自定义消息 CustomElem 即一段二进制 buffer,通常用于传输您应用中的自定义信令,内容不会经过敏感词过滤。
图片消息 ImageElem SDK 会在发送原始图片的同时,自动生成两种不同尺寸的缩略图,三张图分别被称为原图、大图、微缩图。
视频消息 VideoElem 一条视频消息包含一个视频文件和一张配套的缩略图。
语音消息 SoundElem 支持语音是否播放红点展示。
文件消息 FileElem 文件消息最大支持100MB
位置消息 LocationElem 地理位置消息由位置描述、经度(longitude )和维度(latitude)三个字段组成。
群 Tips 消息 GroupTipsElem 群 Tips 消息常被用于承载群中的系统性通知消息,例如有成员进出群组,群的描述信息被修改,群成员的资料发生变化等。
收发简单消息

提供了一组简单的消息收发接口,虽只能用于文本消息和自定义(信令)消息的收发,但使用方法特别简单,只需要几分钟即可完成对接。

发送文本和信令消息(简化接口)

调用 sendC2CTextMessage或者sendGroupTextMessage可以发送文本消息,其中文本消息会经过即时通信 IM 的敏感词过滤,包含的敏感词消息在发送时会报80001错误码。

sendC2CCustomMessage({params}, ret) 发送单聊(C2C)自定义(信令)消息

params:

参数 含义
userId 用户Id
customMsg 信令消息
var self = this;
Im.sendC2CCustomMessage({
    customMsg: self.customMsg,
    userID: self.remoteUserId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

调用 sendC2CCustomMessage 或者 sendGroupCustomMessage 可以发送 C2C 自定义(信令)消息,自定义消息本质是一段二进制 buffer,通常用于传输您应用中的自定义信令,内容不会经过敏感词过滤。

sendGroupTextMessage 发送群聊普通文本消息

params:

字段 含义
text 文本消息
userId 用户Id
var self = this;
Im.sendGroupTextMessage({
    text: self.textMsg,
    groupID: self.groupId,
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

sendGroupCustomMessage 发送群聊自定义(信令)消息

params:

参数 含义
userId 用户Id
customMsg 信令消息
var self = this;
Im.sendGroupCustomMessage({
    customMsg: self.customMsg,
    groupID: self.groupId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
接收文本和信令消息(简化接口)

通过setSimpleMsgListener 可以监听简单的文本和信令消息,复杂的图片、视频、语音消息则需要通过中定义的setAdvancedMsgListener实现。

setSimpleMsgListener({}, ret) 设置基本消息(文本消息和自定义消息)的事件监听器

ret:

回调事件 含义
onRecvGroupTextMessage 收到C2C文本消息
onRecvC2CCustomMessage 收到C2C自定义(信令)消息
onRecvGroupTextMessage 收到群文本消息
onRecvGroupCustomMessage 收到群自定义(信令)消息

sendC2CTextMessage({params}, ret) 发送单聊(C2C)普通文本消息

params:

字段 含义
text 文本消息
userId 用户Id
var self = this;
Im.sendC2CTextMessage({
    text: self.textMsg,
    userId: self.remoteUserId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
收发富媒体消息

图片、视频、语音、文件、地理位置等类型的消息称为“富媒体消息”。相比于简单消息,富媒体消息的收发相对复杂:

  • 在发送时,富媒体消息需要先用对应的 create 函数创建一个消息对象,再调用对应的 send 接口发送。
  • 在接收时,富媒体消息需要先判断字段 elemType,elemType代表对应的消息类型。

createImageMesssage({params}, ret) 创建图片消息

params:

字段 含义
img 图片路径
var self = this;
Im.createImageMessage({
    img: self.imagePath
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

sendMessage({params}, ret) 发送消息

params:

字段 含义
receiver 用户Id
groupId 群组Id
priority 优先级
messageKey 消息键, 由创建消息返回
self = this;
Im.sendMessage({
    receiver: self.remoteUserId,
    priority: self.priority,
    messageKey: self.messageKey
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
发送富媒体消息

本文以图片消息为例,介绍发送一条富媒体消息的过程:

  1. 发送方调用 createImageMessage 创建一条图片消息。
  2. 发送方调用 sendMessage 接口将刚才创建的消息对象发送出去。
接收富媒体消息
  1. 接收方调用setAdvancedMsgListener接口设置高级消息监听。
  2. 接收方通过监听回调setAdvanceMsgListener#onRecvNewMessage 获取图片消息。
  3. 接收方解析消息中的 elemType 属性,获取消息内部 Elem 中的具体内容。
经典示例:收发图片

发送方创建一条图片消息并发送:

var self = this;
// 选择图片
uni.chooseImage({
    success: (res) => {
        var imgPath = res.tempFilePaths[0];
        self.imagePath = plus.io.convertLocalFileSystemURL(imgPath);
    }
});
// 创建图片消息
Im.createImageMessage({
    img: self.imagePath
}, ret => {
    if (ret.hasOwnProperty('status')) {
        self.messageKey = ret.messageKey;
    }
});
// 发送图片消息
Im.sendMessage({
    receiver: self.remoteUserId,
    priority: self.priority,
    messageKey: self.messageKey
}, ret => {
});

接收方识别一条图片消息并将解析中包含的原图、大图和微缩图:

if (ret.eventType == 'onRecvNewMessage') {
    ...
    var imageList = elem.imageList;
    ...
}
收发群 @ 消息

群 @ 消息,发送方可以在输入栏监听 @ 字符输入,调用到群成员选择界面,选择完成后以 “@A @B @C......” 形式显示在输入框,并可以继续编辑消息内容,完成消息发送;接收方会在会话界面的群聊天列表,重点显示 “有人@我” 或者“@所有人” 标识,提醒用户有人在群里 @ 自己了。

说明: 目前仅支持文本 @ 消息。

发送群 @ 消息
  1. 发送方监听聊天界面的文本输入框,启动群成员选择界面,选择完成后回传选择群成员的Id和昵称信息,Id用来构建消息对象,昵称用来在文本框显示。
  2. 发送方调用createTextAtMessage 创建一条 @ 文本消息。
  3. 发送方调用 sendMessage 接口将刚才创建的 @ 消息对象发送出去。

createTextAtMessage({params}, ret) 创建@文本消息

params:

字段 含义
text 文本消息
userIdList 用户Id列表
var self = this;
Im.createTextAtMessage({
    text: self.textMsg,
    userIdList: self.userIdList
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
接收群 @ 消息
  1. 在加载和更新会话处,需要调用 setConversationListener 的 groupAtInfolist 接口获取会话的 @ 数据列表 。
  2. 通过列表中 groupAtInfo 对象的 atType 接口获取 @ 数据类型,并更新到当前会话的 @ 信息。
经典示例:收发群 @ 消息
  • 发送群 @ 消息: 发送方创建一条群 @ 消息并发送。
// 创建@消息
Im.createTextAtMessage({
    text: self.textMsg,
    userIdList: self.userIdList
}, ret => {
    if (ret.hasOwnProperty('status')) {
        self.messageKey = ret.messageKey;
    }
});
// 发送@消息
Im.sendMessage({
    receiver: self.remoteUserId,
    priority: self.priority,
    messageKey: self.messageKey
}, ret => {
});
  • 接收群 @ 消息: 在加载和更新会话处,返回结果里conversation获取群 @ 数据列表,解析当前的 @ 类型,根据 @ 类型显示对应的提示文本。
var atMe = false;
var atAll = false;
switch (atGroupInfo.atType) {
    case 1:
        atMe = true;
    break;
    case 2:
        atAll = true;
    break;
    case 3:
        atMe = true;
        atAll = true;
    break;
}
设置消息为只能在线接收(onlineUserOnly)

某些场景下,您可能希望发出去的消息只被在线用户接收,即当接收者不在线时就不会感知到该消息。您只需在 sendMessage 时,将参数 onlineUserOnly 设置为 true ,此时发送出去的消息与普通消息相比,会有如下差异点:

  • 不支持离线存储,即如果接收方不在线就无法收到。
  • 不支持多端漫游,即如果接收方在一台终端设备上一旦接收过该消息,无论是否已读,都不会在另一台终端上再次收到。
  • 不支持本地存储,即本地的云端的历史消息中均无法找回。
经典示例:实现“对方正在输入”功能

在 C2C 单聊场景下,您可以通过 sendMessage 接口发送 "自己正在输入" 的提示性消息,接收方收到该消息时可以在 UI 界面展示 "对方正在输入"

撤回消息

发送方通过 revokeMessage 接口可以撤回一条已经发送成功的消息。默认情况下,发送者只能撤回2分钟以内的消息,您可以按需更改消息撤回时间限制,具体操作请参见 消息撤回设置。 消息的撤回同时需要接收方 UI 代码的配合:当发送方撤回一条消息后,接收方会收到消息撤回通知 setAdvancedMsgListener#onRecvMessageRevoked,通知中包含被撤回消息的 msgId,您可以根据 msgId 判断 UI 层是哪一条消息被撤回了,然后把对应的消息气泡切换成 "消息已被撤回" 状态。

发送方撤回一条消息

revokeMessage({params}, ret) 撤回消息

params:

参数 含义
msgId 消息Id
self = this;
Im.revokeMessage({
    msgId: self.msgId,
    userId: self.remoteUserId,
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
接收方感知消息被撤回
  • 调用 setAdvancedMsgListener 设置高级消息监听。
  • 通过 setAdvancedMsgListener#onRecvMessageRevoked 接收消息撤回通知。
给消息增加已读回执

在 C2C 单聊场景下,当接收方通过 markC2CMessageAsRead 接口将来自某人的消息标记为已读时,消息的发送方将会收到“已读回执”,表示“xxx 已经读过我的消息了”。

注意: 目前仅 C2C 单聊消息支持已读回执,群聊场景暂不支持。虽然群聊消息也有对应的 markGroupMessageAsRead 接口,但群消息的发送者目前无法收到已读回执。

接收方标记消息已读

markC2CMessageAsRead({params}, ret) 设置单聊消息已读

params:

参数 含义
userId 用户Id
var self = this;
Im.markC2CMessageAsRead({
    userId: self.remoteUserId,
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

markGroupMessageAsRead({params}, ret) 设置群组消息已读

params:

参数 含义
groupId 群组Id
var self = this;
Im.markGroupMessageAsRead({
    groupId: self.groupId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
发送方感知消息已读

消息已读回执的事件通知位于高级消息监听器 setAdvancedMsgListener 中,如需支持感知消息已读,需要先通过 setAdvancedMsgListener 设置监听器,然后通过 setAdvancedMsgListener#onRecvC2CReadReceipt 回调即可感知接收方的已读确认。

查看历史消息

您可以调用 getC2CHistoryMessageList 获取单聊历史消息,调用 getGroupHistoryMessageList 获取群聊历史消息。如果当前设备网络连接正常,SDK 会默认从服务器拉取历史消息;如果没有网络连接,SDK 会直接从本地数据库中读取历史消息。

getC2CHistoryMessageList({params}, ret) 获取单聊历史消息

params:

参数 含义
userId 用户Id
count 拉取消息的个数
msgId 起始消息Id
Im.getC2CHistoryMessageList({
    userId: self.remoteUserId,
    count: self.count,
    msgId: self.msgId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

getGroupHistoryMessageList({params}, ret) 获取群组历史消息

params:

参数 含义
groupId 群组Id
count 拉取消息的个数
msgId 起始消息Id
var self = this;
Im.getGroupHistoryMessageList({
    groupId: self.groupId,
    count: self.count,
    msgId: self.msgId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
分页拉取历史消息

SDK 支持分页拉取历史消息,一次分页拉取的消息数量不宜太大,否则会影响拉取速度,建议一次最多拉取20条。 本文以分页拉取名为 groupA 的群的历史消息,每次分页拉取20条为例,示例代码如下:

self = this;
Im.getC2CHistoryMessageList({
    userId: self.remoteUserId,
    count: self.count,
    msgId: self.msgId
}, ret => {
    if (ret.hasOwnProperty('status')) {
        var messageList = ret.messageList;
        if (messageList.length < self.count) {
            return;
        }
        self.msgId = messageList[messageList.length - 1].msgId;
    }

现实场景中的分页拉取,通常由用户的滑动操作触发的,用户每下拉一次消息列表就触发一次分页拉取。但原理上跟上述示例代码类似,都是以 msgId 作为分页的标记,以 count 控制每次拉取的消息条数。

历史消息的注意事项
  • 历史消息存储时长如下: 体验版:免费存储7天,不支持延长 专业版:免费存储7天,支持延长 旗舰版:免费存储30天,支持延长 延长历史消息存储时长是增值服务,您可以登录 即时通信 IM 控制台 修改相关配置。
  • 只有会议群(Meeting)(对应老版本的 ChatRoom 群)才支持拉取到用户入群之前的历史消息。
  • 直播群(AVChatRoom)中的消息均不支持本地存储和多终端漫游,因此对直播群调用 getGroupHistoryMessageList 接口是无效的。
删除消息

对于历史消息,您可以调用 deleteMessages 接口删除历史消息,消息删除后,无法再恢复。

deleteMessages({params}, ret) 删除本地及云端的消息

params:

参数 含义
msgIdList 消息Id列表
var self = this;
Im.deleteMessages({
    msgIdList: self.msgIdList
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
设置消息权限
只允许好友间收发消息

SDK 默认不限制非好友之间收发消息。如果您希望仅允许好友之间发送单聊消息,您可以在 即时通信 IM 控制台 >【功能配置】>【登录与消息】>【好友关系检查】中开启"发送单聊消息检查关系链"。开启后,用户只能给好友发送消息,当用户给非好友发消息时,SDK 会报20009错误码。

屏蔽某人的消息

如果您想屏蔽某人的消息,请调用 addToBlackList 接口把该用户加入黑名单,即拉黑该用户。 当消息发送者被拉黑后,发送者默认不会感知到“被拉黑”的状态,即发送消息后仍展示发送成功(实际上此时接收方不会收到消息)。如果需要被拉黑的发送者收到消息发送失败的提示,请在 即时通信 IM 控制台 >【功能配置】>【登录与消息】>【黑名单检查】中关闭"发送消息后展示发送成功",关闭后,被拉黑的发送者在发送消息时,SDK 会报20007错误码。

屏蔽某个群组的消息

如果您想屏蔽某个群组的消息,请调用 setReceiveMessageOpt 接口,设置群消息接收选项为 2 状态。

敏感词过滤

SDK 发送的文本消息默认会经过即时通信 IM 的敏感词过滤,如果发送者在发送的文本消息中包含敏感词,SDK 会报 80001 错误码。

敏感词

会话管理

展示会话列表

用户在登录 App 后,可以像微信那样展示最近会话列表。整个过程分为拉取会话列表、处理更新通知和更新 UI 内容(包括未读计数),本文主要介绍这些步骤的详细细节。

![会话列表](https://imsdk-1252463788.cos.ap-guangzhou.myqcloud.com/res/RPReplay_Final0511.gif =300x500)

拉取会话列表

用户在登录后调用 getConversationList 拉取本地会话列表做 UI 展示,会话列表是一个 conversation 对象的列表,每一个对象都代表一个会话。

getConversationList({params}, re) 获取会话列表

params:

参数 含义
nextSeq 分页拉取的游标
count 分页拉取的个数
var self = this;
Im.getConversationList({
    nextSeq: 0,
    count: 10
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

由于本地会话可能较多(例如超过500个),一次性全部加载完毕可能会耗时很久,导致界面展示比较慢。为了提升用户体验,getConversationList 接口支持分页拉取能力:

  1. 首次调用 getConversationList 接口时,可以指定其参数 nextSeq 为0 ,表示从头开始拉取会话列表,并指定 count 为50,表示一次拉取50个会话对象。
  2. 按照从新到旧的顺序拉取会话列表,当首次拉取会话列表成功后,getConversationList 的回调结果中会包含下次分页拉取的 nextSeq 字段以及会话拉取是否完成的 isFinish 字段: 如果 isFinished 返回 true,表示所有会话已经拉取完成。 如果 isFinished 返回 false ,表示还有更多的会话可以拉取。此时并不意味着要立刻开始拉取“下一页”的会话列表。在常见的通信软件中,分页拉取通常由用户的滑动操作触发的,用户每下拉一次会话列表就触发一次分页拉取。
  3. 当用户继续下拉会话列表时,如果还有更多的会话可以拉取,可以继续调用 getConversationList 接口,并传入新一轮的 nextSeq 和 count 参数(数值来自上一次拉取返回的 ret 对象)。
  4. 重复执行 步骤3 直至 isFinished 返回 true。
显示会话列表
获取到 conversation 对象后,即可在 UI 上展示,conversation 有如下关键字段常被用于构造会话列表: 字段名称 含义
showName 会话名称
faceUrl 会话头像
recvOpt 会话接收选项
unreadCount 用于显示未读计数,表示有多少条未读消息
lastMessage 最后一条消息,用于显示会话的消息摘要
更新会话列表

IM SDK 会在登录成功后、用户上线后、以及断线重连后,自动更新会话列表。更新过程如下:

  • 当有会话更新时,例如新收到一条消息,会通过 setConversationListener 中的 onConversationChanged 事件通知您。
  • 当有会话新增时,会通过 setConversationListener 中的 onNewConversation 事件通知您。

setConversationListener({}, ret) 设置会话监听

Im.setConversationListener({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

!!注意: 为保证会话列表顺序符合最后一条消息的排序原则,您需要根据 lastMessage 中的 timestamp 对数据源重新排序。

删除会话

调用 deleteConversation 接口可以删除某个会话,会话删除不支持多端同步,删除会话时默认删除本地和服务器历史消息,且无法恢复。

deleteConversation({params}, ret) 删除会话

params:

参数 含义
conversationId 会话Id
var self = this;
Im.deleteConversation({
    conversationId: self.conversationId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
草稿箱

在发送消息时,可能会遇到消息尚未编辑完就要切换至其它聊天窗口的情况,这些未编辑完的消息可通过 setConversationDraft 接口保存,以便于回到聊天界面后调用 draftText 继续编辑内容

setConversationDraft({params}, ret) 设置会话草稿

params:

参数 含义
conversationId 会话Id
draftText 草稿内容
var self = this;
Im.setConversationDraft({
    conversationId: self.conversationId,
    draftText: self.draftText
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

!!注意: 草稿仅支持文本内容。 草稿仅在本地保存,不会存储到服务器,因此不能多端同步,程序卸载重装会失效。

群组管理

群类型介绍

即时通信 IM 群组分为以下类型:

  • 好友工作群(Work): 类似普通微信群,创建后仅支持已在群内的好友邀请加群,且无需被邀请方同意或群主审批。
  • 陌生人社交群(Public): 类似 QQ 群,创建后群主可以指定群管理员,用户搜索群 ID 发起加群申请后,需要群主或管理员审批通过才能入群。
  • 临时会议群(Meeting): 创建后可以随意进出,且支持查看入群前消息;适合用于音视频会议场景、在线教育场景等与实时音视频产品结合的场景。
  • 直播群(AVChatRoom): 创建后可以随意进出,没有群成员数量上限,但不支持历史消息存储;适合与直播产品结合,用于弹幕聊天场景。

每种群类型的功能特性及限制如下表所示:

群组管理
创建群组

#######简化版接口

调用 createGroup 接口,并指定需要的 groupType、groupID 和 groupName 参数,即可简单创建一个群组。

createGroup({params}, ret) 创建群组

params:

参数 含义
groupType 群类型: Work、Public、Meeting或AVChatRoom
groupId 自定义群组Id
groupName 群名称
var self = this;
Im.createGroup({
    groupType: self.groupType,
    groupId: self.groupId,
    groupName: self.groupName
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

#######高级版接口

如果您想在创建群组的同时初始化群的信息,例如群简介、群头像、以及最初的几个群成员等,可以调用createGroupWithMemberList接口实现。

createGroupWithMemberList({params}, ret) 创建自定义群组(高级版本: 可以指定初始的群成员)

params:

参数 含义
groupInfo 自定义群组信息
memberList 指定初始的群成员

groupInfo:

参数 含义
groupId 群组Id
groupType 群组类型
groupName 群名称
notification 群公告
introduction 群简介
faceUrl 群头像
isAllMuted 是否全员禁言
groupAddOpt 加群是否需要管理员审批

memberList成员:

参数 含义
userId 被操作成员
role 群成员类型
var self = this;
Im.createGroupWithMemberList({
    groupInfo: {
        groupId: self.groupId, 
        groupType: self.groupType,
        groupName: self.groupName,
        notification: self.notification
    },
    memberList: [
        {
            userId: self.remoteUserId,
            role: 0
        }
    ],
    introduction: self.introduction,
        faceUrl: self.faceUrl
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
加入群组
不同类型的群,加群的方法不同, 下面根据加群流程从简单到复杂进行逐一介绍: 类型 好友工作群(Work) 陌生人社交(Public) 临时会议(Meeting) 直播群(AVChatroom)
加群方法 必须由其他群成员邀请 用户申请,群主或管理员审批 用户可随意加入 用户可随意加入

场景一: 用户可以自由进出群

临时会议群(Meeting)和直播群(AVChatRoom)主要用于满足成员进进出出的交互场景,例如在线会议,秀场直播等。因此,这两种类型群的入群流程最为简单。

场景二: 需被邀请才能进入群

好友工作群(Work)类似微信群和企业微信群,适用于工作交流,在交互设计上限制用户主动加入,只能由现有的群成员邀请才能加群。

现有的群成员调用inviteUserToGroup邀请另一个用户入群,全体群成员(包括邀请者自己)会收到setGroupListener#onMemberInvited 回调。

inviteUserToGroup({params}, ret) 邀请他人入群

params:

参数 含义
groupId 群组Id
userList 用户Id列表
var self = this;
Im.inviteUserToGroup({
    groupId: self.groupId,
    userIdList: [
        self.remoteUserId,
    ]
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

场景三:需要审批才能进入群

陌生人社交群(Public)类似 QQ 中的各种兴趣群和部落区,任何人都可以申请入群,但需要经过群主或管理员审批才能真正入群。陌生人社交群默认需要群主或管理员进行审批才能加群的,但群主或管理员也可以通过 setGroupInfo 接口调整加群选项(groupAddOpt),可以设置为更严格的“禁止任何人加群”,也可以设置为更宽松的“放开审批流程”。

  • 0: 禁止任何人加群。
  • 1: 需要群主或管理员审批才能加入(默认值)。
  • 2: 取消审批流程,任何用户都可以加入。

需要审批才能进入群的流程如下:

审批流程

  1. 申请者提出加群申请

申请者调用 joinGroup申请加群。

joinGroup({params}, ret) 加入群组

参数 含义
groupId 群组Id
msg 加群申请信息
var self = this;
Im.joinGroup({
    groupId: self.groupId,
    msg: self.joinGroupMsg
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
  1. 群主或管理员处理加群申请

群主或管理员在收到加群申请的回调setGroupListener#onReceiveJoinApplication 后调用接口 getGroupApplicationList 获取加群申请列表,然后通过 acceptGroupApplication或者refuseGroupApplication来同意或者拒绝某一条加群请求。

getGroupApplicationList({}, ret) 获取加群的申请列表

Im.getGroupApplicationList({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

acceptGroupApplication({params}, ret) 同意某一条加群申请

params:

参数 含义
index 申请索引位置
reason 申请说明
var self = this;
Im.acceptGroupApplication({
    index: self.index,
    reason: self.reason
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

refuseGroupApplication({params}, ret) 拒绝某一条加群申请

params:

参数 含义
index 申请索引位置
reason 申请说明
var self = this;
Im.refuseGroupApplication({
    index: self.index,
    reason: self.reason
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
  1. 申请者收到处理结果
退出群组

调用 quitGroup 可以退出群组,退群者会收到 setGroupListener#onQuitFromGroup 回调,群其他成员会收到 setGroupListener#onMemberLeave 回调。

quitGroup({params}, ret) 退出群组

params:

参数 含义
groupId 群组Id
var self = this;
Im.quitGroup({
    groupId: self.groupId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

注意: 对于陌生人社交群(Public)、临时会议群(Meeting)和直播群(AVChatRoom),群主不可以退群的,群主只能 解散群组。

解散群组

调用 dismissGroup 可以解散群组,全员会收到 setGroupListener#onGroupDismissed 回调。

dismissGroup({params}, ret) 解散群组

参数 含义
groupId 群组Id
var self = this;
Im.dismissGroup({
    groupId: self.groupId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

注意: 对于陌生人社交群(Public)、临时会议群(Meeting)和直播群(AVChatRoom),群主随时可以解散群。 工作群(Work)的解散最为严格,即使群主也不能随意解散,只能由您的业务服务器调用 解散群组 REST API 解散。

获取已加入的群组

调用 getJoinedGroupList 可以获取已加入的好友工作群(Work)、陌生人社交群(Public)、临时会议群(Meeting)列表,但直播群(AVChatRoom)不包含在此列表中。

getJoinedGroupList({}, ret) 获取当前用户已经加入的群列表

Im.getJoinedGroupList({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
群资料和群设置
获取群资料

调用 getGroupsInfo 可以获取群资料,该接口支持批量获取。您可以一次传入多个 groupId 获取多个群的群资料。

getGroupsInfo({params}, ret) 拉取群资料

params:

参数 含义
groupIdList 群组Id列表
var self = this;
Im.getGroupsInfo({
    groupIdList: [
        self.groupId
    ]
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
修改群资料

调用 setGroupInfo 可以修改群资料。群资料被修改后,全员会收到 onGroupInfoChanged 回调。

setGroupInfo({params}, ret) 修改群资料

参数 含义
groupId 群组Id
groupName 群名称
groupType 群类型
notification 群公告
introduction 群简介
faceUrl 群头像
isAllMute 是否全员禁言
groupAddOpt 群是否需要管理员审批
var self = this;
Im.setGroupInfo({
    groupId: self.groupId,
    groupName: self.groupName,
    faceUrl: self.faceUrl,
    groupAddOpt: self.groupAddOpt
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
        });
});

!!注意:

  • 好友工作群(Work)所有群成员都可以修改群基础资料。
  • 陌生人社交群(Public)、临时会议群(Meeting)只有群主或管理员可以修改群基础资料。
  • 直播群(AVChatRoom)只有群主可以修改群基础资料。
设置群消息的接收选项

任何群成员都可以调用 setReceiveMessageOpt 接口修改群消息接收选项。群消息接收选项包括:

  • 0:在线正常接收消息,离线时会有厂商的离线推送通知。
  • 1:不会接收到群消息。
  • 2:在线正常接收消息,离线不会有推送通知。

setReceiveMessageOpt({params}, ret) 修改群消息接收选项

params:

参数 含义
groupId 群组Id
opt 接收选项
var self = this;
Im.setReceiveMessageOpt({
    groupId: self.groupId,
    opt: self.groupRecvOpt
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

根据群消息接收选择可以实现群消息免打扰:

  • 完全不接收群内消息 群消息接收选项设置为 2 后,群内的任何消息都收不到,会话列表也不会更新。

  • 接收群内消息但不提醒,在会话列表界面显示小圆点,而不显示未读数

??说明: 此方式需使用未读计数功能,因此仅适用于好友工作群(Work)和陌生人社交群(Public)。

群消息接收选项设置为 1,当群内收到新消息,会话列表需要更新时,可以通过会话中的 getUnreadCount 获取到消息未读数。根据 getRecvOpt 判断获取到的群消息接收选项为 2 时显示小红点而非消息未读数。

群属性(群自定义字段)

设计了全新的群自定义字段,我们称之为 "群属性",其特性如下:

  1. 不再需要控制台配置,客户端可以直接增删改查群属性。
  2. 最多支持16个群属性,每个群属性的大小最大支持4k,所有群属性的大小最大支持16k。
  3. 目前仅支持直播群(AVChatRoom)。
  4. initGroupAttributes、setGroupAttributes、deleteGroupAttributes 接口合并计算, SDK 限制为5秒10次,超过后回调8511错误码;后台限制1秒5次,超过后返回10049错误码。
  5. getGroupAttributes 接口 SDK 限制5秒20次。

基于群属性,我们可以做语聊房的麦位管理,当有人上麦的时候,可以设置一个群属性管理上麦人信息,当有人下麦的时候,可以删除对应群属性,其他成员可以通过获取群属性列表来展示麦位列表。

初始化群属性

调用 initGroupAttributes 接口可以初始化群属性,如果该群之前有群属性,会先清空原来的群属性。

initGroupAttributes({params}, ret) 初始化群属性

params:

参数 含义
groupId 群组Id
attributeList 属性和属性值对象
var self = this;
Im.initGroupAttributes({
    groupId: self.groupId, 
    attributeList: {}
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
设置群属性

调用 setGroupAttributes 接口可以设置群属性,如果设置的群属性不存在,会自动添加该群属性。

setGroupAttributes({params}, ret) 设置群属性

params:

参数 含义
groupId 群组Id
attributeList 属性和属性值对象
var self = this;
Im.setGroupAttributes({
    groupId: self.groupId,
    attributeList: self.attributeList
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
删除群属性

调用 deleteGroupAttributes 接口可以删除指定群属性,如果 keys 字段填 null ,则会清空所有的群属性。

deleteGroupAttributes({params}, ret) 删除指定群属性

params:

参数 含义
groupId 群组Id
keyList 键名列表
var self = this;
Im.deleteGroupAttributes({
    groupId: self.groupId, 
    keyList: self.keyList
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
获取群属性

调用 getGroupAttributes 接口可以获取指定群属性,如果 keys 字段填 null ,则会获取所有的群属性。

getGroupAttributes({params}, ret) 获取指定群属性

params:

参数 含义
groupId 群组Id
keyList 键名列表
var self = this;
Im.getGroupAttributes({
    groupId: self.groupId,
    keyList: self.keyList
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
群属性更新

群属性有任何的更新变化,都会通过 setGroupListener#onGroupAttributeChanged 回调出来所有的群属性字段。

群成员管理
获取群成员列表

调用 getGroupMemberList 可以获取某个群的群成员列表,该列表中包含了各个群成员的资料信息,例如用户ID(userID)、群名片(nameCard)、头像(faceUrl)、昵称(nickName)、进群时间(joinTime)等信息。 一个群中的成员人数可能很多(例如5000+),群成员列表的拉取接口支持过滤器(filter)和分页拉取(nextSeq)两个高级特性。

getGroupMemberList({params}, ret) 获取群成员列表

params:

参数 含义
groupId 群组Id
filter 指定群成员类型
nextSeq 分页拉取标志
var self = this;
Im.getGroupMemberList({
    groupId: self.groupId,
    filter: 0, 
    nextSeq: 0
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

#######过滤器

在调用 getGroupMemberList 接口时,您可以指定 filter 确定是否仅拉取特定角色的信息列表。

过滤器 过滤类型
0 拉取所有群成员的信息列表
1 仅拉取群主的信息列表
2 仅拉取群管理员的信息列表
3 仅拉取普通群成员的信息列表

#######分页拉取(nextSeq)

很多情况下,用户界面上并不需要展示全部的群成员信息,只需展示群成员列表的第一页即可,等用户单击“下一页”或在列表页下拉刷新时,才需要拉取更多的群成员。针对此类场景,您可以使用分页拉取。

在调用 getGroupMemberList 接口时,一次最多返回50个成员,您可以通过 nextSeq 参数分页拉取成员列表,nextSeq参数为分页拉取标志,第一次拉取时请填0。当首次拉取群成员信息成功后,getGroupMemberList 的回调结果 V2TIMGroupMemberInfoResult 中会包含 getNextSeq() 接口。

如果 getNextSeq() 返回0,表示已经拉取全部的群成员列表。 如果 getNextSeq() 返回 >0 的数值,表示还有更多的群成员信息可以拉取。您可以根据用户在 UI 上的操作,选择是否进行第二次接口调用以拉取更多的群成员信息。当您进行第二次拉取时,需要将上一次拉取返回的 nextSeq 作为参数,传入 getGroupMemberList 接口。

拉取群成员

调用 getGroupMembersInfo 可以获取群成员资料,该接口支持批量获取,您可以一次传入多个 userID 获取多个群成员的资料,从而提升网络传输效率。

getGroupMembersInfo({params}, ret) 获取指定的群成员资料

params:

参数 含义
groupId 群组Id
memberList 成员Id列表
var self = this;
Im.getGroupMembersInfo({
    groupId: self.groupId,
    memberList: [
        self.userId
    ]
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
修改群成员资料

群主或管理员可以调用 setGroupMemberInfo 接口修改群成员的群名片(nameCard)、 群成员角色(role)、禁言时间(muteUntil)以及自定义字段等与群成员相关的资料。 群主或管理员也可以通过 setGroupInfo 接口对整个群进行禁言,将 isAllMuted 属性字段设置为 true 即可。全群禁言没有时间限制,需通过将群资料 isAllMuted设置为false解除禁言。

setGroupMemberInfo({params}, ret) 修改指定的群成员资料

params:

参数 含义
groupId 群组Id
info 修改的群成员信息
var self = this;
Im.setGroupMemberInfo({
    groupId: self.groupId,
    info: {
        userId: self.userId,
        nameCard: self.nameCard
    }
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
踢人

群主或管理员调用 kickGroupMember 接口可以实现踢人。由于直播群(AVChatRoom)对进群没有限制,因此直播群(AVChatRoom)没有支持踢人的接口,您可以使用 muteGroupMember 达到同样的目的。 成员被踢后,全员(包括被踢人)会收到 setGroupListener#onMemberKicked 回调。

kickGroupMember({params}, ret) 踢人

params:

参数 含义
groupId 群组Id
memberList 要踢出的的Id列表
var self = this;
Im.kickGroupMember({
    groupId: self.groupId,
    memberList: [
        self.remoteUserId,
    ],
    reason: self.reason
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

muteGroupMember({params}, ret) 禁言

params:

参数 含义
groupId 群组Id
userId 用户Id
seconds 禁言的时间
var self = this;
Im.muteGroupMember({
    groupId: self.groupId,
    userId: self.remoteUserId,
    seconds: 50
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
切换群成员角色

群主调用 setGroupMemberRole 可以对陌生人社交群(Public)或临时会议群(Meeting)中的群成员进行角色切换,可切换角色包括普通成员、管理员。

  • 被设置为管理员后,全员(包括被设置的成员)会收到 setGroupListener#onGrantAdministrator 回调。
  • 被取消管理员后,全员(包括被设置的成员)会收到 setGroupListener#onRevokeAdministrator 回调。

setGroupMemberRole({params}, ret) 切换群成员的角色

params:

参数 含义
groupId 群组Id
userId 用户Id
role 群成员角色
var self = this;
Im.setGroupMemberRole({
    groupId: self.groupId,
    userId: self.remoteUserId,
    role: self.groupMemberRole
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
转让群主

群主可以调用 transferGroupOwner 把群主转让给其他群成员。 群主转让后,全员会收到 setGroupListener#onGroupInfoChanged 回调,其中 infoList中的 type 为4,value 值为新群主的 userId。

transferGroupOwner({params}, ret) 转让群主

params:

参数 含义
groupId 群组Id
userId 用户Id
var self = this;
Im.transferGroupOwner({
    groupId: self.groupId,
    userId: self.remoteUserId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

信令管理

概述

信令接口是基于 IM 消息提供的一套邀请流程控制的接口,可以实现多种实时场景,例如:

  • 直播聊天室中进行上麦、下麦管理。
  • 聊天场景中实现类似微信中的音视频通话功能。
  • 教育场景中老师邀请同学们举手、发言的流程控制。
功能

信令接口支持以下功能:

单聊邀请

在使用 简单收发消息接口 或 富媒体消息接口 进行单聊的同时,可以使用 [invite])(#invite) 信令接口进行点对点呼叫,对方收到邀请通知 onReceiveNewInvitation 后可以选择接受、拒绝或等待超时。

invite({params}, ret) 邀请某个人

params:

参数 含义
invitee 被邀请人用户Id
data 自定义数据
var self = this;
Im.invite({
    invitee: self.remoteUserId, 
    data: self.inviteData
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
群聊邀请

首先需通过 建群、加群、退群、解散群以及群资料 和 群成员 相关接口完成对群组的管理,并监听群内的相关事件回调 V2TIMGroupListener。然后群成员可以在群内发起群呼叫邀请 inviteInGroup,被邀请的群成员会收到邀请通知 onReceiveNewInvitation 后可以选择接受、拒绝或等待超时。

inviteInGroup({params}, ret) 邀请群内的某些人

params:

参数 含义
groupId 发起邀请所在群组
inviteeList 被邀请人列表
data 自定义数据
var self = this;
Im.inviteInGroup({
    groupId: self.groupId,
    inviteeList: self.inviteeList,
    data: self.inviteData
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
取消邀请

主叫可以在超时前且被叫未处理前取消邀请 cancel。被邀请者会收到取消通知 setSignalingListener#onInvitationCancelled,该邀请流程结束。

取消邀请

cancel({params}, ret) 邀请方取消邀请

params:

参数 含义
inviteId 邀请Id
data 自定义数据
var self = this;
Im.cancel({
    inviteId: self.inviteId,
    data: self.inviteData
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
接受邀请

被叫收到邀请通知 onReceiveNewInvitation 后可以在超时前且主叫取消前接受邀请 accept,主叫会收到接受邀请通知 setSignalingListener#onInviteeAccepted,所有被叫处理完后(包括接受、拒绝、超时)该邀请流程结束。

接收邀请

accept(params, ret) 接收方拒绝邀请

params:

参数 含义
inviteId 邀请Id
data 自定义数据
var self = this;
Im.accept({
    inviteId: self.inviteId,
    data: self.inviteData
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
拒绝邀请

被叫收到邀请通知 onReceiveNewInvitation后可以在超时前且主叫取消前拒绝邀请 reject,主叫会收到拒绝邀请通知 setSignalingListener#onInviteeRejected,所有被叫处理完后(包括接受、拒绝、超时)该邀请流程结束。

reject({params}, ret) 接收方拒绝邀请

params:

参数 含义
inviteId 邀请Id
data 自定义数据
var self = this;
Im.reject({
    inviteId: self.inviteId,
    data: self.inviteData
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
邀请超时

若邀请接口的超时时间大于0,且被叫未在超时时间之内响应则邀请超时,主叫和被叫都会收到超时通知 setSignalingListener#onInvitationTimeout,所有被叫处理完后(包括接受、拒绝、超时)该邀请流程结束。若邀请接口的超时时间等于0,则不会有超时通知。

邀请超时

用户资料与关系链

用户资料管理
查询和修改自己的资料

查询自己的资料接口为 getUsersInfo,其中参数 userIdList 需填入自己的 UserID。 修改自己的资料接口为 setSelfInfo。修改自己的资料成功后,会收到 onSelfInfoUpdated 回调。

getUsersInfo({params}, ret) 获取用户资料

参数 含义
userIdList 用户Id列表
var self = this;
Im.getUsersInfo({
    userIdList: self.userIdList
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

setSelfInfo({params}, ret) 修改个人资料

params:

参数 含义
selfSignature 个性签名
nickName 昵称
allowType 好友验证方式
var self = this;
Im.setSelfInfo({
    selfSignature: self.selfSignature,
    nickName: self.nickName,
    allowType: self.allowType
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
查询非好友用户资料

查询非好友资料接口同查询自己的资料 getUsersInfo,参数 userIdList 填入非好友的 userId 即可。

查询和修改好友资料

查询指定的好友资料接口为 getFriendsInfo,从回调信息中通过 V2TIMFriendGetResult 的 relation 字段可以得到该用户与自己的关系:

0 表示不是好友。 1 表示互为好友。 2 表示对方在我的好友列表中。 修改指定的好友信息接口为 setFriendInfo ,可修改好友备注等资料。

getFriendsInfo({params}, ret) 获取指定好友资料

params:

参数 含义
userIdList 好友userId列表
var self = this;
Im.getFriendsInfo({
    userIdList: [
        self.remoteUserId
    ]
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

setFriendInfo({params}, ret) 设置指定好友资料

params:

参数 含义
userId 用户Id
friendRemark 好友备注
var self = this;
Im.setFriendInfo({
    userId: self.remoteUserId, 
    friendRemark: self.friendRemark
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
屏蔽某人消息
  • 拉黑某人 如需屏蔽某人的消息,请调用 addToBlackList 接口把该用户加入黑名单,即拉黑该用户。 被拉黑的用户默认不会感知到“被拉黑”的状态,消息发送后不会返回已被对方拉黑的错误码。如果希望被拉黑的用户在发消息时返回已被对方拉黑的错误提醒,可以参考 被拉黑的用户发消息怎么给错误提示。

  • 解除拉黑 从黑名单中移除对方后可再次接收对方的消息,可调用 deleteFromBlackList

  • 获取黑名单列表 您可以通过 getBlackList 查看已拉黑多少用户,并对黑名单人员进行管理。

addToBlackList({params}, ret) 添加用户到黑名单

params:

参数 含义
userIdList 用户Id列表
var self = this;
Im.addToBlackList({
    userIdList: [
        self.remoteUserId
    ]
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

deleteFromBlackList({params}, ret) 把用户从黑名单中删除

params:

参数 含义
userIdList 用户Id列表
var self = this;
Im.deleteFromBlackList({
    userIdList: [
        self.remoteUserId
    ]
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

getBlackList({}, ret) 获取黑名单列表

Im.getBlackList({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
好友管理
是否需要加好友

在发送单聊消息的时候,默认不检查好友关系。在客服场景中,如果用户需要先加客服为好友才能进行沟通非常不方便,因此该默认设置常用于在线客服等场景。

如需实现类似“微信”或者“QQ”中“先加好友,再发消息”的交互体验,您可以在 即时通信 IM 控制台 >【功能配置】>【登录与消息】>【好友关系检查】中开启"发送单聊消息检查关系链"。开启后,用户只能给好友发送消息,当用户给非好友发消息时,SDK 会报20009错误码。

好友关系

好友列表管理

支持好友关系链逻辑,您可以调用 getFriendList 接口获取好友列表,调用 deleteFromFriendList 接口删除好友关系,也可以调用 addFriend 接口添加好友。

addFriend({params}, ret) 添加好友

params:

参数 含义
userId 用户Id
friendRemark 好友备注
var self = this;
Im.addFriend({
    userId: self.remoteUserId,
    friendRemark: self.friendRemark
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

deleteFromFriendList({params}, ret) 删除好友

params:

参数 含义
userIdList 要删除的好友 userID 列表
deleteType 删除类型
var self = this;
Im.deleteFromFriendList({
    userIdList: [
        self.remoteUserId
    ],
    deleteType: 1
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

根据对方用户资料中的加好友需要验证与否,可以分为两种处理流程:

第一种:加好友不需要对方验证

  1. 用户 A 和 B 调用 setFriendListener 设置关系链监听。
  2. 用户 B 通过 setSelfInfo 函数里的 allowType 字段设置为0加好友不需要验证。
  3. 用户 A 调用 addFriend 申请添加 B 为好友即可添加成功。
    • 如果申请参数 好友的application 中 addType 设置为双向好友即0,则用户 A 和 B 都会收到 setFriendListener#onFriendListAdded 回调;
    • 如果设置为单向好友即1,则只有用户 A 收到 setFriendListener#onFriendListAdded 回调。

第二种:加好友需要通过对方验证

  1. 用户 A 和 B 调用 setFriendListener 设置关系链监听。
  2. 用户 B 通过 setSelfInfo 函数里的 allowType 字段设置为1加好友需要验证 。
  3. 用户 A 调用 addFriend 申请添加 B 为好友,接口的成功回调参数中 result 中的 resultCode 返回30539,表示需要等待用户 B 的验证,同时 A 和 B 都会收到 setFriendListener#onFriendApplicationListAdded 的回调。
  4. 用户 B 会收到 setFriendListener#onFriendApplicationListAdded 的回调,当好友申请参数的application 中的 type 为 1 时,可以选择接受或者拒绝:
    • 调用 acceptFriendApplication 接受好友请求,如果参数接受类型为0, 仅同意加单向好友时,A 会收到 setFriendListener#onFriendListAdded 回调,说明单向加好友成功,B 会收到 setFriendListener#onFriendApplicationListDeleted 回调,此时 B 成为 A 的好友,但 A 仍不是 B 的好友。
    • 调用 acceptFriendApplication 接受好友请求,如果参数接受类型为 1, 同意加双向好友时,A 和 B 都会收到 setFriendListener#onFriendListAdded 回调,说明互相加好友成功。
    • 调用 refuseFriendApplication 拒绝好友请求,双方都会收到 setFriendListener#onFriendApplicationListDeleted 回调。

setFriendListener({}, ret) 设置好友监听器

Im.setFriendListener({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

getFriendApplicationList({}, ret) 获取好友申请列表

Im.getFriendApplicationList({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

acceptFriendApplication({params}, ret) 同意好友申请

params:

参数 含义
index 获取申请列表里对应的索引位置,从0开始
var self = this;
Im.acceptFriendApplication({
    index: self.index,
    type: self.checkType
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

refuseFriendApplication({params}, ret) 拒绝好友申请

params:

参数 含义
index 获取申请列表里对应的索引位置,从0开始
var self = this;
Im.refuseFriendApplication({
    index: self.index
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
好友分组管理

在某些场景下,您可能需要对好友进行分组,例如分为 "大学同学"、"公司同事" 等,您可以调用以下接口实现。

createFriendGroup({params}, ret) 新建好友分组

params:

参数 含义
groupName 分组名称
userIdList 要添加到分组中的好友 userId 列表
var self = this;
Im.createFriendGroup({
    groupName: self.friendGroupName,
    userIdList: [
        self.userId
    ]
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

deleteFriendGroup({params}, ret) 删除好友分组

params:

参数 含义
groupNameList 要删除的好友分组名称列表
var self = this;
Im.deleteFriendGroup({
    groupNameList: [
        self.friendGroupName
    ]
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

renameFriendGroup({params}, ret) 修改好友分组

params:

参数 含义
oldName 旧的分组名称
newName 新的分组名称
var self = this;
Im.renameFriendGroup({
    oldName: self.friendGroupName,
    newName: self.friendGroupName
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

getFriendGroupList({params}, ret) 获取好友分组

params:

参数 含义
groupNameList 要获取信息的好友分组名称列表
var self = this;
Im.getFriendGroupList({
    groupNameList: [
        self.friendGroupName
    ]
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

addFriendsToFriendGroup({params}, ret) 添加好友到一个分组

params:

参数 含义
groupName 分组名称
userIdList 要添加的分组中好友userId列表
var self = this;
Im.addFriendsToFriendGroup({
    groupName: self.friendGroupName,
    userIdList: [
        self.remoteUserId
    ]
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

deleteFriendsFromFriendGroup({params}, ret) 从分组中删除某好友

params:

参数 含义
groupName 分组名称
userIdList 要删除的分组中的好友userId列表
var self = this;
Im.deleteFriendsFromFriendGroup({
    groupName: self.friendGroupName,
    userIdList: [
        self.remoteUserId
    ]
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

更多功能

获取内测功能和技术支持, 请联系我们客户微信: ruanyunkeji001或ruanyunkeji002

  • 高级参数(内测)
  • 内测函数
  • 更多事件回调

trtcCalling视频语音通话

接口列表

函数 功能
init 初始化
setCallingListener 设置监听器
login 登录
call 单人通话邀请
groupCall 群组邀请通话
accept 接受当前会话
reject 拒绝当前会话
hangup 挂断当前会话
startRemoteView 渲染远端用户视频
openCamera 打开本地摄像头

快速开始

步骤一: 腾讯云配置

这个步骤比较繁琐,可以联系我们上文中的客服进行指引

注册或登录腾讯云账号,实名认证后,点击实时音视频

  1. 点击应用管理许可证

    • 如果还没有,可以点击"创建应用"
    • 或选择对应的应用, 并复制”SDKAppId“,这个ID保存为配置的文件的sdkAppId;
  2. 点击辅助工具,选择UserSig生成&校验,选择对应的应用的ID,生成userId和userSig

步骤二: 开始使用模块

  1. 新建nvue文件,注意该模块必须在nvue中使用 模块名称为: RY-TencentTrtcCalling,使用标签
    <div class="trtc">
        <RY-TencentIMPro-Calling ref="calling" v-bind:style = "{ width: playerWidth, height: playerHeight }"></RY-TencentIMPro-Calling>
    </div>

备注: 可以在js的data()中声明播放器的宽度和高度,这样在代码中可以控制这两个参数的改变,可以参考

data() {
    return {
        playerWidth: 0,
        playerHeight: 0,
        sdkAppId: 1400387416,
        userId: 'test001',
        userSig: 'eJw1zMxxxxx3CNxxxxxx',
        type: 0,
        userIdList: ['test002'],
        groupId: '',
        remoteUserId: 'test002',
        isFront: true, 
        isMute: true,
        isHandsFree: true
    }
}
  1. 模块初始化

init({params}, ret)

var self = this;
const {windowWidth, windowHeight} = uni.getSystemInfoSync();
self.playerWidth = windowWidth / 2;
self.playerHeight = windowHeight / 2;
this.$refs.calling.init({
    docPath: plus.io.convertLocalFileSystemURL('_doc')
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

可以通过直接控制组件的宽度和高度来控制显示界面的大小,如果上面的playerWidth和playerHeight。

步骤三: 设置监听

setCallingListener({} ret) 设置监听器, 监听事件回调

ret:

参数 含义
onInvited 被邀请通话回调
onUserVideoAvailable 用户是否开启视频上行回调
onUserAudioAvailable 用户是否开启音频上行回调
onCallingTimeOut onCallingTimeOut
onNoResp 对方无回应回调
onCallingCancel 当前通话被取消回调
onUserEnter 用户进入通话回调
onUserLeave 用户离开通话回调
this.$refs.calling.setCallingListener({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

步骤四: 登录

login({params}, ret) 登录

params:

参数 含义
sdkAppId 当前用户的Id
userSig 腾讯云设计的一种安全保护签名
var self = this;
    this.$refs.calling.login({
        sdkAppId: self.sdkApp Id,
        userId: self.userId, 
        userSig: self.userSig
    }, ret => {
        uni.showToast({
            title: JSON.stringify(ret),
            icon: "none"
        });
});

步骤五: 实现1V1通话

  1. 发起方: 调用call({params}, ret)发起视频或语音通话的请求。
  2. 接收方: 当接收方处于已登录状态时,监听器会收到setCallingListener#onInvited的事件回调,回调中的callType为发起方的填写的通话类型,您可以通过此参数启动相应的界面。
  3. 接收方: 如果希望接听通话,接收方可以调用accept({}, ret)函数,如果此时是视频通话,可以同时调用openCamera()函数打开自己的本地摄像头。接收方也可以使用reject()拒绝此次通话。
  4. 当双方音视频通道建立完成,通话双方还会收到setCallingListener#onUserVideoAvailable或setCallingListener#onUserAudioAvailable的事件回调。此时双方用户可以调用startRemoteView()展示远端的视频画面。视频通话远端的声音默认是自动播放的。

call 单人通话邀请

params:

参数 含义
userId 呼叫用户Id
type 通话类型:1视频/2语音
var self = this;
this.$refs.calling.call({
    userId: self.remoteUserId, 
    type: self.type
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

accept({}, ret) 接受当前通话

this.$refs.calling.accept({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

openCamera({params}, ret) 开启摄像头

params:

参数 含义
isFront true:开启前置摄像头,false:开启后置摄像头
rect 指定显示区域的坐标和大小
var self = this;
const {windowWidth, windowHeight} = uni.getSystemInfoSync();
this.$refs.calling.openCamera({
    isFront: self.isFront,
    rect: {
        x: 0, 
        y: 0, 
        w: windowWidth / 2, 
        h: windowHeight / 2
    }
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

可以通过rect指定视频显示的区域,x、y代表左上角坐标,w和h代表宽度和高度。

startRemoteView({params}, ret) 渲染远端视频

params:

参数 含义
userId 远端用户Id
rect 指定显示区域的坐标和大小
var self = this;
const {windowWidth, windowHeight} = uni.getSystemInfoSync();
this.$refs.calling.startRemoteView({
    userId: self.remoteUserId,
    rect: {
        x: 0, 
        y: 0, 
        w: windowWidth / 4, 
        h: windowHeight / 4
    }
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

可以通过rect指定视频显示的区域,x、y代表左上角坐标,w和h代表宽度和高度。

步骤六: 实现多人通话

  1. 发起方:多人视频/语音通话需要调用 groupCall() 函数,并传入用户列表(userIdList)、群组 IM ID(groupId)、通话类型(type),其中 userIdList 为必填参数,groupId 为选填参数,type 为通话类型可以填写0或者1。
  2. 接收端:通过监听器监听setCallingListener#onInvited事件回调能够接收到此呼叫请求,其中参数列表就是发起方填入的参数列表,callType 参数为通话类型,您可以通过此参数启动相应的界面。
  3. 接收端:收到回调后可以调用 accept() 方法接听此次通话,也可以选择用 reject() 方法拒绝通话。
  4. 如果超过一定时间(默认30s)没有回复,接收方监听器会收到setCallingListener#onCallingTimeOut的事件回调,发起方监听器会收到setCallingListener#onNoResp回调。通话发起方在多个接收均未应答时 hangup() ,每个接收方监听器均会收到setCallingListener#onCallingCancel回调。
  5. 如果需要离开当前多人通话可以调用 hangup() 方法。
  6. 如果通话中有用户中途加入或离开,那么其他用户监听器均会接收到setCallingListener#onUserEnter或setCallingListener#onUserLeave回调。

groupCall({params}, ret) 群组邀请通话

params:

参数 含义
userIdList 邀请Id列表
type 通话类型:1视频/2语音
groupId 群Id
var self = this;
this.$refs.calling.groupCall({
    userIdList: self.userIdList,
    type: self.type,
    groupId: self.groupId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

hangup({}, ret) 挂断当前通话

this.$refs.calling.hangup({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

更多功能

获取内测功能和技术支持,请联系我们客户微信: ruanyunkeji001或ruanyunkeji002

  • 摄像头控制(内测)
  • 音频控制(内测)
  • 更多事件回调

trtcLiveRoom视频互动直播

腾讯云实时语音, 提供互动直播的功能,包括直播、互动连麦、主播 PK、低延时观看、弹幕聊天等 在互动直播场景下的相关能力。

技术支持

原生模块本身使用复杂,再加上腾讯云音视频功能强大,造成接入难度不小。 建议使用前先联系我们的客服,协助接入。 我们的客服微信: ruanyunkeji001或ruanyunkeji002

接口列表

函数 功能
init 初始化
setLiveRoomListener 设置监听器
login 登录
setSelfProfile 修改个人信息
startCameraPreview 开启摄像头预览
createRoom 创建房间
startPublish 开始推流
getRoomInfos 获取房间信息
enterRoom 进入房间
startPlay 播放远端视频画面
requestJoinAnchor 观众请求连麦
responseJoinAnchor 主播处理连麦请求
requestRoomPK 主播请求跨房PK
responseRoomPK 主播响应跨房PK请求
quitRoomPK 退出跨房PK
sendRoomTextMsg 在房间中广播文本消息
sendRoomCustomMsg 发送自定义消息

快速开始

步骤一: 腾讯云配置

这个步骤比较繁琐,可以联系我们上文中的客服进行指引

注册或登录腾讯云账号,实名认证后,点击实时音视频

  1. 点击应用管理许可证

    • 如果还没有,可以点击"创建应用"
    • 或选择对应的应用, 并复制”SDKAppId“,这个ID保存为配置的文件的sdkAppId;
  2. 点击辅助工具,选择UserSig生成&校验,选择对应的应用的ID,生成userId和userSig

步骤二: 开始使用模块

  1. 新建nvue文件,注意该模块必须在nvue中使用 模块名称为: RY-TencentTrtcVoiceCall,使用标签
    <div class="trtc">
        <RY-TencentIMPro-LiveRoom ref="liveRoom" v-bind:style = "{ width: playerWidth, height: playerHeight }"></RY-TencentIMPro-LiveRoom>
    </div>

备注: 可以在js的data()中声明播放器的宽度和高度,这样在代码中可以控制这两个参数的改变,可以参考

data() {
    return {
        playerWidth: 0,
                playerHeight: 0,
                sdkAppId: 1400387416,
                userId: 'test001',
                userSig: 'eJw1zxxxCNMZw_',
                nickName: 'nickname001',
                avatarUrl: '',
                roomId: 1, 
                remoteRoomId: 1,
                streamId: 'stream01',
                roomName: 'room01',
                coverUrl: 'https://tesxxxx11.cos.ap-guangzhou.myqcloud.com/cover001.jpg',
                roomIdList: [1],
                isFront: true,  
                remoteUserId: 'test002',
                // remoteUserId: 'test001',
                reason: 'this is a reason',
                isAgree: true,
                cmd: 'CMD_LIKE',
                msg: 'Hello world'
    }
}
  1. 模块初始化

init({params}, ret) 初始化

var self = this;
const {windowWidth, windowHeight} = uni.getSystemInfoSync();
self.playerWidth = windowWidth / 2;
self.playerHeight = windowHeight / 2;
this.$refs.liveRoom.init({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

备注: playerWidth和playerHeight主要用来指定控制显示界面的大小。

步骤三: 设置监听器

setLiveRoomListener({} ret)

ret:

事件名称 事件含义
onAnchorEnter 收到新主播进房通知
onAudienceEnter 收到观众进房通知
onRequestJoinAnchor 主播收到观众连麦请求时的回调
onRequestRoomPK 收到请求跨房PK通知
onRecvRoomTextMsg 收到文本消息
onRecvRoomCustomMsg 收到自定义消息
this.$refs.liveRoom.setLiveRoomListener({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

步骤四: 登录

login({params}, ret)

params:

参数 含义
sdkAppId 应用ID
userId 用户Id
userSig 用户签名
var self = this;
    this.$refs.liveRoom.login({
        sdkAppId: self.sdkAppId,
        userId: self.userId,
        userSig: self.userSig
    }, ret => {
        uni.showToast({
            title: JSON.stringify(ret),
            icon: "none"
        });
});

步骤五: 主播端开播

  1. 主播登录后,可以调用setSelfProfile设置自己的昵称和头像。
  2. 主播在开播前可先调用startCameraPreview开启摄像头预览,也可以配置美颜相关功能进行美颜设置。
  3. 主播调整美颜效果后,可以调用createRoom创建新的直播间。
  4. 主播调用startPublish开始推流。

主播端开播

setSelfProfile({params}, ret) 修改个人信息

params:

参数 含义
userName 昵称
avatarUrl 头像地址
var self = this;
self.$refs.liveRoom.setSelfProfile({
    userName: self.userName,
    avatarUrl: self.avatarUrl
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

startCameraPreview({params}, ret) 开启本地视频的预览画面

params:

参数 含义
isFront 是否为前置摄像头
rect 显示区域
var self = this;
this.$refs.liveRoom.startCameraPreview({
    isFront: self.isFront,
    rect: {
        x: 0, 
        y: 0, 
        w: self.playerWidth,
        h: self.playerHeight
    }
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

createRoom({params}, ret) 创建房间(主播调用)

params:

参数 含义
roomId 房间标识,需要由您分配并进行统一管理
roomName 房间名称
coverUrl 房间封面图片url
var self = this;
self.$refs.liveRoom.createRoom({
    roomId: self.roomId,
    roomName: self.roomName, 
    coverUrl: self.coverUrl
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

startPublish({params}, ret) 开始直播(推流),适用于以下场景

  • 主播开播的时候调用
  • 观众开始连麦时调用

params:

参数 含义
streamId 用于绑定直播CDN的streamID
var self = this;
this.$refs.liveRoom.startPublish({
    streamId: self.streamId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

步骤六: 观众端观看

  1. 观众端执行登录后,可以调用setSelfProfile设置自己的昵称和头像。
  2. 观众端向业务后台获取最新的直播房间列表。
  3. 观众端调用getRoomInfos获取房间的详细信息,该信息是在主播端调用createRoom创建直播间时设置的简单描述信息。
  4. 观众选择一个直播间,调用enterRoom并传入房间号即可进入该房间。
  5. 调用startPlay并传入主播的 userId 开始播放。
    • 若直播间列表已包含主播端的 userId 信息,观众端可直接调用startPlay并传入主播的 userId 即可开始播放;
    • 若在进房前暂未获取主播的 userId,观众端在进房后会收到主播setLiveRoomListener#onAnchorEnter的事件回调,该回调中携带主播的 userId 信息,调用startPlay即可播放。

观众端观看

getRoomInfos 获取房间列表的详细信息

params:

参数 含义
roomIdList 房间号列表
var self = this;
this.$refs.liveRoom.getRoomInfos({
    roomIdList: self.roomIdList
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

enterRoom({params}, ret) 进入房间

params:

参数 含义
roomId 房间标识
var self = this;
self.$refs.liveRoom.enterRoom({
    roomId: self.roomId,
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

startPlay({params}, ret) 播放远端视频画面,可以在普通观看和连麦场景中调用

params:

参数 含义
userId 需要观看的用户Id
rect 显示区域
var self = this;
this.$refs.liveRoom.startPlay({
    userId: self.remoteUserId,
    rect: {
        x: 0, 
        y: 0,
        w: self.playerWidth / 2,
        h: self.playerHeight / 2
    }
}, ret => {
        uni.showToast({
            title: JSON.stringify(ret),
            icon: "none"
        });
});

步骤七: 观众与主播连麦

  1. 观众端调用requestJoinAnchor向主播端发起连麦请求。
  2. 主播端会收到setLiveRoomListener#onRequestJoinAnchor(即有观众请求与您连麦)的事件通知。
  3. 主播端可以通过调用responseJoinAnchor决定是否接受来自观众端的连麦请求。
  4. 主播端会收到返回结果,该结果通知会携带来自主播端的处理结果。
  5. 如果主播同意连麦请求,观众端可调用startCameraPreview开启本地摄像头,随后调用startPublish启动观众端的推流。
  6. 主播端会在观众端启动通知后收到 setLiveRoomListener#onAnchorEnter (即另一路音视频流已到来)通知,该通知会携带观众端的 userId。
  7. 主播端调用startPlay即可看到连麦观众的画面。

观众与主播连麦

requestJoinAnchor 观众请求连麦

params:

参数 含义
reason 连麦原因
var self = this;
this.$refs.liveRoom.requestJoinAnchor({
    reason: self.reason
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

responseJoinAnchor 主播处理连麦请求

params:

参数 含义
userId 观众Id
isAgree 是否同意
reason 同意/拒绝连麦的原因描述
var self = this;
this.$refs.liveRoom.responseJoinAnchor({
    userId: self.remoteUserId,
    isAgree: self.isAgree, 
    reason: self.reason
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

步骤八:主播与主播 PK

  1. 主播 A 调用requestRoomPK向主播 B 发起 PK 请求。
  2. 主播 B 会收到setLiveRoomListener#onRequestRoomPK回调通知。
  3. 主播 B 调用responseRoomPK决定是否接受主播 A 的 PK 请求。
  4. 主播 B 接受主播 A 的请求,等待setLiveRoomListener#onAnchorEnter通知,调用startPlay显示主播 A。
  5. 主播 A 收到responseCallback回调通知,PK 请求是否被同意。
  6. 主播 A 请求被同意,等待setLiveRoomListener#onAnchorEnter通知,调用startPlay显示主播 B。

主播与主播PK

requestRoomPK({params}, ret) 主播请求跨房PK

params:

参数 含义
roomId 被邀约房间Id
userId 被邀约主播Id
var self = this;
this.$refs.liveRoom.requestRoomPK({
    roomId: self.remoteRoomId,
    userId: self.remoteUserId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

responseRoomPK({params}, ret) 主播响应跨房PK请求

params:

参数 含义
userId 发起PK请求的主播Id
isAgree 是否同意
reason 同意/拒绝PK的原因描述
var self = this;
this.$refs.liveRoom.responseRoomPK({
    userId: self.remoteUserId,
    isAgree: self.isAgree, 
    reason: self.reason
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

步骤九:实现文字聊天和弹幕消息

  • 通过sendRoomTextMsg可以发送普通的文本消息,所有在该房间内的主播和观众均可以收到setLiveRoomListener#onRecvRoomTextMsg回调。 即时通信 IM 后台有默认的敏感词过滤规则,被判定为敏感词的文本消息不会被云端转发。

sendRoomTextMsg({params}, ret) 在房间中广播文本消息,一般用于弹幕聊天

params:

参数 含义
msg 文本消息
var self = this;
this.$refs.liveRoom.sendRoomTextMsg({
    msg: self.msg
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
  • 通过sendRoomCustomMsg可以发送自定义(信令)的消息,所有在该房间内的主播和观众均可以收到setLiveRoomListener#onRecvRoomCustomMsg回调。 自定义消息常用于传输自定义信令,例如用于点赞消息的发送和广播。、

sendRoomCustomMsg({params}, ret) 发送自定义文本消息

params:

参数 含义
cmd 命令字,由开发者自定义,主要用于区分不同消息类型
msg 文本消息
var self = this;
this.$refs.liveRoom.sendRoomCustomMsg({
    cmd: self.cmd, 
    msg: self.msg
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

更多功能

获取内测功能和技术支持,请联系我们客户微信: ruanyunkeji001或ruanyunkeji002

  • 音视频控制(内测)
  • 背景音乐音效(内测)
  • 基础美颜(内测)
  • 更多高级事件

trtcVoiceRoom语音聊天室

该模块提供语音聊天室的功能, 包括麦位管理、低延时语音互动、文字聊天等 TRTC 在语音聊天场景下的相关能力。

技术支持

原生模块本身使用复杂,再加上腾讯云音视频功能强大,造成接入难度不小。 建议使用前先联系我们的客服,我们的客服微信: ruanyunkeji001或ruanyunkeji002

接口列表

函数 功能
init 初始化
setVoiceRoomListener 设置监听器
login 登录
setSelfProfile 设置个人信息
creatRoom 创建房间
getRoomInfoList 获取房间列表的详细信息
enterRoom 进入房间
enterSeat 主动上麦
pickSeat 抱人上麦
kickSeat 踢人下麦
muteSeat 静音/解除静音某个麦位
closeSeat 封禁/解禁某个麦位
leaveSeat 主动下麦
sendInvitation 向用户发送邀请
[acceptInvitation]((#acceptInvitation) 接受邀请
sendRoomTextMsg 在房间中广播文本消息
sendRoomCustomMsg 发送自定义文本消息

快速开始

步骤一: 腾讯云配置

这个步骤比较繁琐,可以联系我们上文中的客服进行指引

注册或登录腾讯云账号,实名认证后,点击实时音视频

  1. 点击应用管理许可证

    • 如果还没有,可以点击"创建应用"
    • 或选择对应的应用, 并复制”SDKAppId“,这个ID保存为配置的文件的sdkAppId;
  2. 点击辅助工具,选择UserSig生成&校验,选择对应的应用的ID,生成userId和userSig

步骤二: 开始使用模块

  1. 新建nvue文件,注意该模块必须在nvue中使用 模块名称为: RY-TencentTrtcVoiceRoom,使用标签
    <div class="trtc">
        <RY-TencentIMPro-VoiceRoom ref="voiceRoom" v-bind:style = "{ width: playerWidth, height: playerHeight }"></RY-TencentIMPro-VoiceRoom>
    </div>

参数列表:

data() {
    return {
        playerWidth: 0,
        playerHeight: 0,
        sdkAppId: 1400387416,
        userId: 'test001',
        userSig: 'eJw1zMEOgjAxxxxMXeH3CNMZw_',
        userName: 'username001',
        avatarUrl: '',
        roomId: 919, 
        roomParam: {
            roomName: 'rxxj001',
            seatCount: 7, 
            needRequest: false,
            coverUrl: 'https://test001-12xxxxxud.com/cover001.jpg'
        },
        roomIdList: [1],
        userIdList: ['test001'],
        seatIndex: 0,
        remoteUserId: 'test002',
        isMute: true, 
        isClose: true,
        invitationCmd: 'this is invitation cmd', 
        content: 'this is content',
        identifier: '',
        msg: 'this is a message',
        cmd: 'this is a cmd'
    }
}
  1. 模块初始化

init({params}, ret)

var self = this;
const {windowWidth, windowHeight} = uni.getSystemInfoSync();
self.playerWidth = windowWidth / 2;
self.playerHeight = windowHeight / 2;
this.$refs.voiceRoom.init({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

可以通过直接控制组件的宽度和高度来控制显示界面的大小,如果上面的playerWidth和playerHeight。

步骤三: 设置监听

调用setVoiceRoomListener函数注册组件的事件回调通知

setVoiceRoomListener({} ret) 设置监听

ret: 回调名称 含义
onSeatListChang 全量的麦位列表
onAnchorEnterSeat 有成员上麦(主动上麦/主播抱人上麦)
onRoomInfoChange 进房成功后会回调该接口,roomInfo 中的信息在创建房间
onAnchorLeaveSeat 有成员下麦(主动下麦/主播踢人下麦)
onSeatMute 主播禁麦
onSeatClose 主播封麦
this.$refs.voiceRoom.setVoiceRoomListener({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

步骤四: 登录

调用login函数完成组件的登录,请参考下表填写关键参数

login({params}, ret) 登录

params: 参数 含义
sdkAppId 您可以在实时音视频控制台 >【应用管理】> 应用信息中查看 SDKAppID
userId 当前用户的Id
userSig 腾讯云设计的一种安全保护签名
var self = this;
    this.$refs.voiceRoom.login({
        sdkAppId: self.sdkApp Id,
        userId: self.userId, 
        userSig: self.userSig
    }, ret => {
        uni.showToast({
            title: JSON.stringify(ret),
            icon: "none"
        });
});

步骤五: 主播端开播

  1. 主播执行 步骤4 登录后,可以调用setSelfProfile设置自己的昵称和头像。
  2. 主播调用createRoom创建新的语音聊天室,此时传入房间 ID、上麦是否需要房主确认、麦位数等房间属性信息。
  3. 主播创建房间成功后,调用enterSeat进入座位。
  4. 主播收到组件的setVoiceRoomListener#onSeatListChange麦位表变化事件通知,此时可以将麦位表变化刷新到 UI 界面上。
  5. 主播还会收到麦位表有成员进入的setVoiceRoomListener#onAnchorEnterSeat的事件通知,此时会自动打开麦克风采集。

主播端开播

setSelfProfile({params}, ret) 设置个人信息

params: 参数 含义
userName 昵称
avatarUrl 头像地址
var self = this;
self.$refs.voiceRoom.setSelfProfile({
    userName: self.userName,
    avatarUrl: self.avatarUrl
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

creatRoom({params}, ret) 创建房间(主播调用)

params: 参数 含义
roomId 房间标识,需要由您分配并进行统一管理
roomParam 房间信息,用于房间描述的信息
var self = this;
this.$refs.voiceRoom.createRoom({
    roomId: self.roomId, 
    roomParam: self.roomParam
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

enterSeat({params}, ret) 主动上麦,主播和观众均可调用

params: 参数 含义
seatIndex 需要上麦的麦位序号
var self = this;
this.$refs.voiceRoom.enterSeat({
    seatIndex: self.seatIndex
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

步骤六: 观众端观看

  1. 观众端执行 步骤4 登录后,可以调用setSelfProfile设置自己的昵称和头像。
  2. 观众端向业务后台获取最新的语音聊天室房间列表。
  3. 观众端调用getRoomInfoList获取房间的详细信息,该信息是在主播端调用createRoom创建语音聊天室时设置的简单描述信息。
  4. 观众选择一个语音聊天室,调用enterRoom并传入房间号即可进入该房间。
  5. 进房后会收到组件的setVoiceRoomListener#onRoomInfoChange房间属性变化事件通知,此时可以记录房间属性并做相应改变,例如 UI 展示房间名、记录上麦是否需要请求主播同意等。
  6. 进房后会收到组件的setVoiceRoomListener#onSeatListChange麦位表变化事件通知,此时可以将麦位表变化刷新到 UI 界面上。
  7. 进房后还会收到麦位表有主播进入的setVoiceRoomListener#onAnchorEnterSeat的事件通知。

观众端观看

getRoomInfoList({params}, ret) 获取房间列表的详细信息,其中房间名称、房间封面是主播在创建 createRoom() 时通过 roomInfo 设置的

params: 参数 含义
roomIdList 房间号列表
var self = this;
this.$refs.voiceRoom.getRoomInfoList({
    roomIdList: self.roomIdList
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

enterRoom({params}, ret) 进入房间(观众调用)

params: 参数 含义
roomId 房间标识
var self = this;
this.$refs.voiceRoom.enterSeat({
    seatIndex: self.seatIndex
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

步骤七: 麦位管理

主播端:

  1. pickSeat传入对应的麦位和观众 userId, 可以抱人上麦,房间内所有成员会收到setVoiceRoomListener#onSeatListChange和setVoiceRoomListener#onAnchorEnterSeat的事件通知。
  2. kickSeat传入对应麦位后,可以踢人下麦,房间内所有成员会收到setVoiceRoomListener#onSeatListChange和setVoiceRoomListener#onAnchorLeaveSeat的事件通知。
  3. muteSeat传入对应麦位后,可以静音/解除静音,房间内所有成员会收到setVoiceRoomListener#onSeatListChange 和 setVoiceRoomListener#onSeatMute 的事件通知。
  4. closeSeat传入对应麦位后,可以封禁/解禁某个麦位,封禁后观众端将不能再上麦,房间内所有成员会收到setVoiceRoomListener#onSeatListChange和setVoiceRoomListener#onSeatClose的事件通知。

主播端

pickSeat({params}, ret) 抱人上麦(主播调用)

params: 参数 含义
seatIndex 需要抱上麦的麦位序号
userId 用户 ID
var self = this;
this.$refs.voiceRoom.pickSeat({
    seatIndex: self.seatIndex, 
    userId: self.userId
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

kickSeat({params}, ret) 踢人下麦(主播调用)

params: 参数 含义
seatIndex 需要踢下麦的麦位序号
var self = this;
this.$refs.voiceRoom.kickSeat({
    seatIndex: self.seatIndex
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

museSeat({params}, ret) 静音/解除静音某个麦位(主播调用)

params: 参数 含义
seatIndex 需要操作的麦位序号
var self = this;
this.$refs.voiceRoom.muteSeat({
    seatIndex: self.seatIndex, 
    isMute: self.isMute
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

closeSeat({params}, ret) 封禁/解禁某个麦位(主播调用)

params: 参数 含义
seatIndex 需要操作的麦位序号
isClose 是否封禁对应的麦位
var self = this;
this.$refs.voiceRoom.closeSeat({
    seatIndex: self.seatIndex, 
        isClose: self.isClose
    }, ret => {
        uni.showToast({
            title: JSON.stringify(ret),
            icon: "none"
        });
});

观众端:

  1. enterSeat传入对应的麦位后,可以进行上麦,房间内所有成员会收到setVoiceRoomListener#onSeatListChange和setVoiceRoomListener#onAnchorEnterSeat的事件通知。
  2. leaveSeat主动下麦,房间内所有成员会收到setVoiceRoomListener#onSeatListChange和setVoiceRoomListener#onAnchorLeaveSeat的事件通知。

观众端

leaveSeat({params}, ret) 主动下麦(观众端和主播均可调用)

var self = this;
this.$refs.voiceRoom.leaveSeat({}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

步骤八:邀请信令使用

在 麦位管理 中,观众上下麦、主播抱人上麦都不需要经过对方的同意就可以直接操作。 如果您的 App 需要对方同意才能进行下一步操作的业务流程,那么邀请信令可以提供相应支持。 如果您的观众上麦需要申请:

  1. 观众端调用sendInvitation传入主播的 userId 和业务的自定义命令字等,此时函数会返回一个 inviteId,记录该 inviteId。
  2. 主播端收到setVoiceRoomListener#onReceiveNewInvitation的事件通知,此时 UI 可以弹窗并询问主播是否同意。
  3. 主播选择同意后,调用acceptInvitation并传入 inviteId。
  4. 观众端收到setVoiceRoomListener#onInviteeAccepted的事件通知,调用enterSeat进行上麦。

观众上麦需要申请

sendInvitation({params}, ret) 向用户发送邀请

params: 参数 含义
cmd 业务自定义指令
userId 邀请的用户 ID
content 邀请的内容
var self = this;
this.$refs.voiceRoom.sendInvitation({
    cmd: self.invitationCmd, 
    userId: self.remoteUserId,
    content: self.content
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

acceptInvitation({params}, ret) 接受邀请

params: 参数 含义
identifier 邀请ID
var self = this;
this.$refs.voiceRoom.acceptInvitation({
    identifier: self.identifier
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

如果您的主播需要发送邀请才能抱观众上麦:

  1. 主播端调用sendInvitation传入观众的 userId 和业务的自定义命令字等,此时函数会返回一个 inviteId,记录该 inviteId。
  2. 观众端收到setVoiceRoomListener#onReceiveNewInvitation的事件通知,此时 UI 可以弹窗并询问观众是否同意上麦。
  3. 观众选择同意后,调用acceptInvitation并传入 inviteId。
  4. 主播端收到setVoiceRoomListener#onInviteeAccepted的事件通知,调用pickSeat抱观众上麦。

需要主播发送申请才能抱观众上麦

步骤九:实现文字和弹幕消息

  • 通过sendRoomTextMsg可以发送普通的文本消息,所有在该房间内的主播和观众均可以收到setVoiceRoomListener#onRecvRoomTextMsg回调 即时通信 IM 后台有默认的敏感词过滤规则,被判定为敏感词的文本消息不会被云端转发。

sendRoomTextMsg({params}, ret) 在房间中广播文本消息,一般用于弹幕聊天

params 参数 含义
msg 文本消息
var self = this;
this.$refs.voiceRoom.sendRoomTextMsg({
    msg: self.msg
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});
  • 通过sendRoomCustomMsg可以发送自定义(信令)的消息,所有在该房间内的主播和观众均可以收到onRecvRoomCustomMsg回调。 自定义消息常用于传输自定义信令,例如用于点赞消息的发送和广播。

sendRoomCustomMsg({params}, ret) 发送自定义文本消息

params: 参数 含义
cmd 命令字,由开发者自定义,主要用于区分不同消息类型
msg 文本消息
var self = this;
this.$refs.voiceRoom.sendRoomCustomMsg({
    cmd: self.cmd, 
    msg: self.msg
}, ret => {
    uni.showToast({
        title: JSON.stringify(ret),
        icon: "none"
    });
});

更多功能

获取内测功能和技术支持,请联系我们客户微信: ruanyunkeji001或ruanyunkeji002

  • 背景音乐音效
  • 音频控制
  • 更多事件回调

隐私、权限声明

1. 本插件需要申请的系统权限列表:

Android: "android.permission.RECEIVE_BOOT_COMPLETED", "android.permission.INTERNET", "android.permission.ACCESS_NETWORK_STATE", "android.permission.ACCESS_WIFI_STATE", "aandroid.permission.WRITE_EXTERNAL_STORAGE", "android.permission.READ_EXTERNAL_STORAGE", "android.permission.RECORD_AUDIO", "android.permission.MODIFY_AUDIO_SETTINGS", "android.permission.BLUETOOTH", "android.permission.CAMERA", "android.permission.READ_PHONE_STATE", "android.hardware.camera", "android.hardware.camera.autofocus" iOS: 无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件使用的腾讯IM SDK会采集数据,详情可参考:https://cloud.tencent.com/document/product/269

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问