Presence

  • iOS

更新时间

Presence 提供用户在线状态查询、频道成员查询,以及临时状态管理和变更通知能力。通过 Presence,你可以获取以下信息:

  • 查询当前 App ID 下指定用户的 RTM 在线状态
  • 用户加入或离开指定频道的实时事件通知
  • 自定义临时用户状态及其变更实时事件通知
  • 查询指定用户加入或订阅了哪些频道
  • 查询指定频道有哪些用户加入及其用户临时状态数据

信息

Presence 的频道相关能力适用于 Message Channel 和 Stream Channel。

getUserOnlineStatus

接口描述

查询当前 App ID 下指定用户是否存在有效的 RTM 登录连接。每次查询一个 User ID,支持查询自己;查询方和目标用户均无需加入或订阅频道。

接口方法

Objective-C
[[rtm getPresence] getUserOnlineStatus:userId completion:completionBlock];

上面展示的是 AgoraRtmPresence.getUserOnlineStatus:completion: 的调用形式。

参数类型是否必填默认值描述
userIdNSString *必填-目标用户的精确 User ID,须符合 RTM User ID 规则。查询自己时也须传入完整 User ID,空字符串不代表自己。
completionAgoraRtmGetUserOnlineStatusBlock接收结果时提供-成功时返回 AgoraRtmUserOnlineStatus 且无错误;失败时返回错误信息。
表格内容超出当前宽度,可横向滚动查看更多列。

注意事项

  • 调用方须具有可用的 MESSAGE service,且 MESSAGE session 已连接。该查询不依赖 Presence 服务开关或 Sync Database 就绪。
  • 结果是服务端响应时刻的状态快照。异常断网后,服务端需要经过失联检测窗口才能判定用户离线。该接口不提供最后在线时间或在线状态变更订阅。
  • logout 会取消在途请求;release 会清理请求资源,不保证客户端释放后仍会回调。重复或晚到的响应不会使同一请求重复完成。

基本用法

以下示例假设客户端已初始化、登录成功且 session 已连接。

Objective-C
[[rtm getPresence] getUserOnlineStatus:@"targetUserId"
    completion:^(AgoraRtmUserOnlineStatus *status, AgoraRtmErrorInfo *errorInfo) {
        if (errorInfo != nil) {
            NSLog(@"Query failed: %@", errorInfo);
            return;
        }
        if (status == nil) {
            NSLog(@"No usable result");
            return;
        }
        if (status.online) {
            NSLog(@"%@ is online", status.userId);
        } else {
            NSLog(@"%@ is offline or does not exist", status.userId);
        }
    }];

使用说明见查询用户在线状态。

错误码

数值名称触发条件
-10006AgoraRtmErrorInvalidUserIduserId 为 nil、空字符串或非法 UID。
-10025AgoraRtmErrorNotConnected调用方 session 未连接。
-10022AgoraRtmErrorServiceNotSupport私有配置的 service 未包含 MESSAGE。
-10021AgoraRtmErrorOperationRateExceedLimitation本接口调用频率超过限制。默认每个 RtmClient 实例内独立计数,限额为 20 次/秒,不与其他 API 共用配额。
-13012AgoraRtmErrorPresenceOperationTimeout5 秒内未收到有效响应,SDK 不做超时重试。
-13013AgoraRtmErrorPresenceOperationFailed响应条目数不是 1,或返回的 UID 与请求不匹配。
-13015AgoraRtmErrorPresencePendingRequestCancelledlogout 取消在途请求。
表格内容超出当前宽度,可横向滚动查看更多列。

AgoraRtmUserOnlineStatus

以下字段仅在 completion 回调成功时有效。调用失败时应检查 errorInfo,不能据此判定目标用户离线。

属性类型描述
userIdNSString *被查询的 UID。
onlineBOOLtrue:存在有效的 RTM 登录连接;false:用户离线或不存在。
表格内容超出当前宽度,可横向滚动查看更多列。

AgoraRtmGetUserOnlineStatusBlock

getUserOnlineStatus 的完成回调。成功时返回非 nil 的 AgoraRtmUserOnlineStatus,错误信息为 nil;失败时返回错误信息,没有可用结果。读取 online 前先检查错误及结果,不得将 nil 结果当作离线结果。

whoNow

接口描述

调用 whoNow 方法,你可以实时查询指定频道的在线用户数量、在线用户列表及在线用户的临时状态等信息。

接口方法

你可以通过以下方式调用 whoNow 方法:

Objective-C
-(void) whoNow: (NSString * _Nonnull) channelName
   channelType: (AgoraRtmChannelType)channelType
       options: (AgoraRtmPresenceOptions* _Nullable)options
    completion: (AgoraRtmWhoNowBlock _Nullable)completionBlock;
参数类型是否必填默认值描述
channelNameNSString必填-频道名称。
channelTypeAgoraRtmChannelType必填-频道类型。详见 AgoraRtmChannelType。
optionsAgoraRtmPresenceOptions选填-查询附加选项。
completionAgoraRtmWhoNowBlock选填-

调用结果回调:

  • 调用成功:在 response 参数中返回 AgoraRtmWhoNowResponse 数据,在 errorInfo 参数中返回 nil。
  • 调用失败:在 response 参数中返回 nil,在 errorInfo 参数中返回错误信息。
表格内容超出当前宽度,可横向滚动查看更多列。

AgoraRtmPresenceOptions 数据类型包含以下属性:

属性类型是否必填默认值描述
includeUserIdBOOL选填true返回结果中是否包含在线成员的用户 ID。
includeStateBOOL选填false返回结果中是否包含在线用户的临时状态数据。
pageNSString必填-页码书签。你可以在返回值中查看是否还有下一页。
表格内容超出当前宽度,可横向滚动查看更多列。

AgoraRtmWhoNowResponse 数据类型包含以下属性:

属性类型描述
totalOccupancyintuserStateList 列表长度。当 AgoraRtmPresenceOptions 中的 includeUserId 和 includeState 属性都设置为 false 时,此值表示频道当前总在线人数。
userStateListNSArray<AgoraRtmUserState *>频道在线用户及其临时状态信息列表。
nextPageNSString

下一页书签。通过该属性可以确认是否有下一页:

  • 值为空表示没有下一页。
  • 值不为空表示有下一页。你可以将该值填写在 whoNow 的 page 属性中,从而查询下一页结果。
表格内容超出当前宽度,可横向滚动查看更多列。

AgoraRtmUserState 数据类型包含以下属性:

属性类型描述
userIdNSString用户 ID。
statesNSDictionary频道在线用户及其临时状态信息列表。
表格内容超出当前宽度,可横向滚动查看更多列。

接口方法

Objective-C
AgoraRtmPresenceOptions* presence_opt = [[AgoraRtmPresence alloc] init];
presence_opt.includeState = false;
presence_opt.includeUserId = false;

[[rtm getPresence] whoNow:@"your_channel" channelType:AgoraRtmChannelTypeMessage options:presence_opt completion:^(AgoraRtmWhoNowResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"whoNow success!!");
        int user_count = response.totalOccupancy;
    } else {
        NSLog(@"whoNow failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

whereNow

接口描述

在数据统计、App 调试等场景中,你可能需要了解指定用户订阅或加入的所有频道。调用 whereNow 方法,你可以实时获取指定用户所在频道的列表。

接口方法

你可以通过以下方式调用 whereNow 方法:

Objective-C
-(void) whereNow: (NSString * _Nonnull) userId
      completion: (AgoraRtmWhereNowBlock _Nullable)completionBlock;
参数类型是否必填默认值描述
userIdNSString必填-用户 ID。
completionAgoraRtmWhereNowBlock选填-

调用结果回调:

  • 调用成功:在 response 参数中返回 AgoraRtmWhereNowResponse 数据,在 errorInfo 参数中返回 nil。
  • 调用失败:在 response 参数中返回 nil,在 errorInfo 参数中返回错误信息。
表格内容超出当前宽度,可横向滚动查看更多列。

AgoraRtmWhereNowResponse 数据类型包含以下属性:

属性类型描述
totalChannelint用户所在频道个数。
channelsNSArray<AgoraRtmChannelInfo *>用户所在频道信息类表,其中包含频道名和频道类型。
表格内容超出当前宽度,可横向滚动查看更多列。

AgoraRtmChannelInfo 数据类型包含以下属性:

属性类型描述
channelNameNSString频道名称。
channelTypeAgoraRtmChannelType频道类型。详见 AgoraRtmChannelType。
表格内容超出当前宽度,可横向滚动查看更多列。

基本用法

Objective-C
[[rtm getPresence] whereNow:@"userId" completion:^(AgoraRtmWhereNowResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"whereNow success!!");
        int channel_count = response.totalChannel;
        NSArray<AgoraRtmChannelInfo *> * channels = response.channels;
    } else {
        NSLog(@"whereNow failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

setState

接口描述

为满足不同业务场景对用户状态的设置需求,RTM 提供 setState 方法自定义临时用户状态。用户可以为自己添加分数、游戏状态、位置、心情、连麦状态等自定义状态。

设置成功后,只要用户保持订阅频道并一直在线,自定义状态就会在频道中持续存在。setState 方法设置的是临时用户状态,当用户离开频道或断开与 RTM 的连接时,状态会消失。如果需要在重新加入频道或者重新连接时恢复用户状态,你需要实时在本地缓存该数据。如果你希望永久保存用户状态数据,声网推荐改用 Storage 功能的 setUserMetadata 方法。

如果用户修改了临时用户状态,RTM 会实时触发 AgoraRtmPresenceEventTypeRemoteStateChanged 类型的 didReceivePresenceEvent 事件通知。你可以通过订阅频道并配置对应属性来接收该事件。

接口方法

你可以通过以下方式调用 setState 方法:

Objective-C
-(void) setState: (NSString * _Nonnull) channelName
     channelType: (AgoraRtmChannelType)channelType
           items: (NSArray<AgoraRtmStateItem *> * _Nonnull) items
      completion: (AgoraRtmOperationBlock _Nullable)completionBlock;
参数类型是否必填默认值描述
channelNameNSString必填-频道名称
channelTypeAgoraRtmChannelType必填-频道类型。详见 AgoraRtmChannelType。
itemsNSDictionary必填-用户状态,类型为 StateItem 数组。
completionAgoraRtmOperationBlock选填-

调用结果回调:

  • 调用成功:在 response 参数中返回 AgoraRtmCommonResponse 数据,在 errorInfo 参数中返回 nil。
  • 调用失败:在 response 参数中返回 nil,在 errorInfo 参数中返回错误信息。
表格内容超出当前宽度,可横向滚动查看更多列。

接口方法

Objective-C
NSDictionary *states = @{@"key1": @"value1", @"key2": @"value2"};

[[rtm getPresence] setState:@"your_channel" channelType:AgoraRtmChannelTypeMessage items:states completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"setState success!!");
    } else {
        NSLog(@"setState failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

getState

接口描述

如需获取指定频道中指定用户的临时用户状态,你可以调用 getState 方法。

接口方法

你可以通过以下方式调用 getState 方法:

Objective-C
-(void) getState: (NSString * _Nonnull) channelName
     channelType: (AgoraRtmChannelType)channelType
          userId: (NSString * _Nonnull) userId
      completion: (AgoraRtmPresenceGetStateBlock _Nullable)completionBlock;
参数类型是否必填默认值描述
channelNameNSString必填-频道名称。
channelTypeAgoraRtmChannelType必填-频道类型。详见 AgoraRtmChannelType。
userIdNSString必填-用户 ID。
completionAgoraRtmPresenceGetStateBlock选填-

调用结果回调:

  • 调用成功:在 response 参数中返回 AgoraRtmPresenceGetStateResponse 数据,在 errorInfo 参数中返回 nil。
  • 调用失败:在 response 参数中返回 nil,在 errorInfo 参数中返回错误信息。
表格内容超出当前宽度,可横向滚动查看更多列。

AgoraRtmPresenceGetStateResponse 数据类型包含以下属性:

属性类型描述
stateAgoraRtmUserState频道在线用户及其临时状态信息列表。
表格内容超出当前宽度,可横向滚动查看更多列。

AgoraRtmUserState 数据类型包含以下属性:

属性类型描述
userIdNSString用户 ID。
statesNSDictionary频道在线用户及其临时状态信息列表。
表格内容超出当前宽度,可横向滚动查看更多列。

基本用法

Objective-C
[[rtm getPresence] getState:@"your_channel" channelType:AgoraRtmChannelTypeMessage userId:@"userid" completion:^(AgoraRtmPresenceGetStateResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"getState success!!");
        AgoraRtmUserState* state = response.state;
    } else {
        NSLog(@"getState failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

removeState

接口描述

当不再需要某个临时用户状态时,你可以调用 removeState 方法删除自己的一个或多个临时状态。成功删除用户状态后,订阅该频道且开启 Presence 事件监听的用户会收到 AgoraRtmPresenceEventTypeRemoteStateChanged 类型的 didReceivePresenceEvent 事件通知,详见事件监听。

接口方法

你可以通过以下方式调用 removeState 方法:

Objective-C
-(void) removeState:(NSString * _Nonnull)channelName
        channelType:(AgoraRtmChannelType)channelType
               keys:(NSArray<NSString *> * _Nonnull)keys
         completion:(AgoraRtmOperationBlock _Nullable)completionBlock
参数类型是否必填默认值描述
channelNameNSString必填-频道名称
channelTypeAgoraRtmChannelType必填-频道类型。详见 AgoraRtmChannelType。
keysNSArray<NSString *>必填-需要删除状态的 key 列表。如果不填写,则删除全部状态。
completionAgoraRtmOperationBlock选填-

调用结果回调:

  • 调用成功:在 response 参数中返回 AgoraRtmCommonResponse 数据,在 errorInfo 参数中返回 nil。
  • 调用失败:在 response 参数中返回 nil,在 errorInfo 参数中返回错误信息。
表格内容超出当前宽度,可横向滚动查看更多列。

基本用法

Objective-C
NSArray<NSString*>* keys = @[@"key1", @"key2"];
[[rtm getPresence] removeState:@"your_channel" channelType:AgoraRtmChannelTypeMessage keys:keys completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"removeState success!!");
    } else {
        NSLog(@"removeState failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];