通过 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 登录时,之前登录的用户会被踢出系统,同时也会从之前加入的频道中踢出。
参数
参数 | 类型 | 描述 |
---|---|---|
options | loginOptions | RTM 登录配置, 设置 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。
参数
参数 | 类型 | 描述 |
---|---|---|
message | RtmMessage | 要发送的文字消息对象。可以选择使用 RtmTextMessage。 |
peerId | string | 远端用户的 uid。 |
options | SendMessageOption | 消息属性配置,比如是否为离线消息。 |
示例
/**
* 本地用户(发送者)向指定用户(接收者)发送点对点消息或点对点的离线消息 sendMessageToPeer
* @params PeerId: 远端用户的 uid
*/
client.sendMessageToPeer(
{ text: "要发送的文字消息" }, // 一个 RtmMessage 实例。
"PeerId",
).then({ hasPeerReceived } => {
if (hasPeerReceived) {
// 你的代码:远端用户收到消息事件。
} else {
// 你的代码:服务器已收到消息,对端未收到消息。
}
}).catch((err) => {
// 你的代码:点对点消息发送失败。
});
返回
Promise<PeerMessageSendResult>
查询人员上下线
queryPeersBySubscriptionOption
queryPeersBySubscriptionOption(option: PeerSubscriptionOption): Promise<string[]>
获取某特定用户类型的用户列表。
参数
参数 | 类型 | 描述 |
---|---|---|
option | PeerSubscriptionOption | 订阅用户设定内容的配置。 |
示例
/**
* 获取某特定内容被订阅的用户列表回调 queryPeersBySubscriptionOption
* @params option: 订阅类型
*/
client.queryPeersBySubscriptionOption("ONLINE_STATUS")
.then((peerSubscriptionOption) => { })
.catch((err) => { });
返回
Promise<string[]>
queryPeersOnlineStatus
queryPeersOnlineStatus(peerIds: string[]): Promise<PeersOnlineStatusResult>
查询指定用户的在线状态。
参数
参数 | 类型 | 描述 |
---|---|---|
peerIds | Array | 用户 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 会自动重新订阅之前订阅用户,无需人为干预。
参数
参数 | 类型 | 描述 |
---|---|---|
peerIds | Array | 订阅用户的用户 ID 阵列。 |
示例
...
/**
* 订阅指定单个或多个用户的在线状态。
* @params peerIds: 订阅用户的用户 ID 阵列 (类型:array)
*/
client.subscribePeersOnlineStatus(['123456', '55555'])
.then(() => { })
.catch((err) => { });
返回
Promise<void>
unsubscribePeersOnlineStatus
unsubscribePeersOnlineStatus(peerIds: string[]): Promise<void>
退订指定单个或多个用户的在线状态。
参数
参数 | 类型 | 描述 |
---|---|---|
peerIds | Array | 被退订用户的用户 ID 阵列。 |
示例
/**
* 退订指定单个或多个用户的在线状态。
* @params peerIds: 被退订用户的用户 ID 阵列 (类型:array)
*/
client.unsubscribePeersOnlineStatus(['123456', '55555'])
.then(() => { })
.catch((err) => { });
返回
Promise<void>
用户属性增删改查
setLocalUserAttributes
setLocalUserAttributes(attributes: AttributesMap): Promise<void>
全量设置本地用户的属性。
参数
参数 | 类型 | 描述 |
---|---|---|
attributes | AttributesMap | 自定义本地用户属性。 |
示例
/**
* 全量设置本地用户的属性。
* @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) => { });
参数
参数 | 类型 | 描述 |
---|---|---|
attributes | AttributesMap | 待增加或更新的属性列表。 |
返回
Promise<void>
deleteLocalUserAttributesByKeys
deleteLocalUserAttributesByKeys(attributeKeys: string[]): Promise<void>
删除本地用户的指定属性。
参数
参数 | 类型 | 描述 |
---|---|---|
attributeKeys | Array | 属性名列表。 |
示例
/**
* 删除本地用户的指定属性。
* @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>
获取指定用户的全部属性。
参数
参数 | 类型 | 描述 |
---|---|---|
userId | string | 指定用户的用户 ID。 |
示例
/**
* 获取指定用户的全部属性。
* @params userId: 指定用户的用户 ID。(类型:string)
*/
client.getUserAttributes('123456')
.then((attributesMap) => { })
.catch((err) => { });
返回
Promise<AttributesMap>
getUserAttributesByKeys
getUserAttributesByKeys(userId: string, attributeKeys: string[]): Promise<AttributesMap>
获取指定用户指定属性名的属性。
参数
参数 | 类型 | 描述 |
---|---|---|
userId | string | 指定用户的用户 ID。 |
attributeKeys | Array | 用户属性名列表。 |
示例
/**
* 获取指定用户指定属性名的属性
* @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"。
参数
参数 | 类型 | 描述 |
---|---|---|
channelId | string | 频道名称。该字符串不可超过 64 字节。 |
示例
/**
* 创建一个 RtmClient 实例
* @params channelId: 频道名称。(类型:string)
*/
const rtmChannel = client.createChannel('123456789');
返回
一个 RtmChannel 实例。
获取频道人数
getChannelMemberCount
getChannelMemberCount(channelIds: string[]): Promise<ChannelMemberCountResult>
查询单个或多个频道的成员人数。
注意事项
- 该方法的调用频率上限为每秒 1 次。
- 不支持一次查询超过 32 个频道的成员人数。
- 返回值 Promise<ChannelMemberCountResult>
参数
参数 | 类型 | 描述 |
---|---|---|
channelIds | Array | 指定频道名列表。 |
示例
/**
* 查询单个或多个频道的成员人数。
* @params channelIds: 指定频道名列表。(类型:array)
*/
client.getChannelMemberCount(['123456789'])
.then((channelMemberCountResult) => { })
.catch((err) => { });
返回
Promise<ChannelMemberCountResult>
频道属性增删改查
setChannelAttributes
setChannelAttributes(channelId: string, attributes: AttributesMap, options?: ChannelAttributeOptions): Promise<void>
全量设置某指定频道的属性。
注意事项
- 你无需加入指定频道即可为该频道设置频道属性。
- 当某频道处于空频道状态(无人状态)数分钟后,该频道的频道属性将被清空。
- setLocalUserAttributes、 addOrUpdateChannelAttributes、 deleteChannelAttributesByKeys ,和 clearChannelAttributes 一并计算在内:调用频率限制为每 5 秒 10 次。
参数
参数 | 类型 | 描述 |
---|---|---|
channelId | string | 该指定频道的频道 ID。 |
attributes | AttributesMap | 频道属性列表实例。 |
options | ChannelAttributeOptions | 频道属性操作选项。 |
示例
/**
* 全量设置某指定频道的属性。
* @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>
添加或更新某指定频道的属性。
注意事项
- 如果属性已存在,该方法更新该频道的已有属性;
- 如果属性不存在,该方法增加该频道的属性。
- 你无需加入指定频道即可为该频道更新频道属性。
- 当某频道处于无人状态数分钟后,该频道的频道属性将被清空。
- setLocalUserAttributes、 addOrUpdateChannelAttributes、 deleteChannelAttributesByKeys ,和 clearChannelAttributes 一并计算在内:调用频率限制为每 5 秒 10 次。
参数
参数 | 类型 | 描述 |
---|---|---|
channelId | string | 该指定频道的 ID。 |
attributes | AttributesMap | 待增加或更新的属性列表。 |
options | ChannelAttributeOptions | 频道属性操作选项。 |
示例
/**
* 添加或更新某指定频道的属性。
* @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>
删除某指定频道的指定属性。
注意事项
- 你无需加入指定频道即可删除该频道的属性。
- 当某频道处于空频道状态(无人状态)数分钟后,该频道的频道属性将被清空。
- setLocalUserAttributes、 addOrUpdateChannelAttributes、 deleteChannelAttributesByKeys ,和 clearChannelAttributes 一并计算在内:调用频率限制为每 5 秒 10 次。
参数
参数 | 类型 | 描述 |
---|---|---|
channelId | string | 该指定频道的 ID。 |
attributeKeys | Array | 属性名列表。 |
options | ChannelAttributeOptions | 频道属性操作选项。 |
示例
/**
* 删除指定频道的指定属性。
* @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>
清空某指定频道的属性。
注意事项
- 你无需加入指定频道即可清空该频道的属性。
- setLocalUserAttributes、 addOrUpdateChannelAttributes、 deleteChannelAttributesByKeys ,和 clearChannelAttributes 一并计算在内:调用频率限制为每 5 秒 10 次。
参数
参数 | 类型 | 描述 |
---|---|---|
channelId | string | 该指定频道的 ID。 |
options | Object | 频道属性操作选项,参数详见ChannelAttributeOptions说明。 |
示例
/**
* 清空某指定频道的属性。
* @params channelId: 指定频道的 ID (类型:string)
* @params options: 频道属性操作选项 (类型:object)
*/
client.clearChannelAttributes(channelId, options)
.then(() => { })
.catch((err) => { });
返回
Promise<void>
getChannelAttributes
getChannelAttributes(channelId: string): Promise<ChannelAttributes>
查询某指定频道的全部属性。
注意事项
- 你无需加入指定频道即可查询该频道的属性。
- getChannelAttributes 和 getChannelAttributesByKeys 一并计算在内:调用频率限制为每 5 秒 10 次。
- 返回值 Promise<ChannelAttributes>
参数
参数 | 类型 | 描述 |
---|---|---|
channelId | string | 该指定频道的 ID。 |
示例
/**
* 查询某指定频道的全部属性。(无需加入指定频道即可查询该频道的属性)
* @params channelId: 指定频道的 ID。(类型:string)
*/
client.getChannelAttributes(channelId)
.then((channelAttributes) => { })
.catch((err) => { });
返回
Promise<ChannelAttributes>
getChannelAttributesByKeys
getChannelAttributesByKeys(channelId: string, keys: string[]): Promise<ChannelAttributes>
查询某指定频道指定属性名的属性。
注意事项
- 你无需加入指定频道即可查询该频道的属性。
- getChannelAttributes 和 getChannelAttributesByKeys 一并计算在内:调用频率限制为每 5 秒 10 次。
- 返回值 Promise<ChannelAttributes>
参数
参数 | 类型 | 描述 |
---|---|---|
channelId | string | 该指定频道的 ID。 |
keys | Array | 频道属性名列表。 |
示例
/**
* 查询某指定频道指定属性名的属性。(无需加入指定频道即可查询该频道的属性)
* @params channelId: 指定频道的 ID。(类型:string)
* @params keys: 频道属性名列表。(类型:array)
*/
client.getChannelAttributesByKeys(channelId, keys)
.then((channelAttributes) => { })
.catch((err) => { });
返回
Promise<ChannelAttributes>
呼叫邀请
createLocalInvitation
createLocalInvitation(calleeId: string): LocalInvitation
该方法创建一个 LocalInvitation 实例。
参数
参数 | 类型 | 描述 |
---|---|---|
calleeId | string | 被叫的 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 文档。
参数
参数 | 类型 | 描述 |
---|---|---|
eventName | string | RTM 客户端事件的名称。 |
listener | function | 事件的回调函数。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。
参数
参数 | 类型 | 描述 |
---|---|---|
token | string | 新的 Token。 |
示例
/**
* 更新当前 Token
* @params token: 新的 Token (类型:string)
*/
client.renewToken(token)
.then(() => { })
.catch((err) => { });
返回
Promise<void>
setParameters
setParameters(params: RtmParameters): void
配置 SDK 提供技术预览或特别定制功能。
参数
参数 | 类型 | 描述 |
---|---|---|
params | RtmParameters | 定制功能。 |
示例
/**
* 全量设置本地用户的属性。
* @params params: 定制功能 (类型:object)
*/
client.setParameters(params);
返回
void