RtmClient 类

最近更新时间:2022-09-20 05:17:40

通过 ArRTM 上的 createInstance 方法创建 RTM 客户端实例。

示例

本示例为创建一个 RtmClient 示例,本页所有的示例都是基于当前这个 RtmClient 示例执行。

import ArRTM from "ar-rtm-sdk";
/**
 * 创建 RTM 客户端实例
 * @params appId: 项目的 App ID。必须是 ASCII 编码,长度为 32 个字符。(类型:string)
 */
const client = ArRTM.createInstance(appId);

核心方法

login

login(options: loginOptions): Promise<void>

用户登录 anyRTC RTM 系统。

注意事项
1. 同时进行 RTM 和 RTC 系统的登录操作,推荐先登录 RTM 系统再登录 RTC 系统,错时登录更加高效。
2. 使用相同用户 ID 登录时,之前登录的用户会被踢出系统,同时也会从之前加入的频道中踢出。

参数

参数类型描述
optionsloginOptionsRTM 登录配置, 设置 uid、token 等信息。

示例

/**
 * 用户登录 anyRTC RTM 系统
 * @params options: 参数详见上方
 */
client.login({ token: "undefined", uid: "userID" })
    .then(() => { })
    .catch((err) => { });

返回

Promise<void>

logout

logout(): Promise<void>

退出 RTM 系统。

退出后自动断开连接和销毁回调监听。

示例

/**
 * 退出登录,退出后自动断开连接和销毁回调监听 (必须先登录)
 */
client.logout()
    .then(() => { })
    .catch((err) => { });

返回

void

sendMessageToPeer

sendMessageToPeer(
    message: RtmMessage,
    peerId: string,
    options?: SendMessageOption): Promise<PeerMessageSendResult>

本地用户向指定用户发送消息或离线消息。

发送消息(包括点对点消息和频道消息)的频率上限为 60 次每秒。

注意事项:
uid 不支持 number 类型。建议调用 tostring() 方法转化非 string 型 uid。

参数

参数类型描述
messageRtmMessage要发送的文字消息对象。可以选择使用 RtmTextMessage
peerIdstring远端用户的 uid。
optionsSendMessageOption消息属性配置,比如是否为离线消息。

示例

/**
 * 本地用户(发送者)向指定用户(接收者)发送点对点消息或点对点的离线消息  sendMessageToPeer
 * @params PeerId: 远端用户的 uid
 */
client.sendMessageToPeer(
    { text: "要发送的文字消息" }, // 一个 RtmMessage 实例。  
    "PeerId",
).then({ hasPeerReceived } => {
    if (hasPeerReceived) {
        // 你的代码:远端用户收到消息事件。  
    } else {
        // 你的代码:服务器已收到消息,对端未收到消息。  
    }
}).catch((err) => {
// 你的代码:点对点消息发送失败。 
});

返回

Promise<PeerMessageSendResult>

查询人员上下线

queryPeersBySubscriptionOption

queryPeersBySubscriptionOption(option: PeerSubscriptionOption): Promise<string[]>

获取某特定用户类型的用户列表。

参数

参数类型描述
optionPeerSubscriptionOption订阅用户设定内容的配置。

示例

/**
 * 获取某特定内容被订阅的用户列表回调 queryPeersBySubscriptionOption
 * @params option: 订阅类型
 */
client.queryPeersBySubscriptionOption("ONLINE_STATUS")
    .then((peerSubscriptionOption) => { })
    .catch((err) => { });

返回

Promise<string[]>

queryPeersOnlineStatus

queryPeersOnlineStatus(peerIds: string[]): Promise<PeersOnlineStatusResult>

查询指定用户的在线状态。

参数

参数类型描述
peerIdsArray用户 ID 列表。用户 ID 个数不能超过 256。

示例

/**
 * 查询指定用户的在线状态。
 * @params peerIds: 用户 ID 列表。用户 ID 个数不能超过 256 (类型:array)
 */
client.queryPeersOnlineStatus(['123456', '55555'])
    .then((peersOnlineStatusResult) => { })
    .catch((err) => { });

返回

Promise<PeersOnlineStatusResult>

订阅人员上下线

subscribePeersOnlineStatus

subscribePeersOnlineStatus(peerIds: string[]): Promise<void>

订阅指定单个或多个用户的在线状态。

  • 首次订阅成功后,SDK 会通过 PeersOnlineStatusChanged 回调返回被订阅用户在线状态。
  • 每当被订阅用户在线状态发生变化时,SDK 都会通过 PeersOnlineStatusChanged 回调通知订阅方。
  • 如果 SDK 在断线重连过程中有被订阅用户的在线状态发生改变,SDK 会在重连成功时通过 PeersOnlineStatusChanged 回调通知订阅方。

1. 用户登出 anyRTC RTM 系统后,所有之前的订阅内容都会被清空;重新登录后,如需保留之前订阅内容则需重新订阅。
2. SDK 会在网络连接中断时进入断线重连状态。重连成功时 SDK 会自动重新订阅之前订阅用户,无需人为干预。

参数

参数类型描述
peerIdsArray订阅用户的用户 ID 阵列。

示例

...
/**
 * 订阅指定单个或多个用户的在线状态。
 * @params peerIds: 订阅用户的用户 ID 阵列 (类型:array)
 */
client.subscribePeersOnlineStatus(['123456', '55555'])
    .then(() => { })
    .catch((err) => { });

返回

Promise<void>

unsubscribePeersOnlineStatus

unsubscribePeersOnlineStatus(peerIds: string[]): Promise<void>

退订指定单个或多个用户的在线状态。

参数

参数类型描述
peerIdsArray被退订用户的用户 ID 阵列。

示例

/**
 * 退订指定单个或多个用户的在线状态。
 * @params peerIds: 被退订用户的用户 ID 阵列 (类型:array)
 */
client.unsubscribePeersOnlineStatus(['123456', '55555'])
    .then(() => { })
    .catch((err) => { });

返回

Promise<void>

用户属性增删改查

setLocalUserAttributes

setLocalUserAttributes(attributes: AttributesMap): Promise<void>

全量设置本地用户的属性。

参数

参数类型描述
attributesAttributesMap自定义本地用户属性。

示例

/**
 * 全量设置本地用户的属性。
 * @params attributes: 新的属性 (类型:object)
 */
client.setLocalUserAttributes({
    userName: '开发小王子',
    age: 1024,
})
    .then(() => { })
    .catch((err) => { });

返回

Promise<void>

addOrUpdateLocalUserAttributes

addOrUpdateLocalUserAttributes(attributes: AttributesMap): Promise<void>

添加或更新本地用户的属性。

  • 如果属性已存在,该方法更新本地用户的已有属性;
  • 如果属性不存在,该方法增加本地用户的属性。

示例

/**
 * 添加或更新本地用户的属性。
 * @params attributes: 待增加或更新的属性列表 (类型:object)
 */
client.addOrUpdateLocalUserAttributes({
    userName: '开发最强王者',
    age: 1024,
})
    .then(() => { })
    .catch((err) => { });

参数

参数类型描述
attributesAttributesMap待增加或更新的属性列表。

返回

Promise<void>

deleteLocalUserAttributesByKeys

deleteLocalUserAttributesByKeys(attributeKeys: string[]): Promise<void>

删除本地用户的指定属性。

参数

参数类型描述
attributeKeysArray属性名列表。

示例

/**
 * 删除本地用户的指定属性。
 * @params attributeKeys: 属性名列表 (类型:array)
 */
client.deleteLocalUserAttributesByKeys(['age'])
    .then(() => { })
    .catch((err) => { });

返回

Promise<void>

clearLocalUserAttributes

clearLocalUserAttributes(): Promise<void>

清空本地用户的所有属性。

示例

/**
 * 清空本地用户的所有属性。
 */
client.clearLocalUserAttributes()
    .then(() => { })
    .catch((err) => { });

返回

Promise<void>

getUserAttributes

getUserAttributes(userId: string): Promise<AttributesMap>

获取指定用户的全部属性。

参数

参数类型描述
userIdstring指定用户的用户 ID。

示例

/**
 * 获取指定用户的全部属性。
 * @params userId: 指定用户的用户 ID。(类型:string)
 */
client.getUserAttributes('123456')
    .then((attributesMap) => { })
    .catch((err) => { });

返回

Promise<AttributesMap>

getUserAttributesByKeys

getUserAttributesByKeys(userId: string, attributeKeys: string[]): Promise<AttributesMap>

获取指定用户指定属性名的属性。

参数

参数类型描述
userIdstring指定用户的用户 ID。
attributeKeysArray用户属性名列表。

示例

/**
 * 获取指定用户指定属性名的属性
 * @params userId:  指定用户的用户 ID。(类型:string)
 * @params attributeKeys: 用户属性名列表。(类型:array)
 */
client.getUserAttributesByKeys('123456', ['userName'])
    .then((attributesMap) => { })
    .catch((err) => { });

返回

Promise<AttributesMap>

创建频道

createChannel

createChannel(channelId: string): RtmChannel

该方法创建一个 RtmChannel 实例。

请不要将 channelId 设为字符串 "null"。

参数

参数类型描述
channelIdstring频道名称。该字符串不可超过 64 字节。

示例

/**
 * 创建一个 RtmClient 实例
 * @params channelId: 频道名称。(类型:string)
 */
const rtmChannel = client.createChannel('123456789');

返回

一个 RtmChannel 实例。

获取频道人数

getChannelMemberCount

getChannelMemberCount(channelIds: string[]): Promise<ChannelMemberCountResult>

查询单个或多个频道的成员人数。

注意事项

  • 该方法的调用频率上限为每秒 1 次。
  • 不支持一次查询超过 32 个频道的成员人数。
  • 返回值 Promise<ChannelMemberCountResult>

参数

参数类型描述
channelIdsArray指定频道名列表。

示例

/**
 * 查询单个或多个频道的成员人数。
 * @params channelIds: 指定频道名列表。(类型:array)
 */
client.getChannelMemberCount(['123456789'])
    .then((channelMemberCountResult) => { })
    .catch((err) => { });

返回

Promise<ChannelMemberCountResult>

频道属性增删改查

setChannelAttributes

setChannelAttributes(channelId: string, attributes: AttributesMap, options?: ChannelAttributeOptions): Promise<void>

全量设置某指定频道的属性。

注意事项

参数

参数类型描述
channelIdstring该指定频道的频道 ID。
attributesAttributesMap频道属性列表实例。
optionsChannelAttributeOptions频道属性操作选项。

示例

/**
 * 全量设置某指定频道的属性。
 * @params channelId: 指定频道的频道 ID (类型:string)
 * @params attributes: 频道属性列表实例 (类型:object)
 * @params options: 频道属性操作选项 (类型:object)
 */
client.setChannelAttributes(channelId, attributes, options)
    .then(() => { })
    .catch((err) => { });

返回

Promise<void>

addOrUpdateChannelAttributes

addOrUpdateChannelAttributes(channelId: string, attributes: AttributesMap, options?: ChannelAttributeOptions): Promise<void>

添加或更新某指定频道的属性。

注意事项

参数

参数类型描述
channelIdstring该指定频道的 ID。
attributesAttributesMap待增加或更新的属性列表。
optionsChannelAttributeOptions频道属性操作选项。

示例

/**
 * 添加或更新某指定频道的属性。
 * @params channelId: 指定频道的 ID (类型:string)
 * @params attributes: 待增加或更新的属性列表 (类型:object)
 * @params options: 频道属性操作选项 (类型:object)
 */
client.addOrUpdateChannelAttributes(channelId, attributes, options)
    .then(() => { })
    .catch((err) => { });

返回

Promise<void>

deleteChannelAttributesByKeys

deleteChannelAttributesByKeys(channelId: string, attributeKeys: string[], options?: ChannelAttributeOptions): Promise<void>

删除某指定频道的指定属性。

注意事项

参数

参数类型描述
channelIdstring该指定频道的 ID。
attributeKeysArray属性名列表。
optionsChannelAttributeOptions频道属性操作选项。

示例

/**
 * 删除指定频道的指定属性。
 * @params channelId: 被叫的 uid。(类型:string)
 * @params attributeKeys: 属性名列表 (类型:array)
 * @params options: 频道属性操作选项 (类型:object)
 */
client.deleteChannelAttributesByKeys(channelId, attributeKeys, options)
    .then(() => { })
    .catch((err) => { });

返回

Promise<void>

clearChannelAttributes

clearChannelAttributes(channelId: string, options?: ChannelAttributeOptions): Promise<void>

清空某指定频道的属性。

注意事项

参数

参数类型描述
channelIdstring该指定频道的 ID。
optionsObject频道属性操作选项,参数详见ChannelAttributeOptions说明。

示例

/**
 * 清空某指定频道的属性。
 * @params channelId: 指定频道的 ID (类型:string)
 * @params options: 频道属性操作选项 (类型:object)
 */
client.clearChannelAttributes(channelId, options)
    .then(() => { })
    .catch((err) => { });

返回

Promise<void>

getChannelAttributes

getChannelAttributes(channelId: string): Promise<ChannelAttributes>

查询某指定频道的全部属性。

注意事项

参数

参数类型描述
channelIdstring该指定频道的 ID。

示例

/**
 * 查询某指定频道的全部属性。(无需加入指定频道即可查询该频道的属性)
 * @params channelId: 指定频道的 ID。(类型:string)
 */
client.getChannelAttributes(channelId)
    .then((channelAttributes) => { })
    .catch((err) => { });

返回

Promise<ChannelAttributes>

getChannelAttributesByKeys

getChannelAttributesByKeys(channelId: string, keys: string[]): Promise<ChannelAttributes>

查询某指定频道指定属性名的属性。

注意事项

参数

参数类型描述
channelIdstring该指定频道的 ID。
keysArray频道属性名列表。

示例

/**
 * 查询某指定频道指定属性名的属性。(无需加入指定频道即可查询该频道的属性)
 * @params channelId: 指定频道的 ID。(类型:string)
 * @params keys: 频道属性名列表。(类型:array)
 */
client.getChannelAttributesByKeys(channelId, keys)
    .then((channelAttributes) => { })
    .catch((err) => { });

返回

Promise<ChannelAttributes>

呼叫邀请

createLocalInvitation

createLocalInvitation(calleeId: string): LocalInvitation

该方法创建一个 LocalInvitation 实例。

参数

参数类型描述
calleeIdstring被叫的 uid。

示例

/**
 * 创建一个 LocalInvitation 实例
 * @params calleeId: 被叫的 uid。(类型:string)
 */
const localInvitation = client.createLocalInvitation(calleeId);

返回

一个 LocalInvitation 实例。

其他

on

on(event: string, callback: (...args: any[]) => void): void;

在该频道实例上添加 listener 函数到名为 eventName 的事件。其他 RtmClient 实例上的事件方法请参考 EventEmitter API 文档。

参数

参数类型描述
eventNamestringRTM 客户端事件的名称。
listenerfunction事件的回调函数。RtmClientEvents[eventName]

示例

/**
 * 通过绑定 SDK 提供的事件回调进行相关操作监听
 * @params eventName: SDK RTM 客户端提供的事件的名称。(类型:string)
 * @params ...args: 不同的事件,回调参数是不同的。(类型:any[])
 */
client.on("MessageFromPeer", (message, peerId, messageProps) => {

});

返回

void

renewToken

renewToken(token: string): Promise<void>

更新当前 Token。

参数

参数类型描述
tokenstring新的 Token。

示例

/**
 * 更新当前 Token
 * @params token: 新的 Token (类型:string)
 */
client.renewToken(token)
    .then(() => { })
    .catch((err) => { });

返回

Promise<void>

setParameters

setParameters(params: RtmParameters): void

配置 SDK 提供技术预览或特别定制功能。

参数

参数类型描述
paramsRtmParameters定制功能。

示例

/**
 * 全量设置本地用户的属性。
 * @params params: 定制功能 (类型:object)
 */
client.setParameters(params);

返回

void