RtmClient 类为 RTM 客户端相关接口,包含初始化客户端实例,销毁客户端实例,创建 Stream Channel 实例,设置监听程序等。
RtmClient createAgoraRtmClient() {
return RtmClientImpl.create();
}
创建一个 RtmClient
单实例。
注意:
- 在调用
RtmClient
类的方法之前,你需要调用该方法创建RtmClient
单实例。- 在调用
release
销毁RtmClient
单实例之前,多次调用createAgoraRtmClient
获取的是同一个RtmClient
单实例。声网不推荐多次调用createAgoraRtmClient
。
RtmClient rtmClient = createAgoraRtmClient();
RtmClient
对象:调用成功。Future<void> initialize(RtmConfig config);
初始化 RtmClient
单实例。
注意:初始化实例必须在你调用
createAgoraRtmClient
之后,使用 RTM 其他功能之前完成,以建立正确的账号级别的凭据(例如 APP ID)。
参数 | 描述 |
---|---|
config |
该 RtmClient 实例的配置信息,详见 RtmConfig 。 |
// 初始化 RtcEngine 实例
RtcEngine engine = createAgoraRtcEngine();
// 从声网控制台上获取 APP ID 并填入 "my_appId"
await _engine.initialize(RtcEngineContext(
appId: 'my_appId',
));
// 创建 RtmClient 实例
RtmClient rtmClient = createAgoraRtmClient();
final rtmConfig = RtmConfig(
// 从声网控制台上获取 APP ID 并填入 "my_appId"
appId: 'my_appId',
// 为用户或设备设置唯一标识符 userId 并填入 "my_userId"
userId: 'my_userId',
// 设置事件监听程序
eventHandler: RtmEventHandler(
onMessageEvent: (MessageEvent event) {
debugPrint('onMessageEvent');
},
onJoinResult: (String channelName, String userId,
StreamChannelErrorCode errorCode) {
debugPrint('onJoinResult');
},
onLeaveResult: (String channelName, String userId,
StreamChannelErrorCode errorCode) {
debugPrint('onLeaveResult');
},
...
),
);
// 初始化 RtmClient 实例
await _rtmClient.initialize(rtmConfig);
Future<void> release();
销毁 RtmClient
单实例以释放资源。
成功销毁后,如需调用 RtmClient
类的 API,你需要调用 createAgoraRtmClient
重新创建 RtmClient
单实例。
// 先销毁 RtmClient 实例 再销毁 RtcEngine 实例
await rtmClient.release();
await rtcEngine.release();
Future<StreamChannel> createStreamChannel(String channelName);
创建一个 StreamChannel
类型实例。
该类为 Stream Channel 频道相关接口,使用户在频道内进行创建频道,加入频道,离开频道,销毁频道,发送消息,订阅消息等操作。频道类型,频道限制等更多频道相关信息详见 Channels。
创建 StreamChannel
实例后你可以调用其他频道相关方法,详见 StreamChannel 类。
参数 | 描述 |
---|---|
channelName |
频道名称。单个 VID 下频道名唯一,即你可以在一个 VID 中使用另一个 VID 已经存在的频道名称。频道名称不能为空,可为长度在 64 字节以内的字符串。 以下为支持的字符集范围: |
StreamChannel
类型实例// 创建一个频道名为 Location 的 StreamChannel 实例
final streamChannel = await _rtmClient.createStreamChannel('Location');
StreamChannel
类型实例:调用成功。通过添加事件监听处理程序以获方法调用结果以及事件通知,包括连接状态,消息到达,Presence 状态等事件通知以及监控方法回调结果。如需要在 App 中接收消息和事件通知,在调用这些函数前必须先添加事件监听处理程序。
// 初始化 RtcEngine 实例
RtcEngine engine = createAgoraRtcEngine();
// 从声网控制台上获取 APP ID 并填入 "my_appId"
await _engine.initialize(RtcEngineContext(
appId: 'my_appId',
));
// 创建 RtmClient 实例
RtmClient rtmClient = createAgoraRtmClient();
final rtmConfig = RtmConfig(
// 从声网控制台上获取 APP ID 并填入 "my_appId"
appId: 'my_appId',
// 为用户或设备设置唯一标识符 userId 并填入 "my_userId"
userId: 'my_userId',
// 设置事件监听程序
eventHandler: RtmEventHandler(
// 消息事件通知,消息到达会触发该事件。
onMessageEvent: (MessageEvent event) {
debugPrint('onMessageEvent');
},
// Presence 事件通知,频道 presence 变更会触发该事件。
onPresenceEvent: (PresenceEvent event) {
debugPrint('onPresenceEvent');
},
// SDK 连接状态变更事件通知
onConnectionStateChange: (String channelName, RtmConnectionState state,
RtmConnectionChangeReason reason) {
debugPrint('onConnectionStateChange');
},
// 加入频道事件回调。
onJoinResult: (String channelName, String userId,
StreamChannelErrorCode errorCode) {
debugPrint('onJoinResult');
},
// 离开频道事件回调。
onLeaveResult: (String channelName, String userId,
StreamChannelErrorCode errorCode) {
debugPrint('onLeaveResult');
},
// 加入 Topic 事件回调。
onJoinTopicResult: (String channelName, String userId, String topic,
String meta, StreamChannelErrorCode errorCode) {
debugPrint('onJoinTopicResult');
},
// 离开 Topic 事件回调。
onLeaveTopicResult: (String channelName, String userId, String topic,
String meta, StreamChannelErrorCode errorCode) {
debugPrint('onLeaveTopicResult');
},
// 订阅 Topic 及订阅用户事件回调。
onTopicSubscribed: (
String channelName,
String userId,
String topic,
UserList succeedUsers,
UserList failedUsers,
StreamChannelErrorCode errorCode) {
debugPrint('onTopicSubscribed');
},
// 取消订阅 Topic 及取消订阅用户事件回调。
onTopicUnsubscribed: (
String channelName,
String userId,
String topic,
UserList succeedUsers,
UserList failedUsers,
StreamChannelErrorCode errorCode) {
debugPrint('onTopicUnsubscribed');
},
),
);
// 初始化 RtmClient 实例
await _rtmClient.initialize(rtmConfig);
final void Function(
String channelName, String userId, StreamChannelErrorCode errorCode)?
onJoinResult;
join
调用的异步回调,在加入频道时触发。
参数 | 描述 |
---|---|
channelName |
事件所在频道名称。 |
userId |
加入频道用户的 User ID。 |
errorCode |
频道错误码,详见 StreamChannelErrorCode 。 |
final void Function(
String channelName, String userId, StreamChannelErrorCode errorCode)?
onLeaveResult;
leave
调用的异步回调,在离开频道时触发。
参数 | 描述 |
---|---|
channelName |
事件所在频道名称。 |
userId |
离开频道用户的 User ID。 |
errorCode |
频道错误码,详见 StreamChannelErrorCode 。 |
final void Function(String channelName, String userId, String topic,
String meta, StreamChannelErrorCode errorCode)? onJoinTopicResult;
joinTopic
调用的异步回调,在加入 Topic 时触发。
参数 | 描述 |
---|---|
channelName |
事件所在频道名称。 |
userId |
加入 Topic 用户的 User ID。 |
topic |
Topic 名称。 |
meta |
创建 Topic 的元数据。 |
errorCode |
频道错误码,详见 StreamChannelErrorCode 。 |
final void Function(String channelName, String userId, String topic,
String meta, StreamChannelErrorCode errorCode)? onLeaveTopicResult;
leaveTopic
调用的异步回调,在离开 Topic 时触发。
参数 | 描述 |
---|---|
channelName |
事件所在频道名称。 |
userId |
离开 Topic 用户的 User ID。 |
topic |
Topic 名称。 |
meta |
创建 Topic 的元数据。 |
errorCode |
频道错误码,详见 StreamChannelErrorCode 。 |
final void Function(
String channelName,
String userId,
String topic,
UserList succeedUsers,
UserList failedUsers,
StreamChannelErrorCode errorCode)? onTopicSubscribed;
subscribeTopic
调用的异步回调,订阅 Topic 或订阅 Topic 中发布消息的用户时触发。
参数 | 描述 |
---|---|
channelName |
事件所在频道名称。 |
userId |
订阅 Topic 用户的 User ID。 |
topic |
事件所在 Topic 名称。 |
succeedUsers |
本次订阅成功的消息发布者列表,详见 UserList 。 |
failedUsers |
本次订阅订失败的消息发布者列表,详见 UserList 。 订阅失败的原因可能是超过了订阅数量限制。 |
errorCode |
频道错误码,详见 StreamChannelErrorCode 。 |
final void Function(
String channelName,
String userId,
String topic,
UserList succeedUsers,
UserList failedUsers,
StreamChannelErrorCode errorCode)? onTopicUnsubscribed;
unsubscribeTopic
调用的异步回调,取消订阅 Topic 或取消订阅 Topic 中发布消息的用户时触发。
参数 | 描述 |
---|---|
channelName |
事件所在频道名称。 |
userId |
取消订阅 Topic 用户的 User ID。 |
topic |
事件所在 Topic 名称。 |
succeedUsers |
本次取消订阅成功的消息发布者列表,详见 UserList 。 |
failedUsers |
本次取消订阅失败的消息发布者列表,详见 UserList 。取消订阅失败的原因可能是之前未订阅过该用户。 |
errorCode |
频道错误码,详见 StreamChannelErrorCode 。 |
final void Function(String channelName, RtmConnectionState state,
RtmConnectionChangeReason reason)? onConnectionStateChange;
}
SDK 连接状态发生改变时会发送该事件通知。
参数 | 描述 |
---|---|
channelName |
事件所在频道名称。 |
state |
SDK 连接状态,详见 RtmConnectionState 。 |
reason |
SDK 连接状态改变原因,详见 RtmConnectionChangeReason 。 |
RtmEventHandler(
onConnectionStateChange: (String channelName, RtmConnectionState state,
RtmConnectionChangeReason reason) {
debugPrint(
'[onConnectionStateChange] channelName: $channelName, state: $state, reason: $reason');
}
)
final void Function(PresenceEvent event)? onPresenceEvent;
当频道中有用户的 Presence 状态发生变更时,SDK 会发送该事件通知。
你可以根据实际场景监听需要的 Presence 类型:
频道相关类型,你可以在该类型中获取频道类型(channelType
)、频道名(channelName
)、用户 ID(userId
):
rtmPresenceTypeRemoteJoinChannel(0)
:远端用户加入频道。rtmPresenceTypeRemoteLeaveChannel(1)
:远端用户离开频道。rtmPresenceTypeRemoteConnectionTimeout(2)
:远端用户连接超时。Topic 相关类型,你可以在该类型中获取频道类型(channelType
)、频道名(channelName
)、用户 ID(userId
)、Topic 信息(topicInfos
)、Topic 信息数量(topicInfoNumber
):
rtmPresenceTypeRemoteJoinTopic(3)
:远端用户加入 Topic。rtmPresenceTypeRemoteLeaveTopic(4)
:远端用户离开 Topic。rtmPresenceTypeSelfJoinChannel(5)
:本地用户加入频道,收到该频道中所有 Topic 的信息。参数 | 描述 |
---|---|
event |
消息事件类型,详见 PresenceEvent 。 |
final void Function(MessageEvent event)? onMessageEvent;
在不同频道类型中,SDK 发送该事件通知的情况不同。具体如下:
参数 | 描述 |
---|---|
event |
消息事件类型,详见 MessageEvent 。 |
class RtmConfig {
@JsonKey(name: 'appId')
final String? appId;
@JsonKey(name: 'userId')
final String? userId;
@JsonKey(name: 'useStringUserId')
final bool? useStringUserId;
@JsonKey(name: 'eventHandler', ignore: true)
final RtmEventHandler? eventHandler;
factory RtmConfig.fromJson(Map<String, dynamic> json) =>
_$RtmConfigFromJson(json);
Map<String, dynamic> toJson() => _$RtmConfigToJson(this);
}
RTM 客户端配置信息。
参数 | 描述 |
---|---|
appId |
从声网控制台上获取的 APP ID。 |
userId |
用户 ID,用户或设备设置唯一的标识符。你需要维护 userId 和用户之间的映射关系,并在整个服务周期内不能改变该映射关系。如果不设置该参数,将无法连接到 RTM 服务。 |
useStringUserId |
是否使用 String 型 User ID:
|
eventHandler |
事件监听函数句柄,用以监听消息通知,Presence 通知,状态变更通知等事件通知。详见 RtmEventHandler 。 |
final rtmConfig = RtmConfig(
// 从声网控制台上获取 APP ID 并填入 "my_appId"
appId: 'my_appId',
// 为用户或设备设置唯一标识符 userId 并填入 "my_userId"
userId: 'my_userId',
// 设置事件监听程序
eventHandler: RtmEventHandler(
onMessageEvent: (MessageEvent event) {
debugPrint('onMessageEvent');
},
onJoinResult: (String channelName, String userId,
StreamChannelErrorCode errorCode) {
debugPrint('onJoinResult');
},
onLeaveResult: (String channelName, String userId,
StreamChannelErrorCode errorCode) {
debugPrint('onLeaveResult');
},
...
),
);
class MessageEvent {
@JsonKey(name: 'channelType')
final RtmChannelType? channelType;
@JsonKey(name: 'channelName')
final String? channelName;
@JsonKey(name: 'channelTopic')
final String? channelTopic;
@JsonKey(name: 'message', ignore: true)
final Uint8List? message;
@JsonKey(name: 'messageLength')
final int? messageLength;
@JsonKey(name: 'publisher')
final String? publisher;
factory MessageEvent.fromJson(Map<String, dynamic> json) =>
_$MessageEventFromJson(json);
Map<String, dynamic> toJson() => _$MessageEventToJson(this);
}
消息回调事件。
参数 | 描述 |
---|---|
channelType |
频道类型,详见 RtmChannelType 。 |
channelName |
频道名称。 |
channelTopic |
Topic 名称。 该参数仅在 channelType 为 rtmChannelTypeStream(1) 时生效。 |
message |
消息负载。 |
messageLength |
消息负载长度。 |
publisher |
发布消息用户的 User ID。 |
class PresenceEvent {
@JsonKey(name: 'channelType')
final RtmChannelType? channelType;
@JsonKey(name: 'type')
final RtmPresenceType? type;
@JsonKey(name: 'channelName')
final String? channelName;
@JsonKey(name: 'topicInfos')
final List<TopicInfo>? topicInfos;
@JsonKey(name: 'topicInfoNumber')
final int? topicInfoNumber;
@JsonKey(name: 'userId')
final String? userId;
factory PresenceEvent.fromJson(Map<String, dynamic> json) =>
_$PresenceEventFromJson(json);
Map<String, dynamic> toJson() => _$PresenceEventToJson(this);
}
Presence 回调事件。
参数 | 描述 |
---|---|
type |
Presence 类型,详见 RtmPresenceType 。 |
channelType |
频道类型,详见 RtmChannelType 。 |
channelName |
频道名称。 |
topicInfos |
Topic 信息,详见 TopicInfo。 该参数仅在 channelType 为 rtmChannelTypeStream(1) 且 type 为 rtmPresenceTypeRemoteJoinTopic(3) 、rtmPresenceTypeRemoteLeaveTopic(4) 或 rtmPresenceTypeSelfJoinChannel(5) 时生效。 |
topicInfoNumber |
Topic 信息数量。 该参数仅在 channelType 为 rtmChannelTypeStream(1) 且 type 为 rtmPresenceTypeRemoteJoinTopic(3) 、rtmPresenceTypeRemoteLeaveTopic(4) 或 rtmPresenceTypeSelfJoinChannel(5) 时生效。 |
userId |
触发 Presence 事件用户的 User ID。 |
class TopicInfo {
@JsonKey(name: 'topic')
final String? topic;
@JsonKey(name: 'numOfPublisher')
final int? numOfPublisher;
@JsonKey(name: 'publisherUserIds')
final List<String>? publisherUserIds;
@JsonKey(name: 'publisherMetas')
final List<String>? publisherMetas;
factory TopicInfo.fromJson(Map<String, dynamic> json) =>
_$TopicInfoFromJson(json);
Map<String, dynamic> toJson() => _$TopicInfoToJson(this);
}
参数 | 描述 |
---|---|
topic |
Topic 名称,同一个频道内相同的 Topic 名称属于同一个 Topic。Topic 名称可设为 16 字节以内的字符串,单个频道下 Topic 名唯一,即你可以在一个频道中使用另一个频道已经存在的 Topic 名称。 |
numOfPublisher |
向该 Topic 发布消息的用户数量。 |
publisherUserIds |
向该 Topic 发布消息的用户 ID 列表。 |
publisherMetas |
发布消息的用户的元数据。 |
enum RtmChannelType {
@JsonValue(0)
rtmChannelTypeMessage,
@JsonValue(1)
rtmChannelTypeStream,
}
RTM 频道类型。
枚举值 | 描述 |
---|---|
rtmChannelTypeMessage |
0: Message Channel。 |
rtmChannelTypeStream |
1: Stream Channel。 |
enum RtmConnectionState {
@JsonValue(1)
rtmConnectionStateDisconnected,
@JsonValue(2)
rtmConnectionStateConnecting,
@JsonValue(3)
rtmConnectionStateConnected,
@JsonValue(4)
rtmConnectionStateReconnecting,
@JsonValue(5)
rtmConnectionStateFailed,
}
SDK 连接状态。
枚举值 | 描述 |
---|---|
rtmConnectionStateDisconnected |
1: SDK 已和服务器断开连接。 |
rtmConnectionStateConnecting |
2: SDK 正在连接服务器。 |
rtmConnectionStateConnected |
3: SDK 已连上服务器。 |
rtmConnectionStateReconnecting |
4: SDK 和服务器断开连接,正在重新连接服务器。 |
rtmConnectionStateFailed |
5: SDK 无法连接服务器。 |
enum RtmConnectionChangeReason {
@JsonValue(0)
rtmConnectionChangedConnecting,
@JsonValue(1)
rtmConnectionChangedJoinSuccess,
@JsonValue(2)
rtmConnectionChangedInterrupted,
@JsonValue(3)
rtmConnectionChangedBannedByServer,
@JsonValue(4)
rtmConnectionChangedJoinFailed,
@JsonValue(5)
rtmConnectionChangedLeaveChannel,
@JsonValue(6)
rtmConnectionChangedInvalidAppId,
@JsonValue(7)
rtmConnectionChangedInvalidChannelName,
@JsonValue(8)
rtmConnectionChangedInvalidToken,
@JsonValue(9)
rtmConnectionChangedTokenExpired,
@JsonValue(10)
rtmConnectionChangedRejectedByServer,
@JsonValue(11)
rtmConnectionChangedSettingProxyServer,
@JsonValue(12)
rtmConnectionChangedRenewToken,
@JsonValue(13)
rtmConnectionChangedClientIpAddressChanged,
@JsonValue(14)
rtmConnectionChangedKeepAliveTimeout,
@JsonValue(15)
rtmConnectionChangedRejoinSuccess
@JsonValue(16)
rtmConnectionChangedLost,
@JsonValue(17)
rtmConnectionChangedEchoTest,
@JsonValue(18)
rtmConnectionChangedClientIpAddressChangedByUser,
@JsonValue(19)
rtmConnectionChangedSameUidLogin,
@JsonValue(20)
rtmConnectionChangedTooManyBroadcasters,
}
SDK 连接状态改变原因。
枚举值 | 描述 |
---|---|
rtmConnectionChangedConnecting |
0: 建立网络连接中。 |
rtmConnectionChangedJoinSuccess |
1: 成功加入频道。 |
rtmConnectionChangedInterrupted |
2: 网络连接中断。 |
rtmConnectionChangedBannedByServer |
3: 网络连接被服务器禁止。 |
rtmConnectionChangedJoinFailed |
4: SDK 连续 20 分钟无法加入频道,停止重连频道。 |
rtmConnectionChangedLeaveChannel |
5: 离开频道。 |
rtmConnectionChangedInvalidAppId |
6: 不是有效的 APP ID,无法加入频道。 |
rtmConnectionChangedInvalidChannelName |
7: 不是有效的频道名,无法加入频道。 |
rtmConnectionChangedInvalidToken |
8: Token 无效,无法加入频道。 |
rtmConnectionChangedTokenExpired |
9: Token 过期,无法加入频道。 |
rtmConnectionChangedRejectedByServer |
10: 被服务器禁止连接。 |
rtmConnectionChangedSettingProxyServer |
11: 由于设置了代理服务器,SDK 尝试重连。 |
rtmConnectionChangedRenewToken |
12: 更新 Token 引起网络连接状态改变。 |
rtmConnectionChangedClientIpAddressChanged |
13: 由于网络类型,或网络运营商的 IP 或端口发生改变,客户端 IP 地址变更,SDK 尝试重连。 |
rtmConnectionChangedKeepAliveTimeout |
14: SDK 和服务器连接保活超时,进入自动重连状态。 |
rtmConnectionChangedRejoinSuccess |
15: SDK 重连成功。 |
rtmConnectionChangedLost |
16: SDK 丢失与服务器的连接。 |
rtmConnectionChangedEchoTest |
17: 通话回声测试引起连接状态改变。 |
rtmConnectionChangedClientIpAddressChangedByUser |
18: 用户变更客户端 IP 地址,SDK 尝试重连。 |
rtmConnectionChangedSameUidLogin |
19: 使用相同的 UID 从不同的设备加入同一频道。 |
rtmConnectionChangedTooManyBroadcasters |
20: 频道内主播人数已达上限。 |
enum StreamChannelErrorCode {
@JsonValue(0)
streamChannelErrorOk,
@JsonValue(1)
streamChannelErrorExceedLimitation,
@JsonValue(2)
streamChannelErrorUserNotExist,
}
频道事件错误码。
枚举值 | 描述 |
---|---|
streamChannelErrorOk |
0: 操作成功。 |
streamChannelErrorExceedLimitation |
1: 订阅用户数量超出限制。 |
streamChannelErrorUserNotExist |
2: 所订阅用户不存在。 |
enum RtmPresenceType {
@JsonValue(0)
rtmPresenceTypeRemoteJoinChannel,
@JsonValue(1)
rtmPresenceTypeRemoteLeaveChannel,
@JsonValue(2)
rtmPresenceTypeRemoteConnectionTimeout,
@JsonValue(3)
rtmPresenceTypeRemoteJoinTopic,
@JsonValue(4)
rtmPresenceTypeRemoteLeaveTopic,
@JsonValue(5)
rtmPresenceTypeSelfJoinChannel,
}
Presence 类型。
枚举值 | 描述 |
---|---|
rtmPresenceTypeRemoteJoinChannel |
0: 远端用户加入频道。 |
rtmPresenceTypeRemoteLeaveChannel |
1: 远端用户离开频道。 |
rtmPresenceTypeRemoteConnectionTimeout |
2: 远端用户连接超时。 |
rtmPresenceTypeRemoteJoinTopic |
3: 远端用户加入 Topic。 |
rtmPresenceTypeRemoteLeaveTopic |
4: 远端用户离开 Topic。 |
rtmPresenceTypeSelfJoinChannel |
5: 本地用户加入频道,收到该频道中所有 Topic 的信息。 |