Monitoring Chatroom Events

The chatroom service provides client apps with three types of event delegation protocols: Chatroom Status Delegate, Chatroom Member Change Delegate, and Chatroom Event Notification Delegate.

Through these delegates provided by the IMLib SDK, you can obtain the following information from the RC server: chatroom destruction status, user join/leave status in current and other clients, member entry/exit event notifications in chatrooms, as well as information related to member muting and banning in chatrooms.

Delegation Protocol	Name	Description
[RCChatRoomStatusDelegate]	Chatroom Status Delegate	Receives events when users join/leave chatrooms on the current client and chatroom destruction status information.
RCChatRoomMemberDelegate	Chatroom Member Change Delegate	Receives information about users joining/leaving the current chatroom.
ChatRoomNotifyEventDelegate	Chatroom Event Notification Delegate	Receives information about member muting/banning in the current chatroom; receives information about the current user joining/leaving chatrooms on other devices.

Monitoring Chatroom Status

You can call the setChatRoomStatusDelegate or addChatRoomStatusDelegate method of RCChatRoomClient to add an [RCChatRoomStatusDelegate] delegate to monitor events when the current user joins/leaves chatrooms and the destruction status of joined chatrooms.

Setting Chatroom Status Delegate

[[RCChatRoomClient sharedChatRoomClient] setChatRoomStatusDelegate:self];

Starting from version 5.2.5, IMLib SDK supports adding multiple delegates. The method to add a delegate is as follows:

[[RCChatRoomClient sharedChatRoomClient] addChatRoomStatusDelegate:self];

Removing Chatroom Status Delegate

Starting from version 5.2.5, IMLib SDK supports removing delegates. The method to remove a delegate is as follows:

[[RCChatRoomClient sharedChatRoomClient] removeChatRoomStatusDelegate:self];

Chatroom Status Event Callback Methods

Below lists the events and delegate methods provided by the RCChatRoomStatusDelegate protocol.

@protocol RCChatRoomStatusDelegate <NSObject>

/*!
 Callback when starting to join a chatroom

 - Parameter chatroomId: Chatroom ID
 */
- (void)onChatRoomJoining:(NSString *)chatroomId;

/*!
 Callback when successfully joining a chatroom

 - Parameter chatroomId: Chatroom ID
 - Parameter response: Information returned upon successful join
 - Since: 5.6.3
 */
- (void)onChatRoomJoined:(NSString *)chatroomId response:(RCJoinChatRoomResponse *)response;

/*!
 Callback when successfully joining a chatroom

 - Parameter chatroomId: Chatroom ID
 */
- (void)onChatRoomJoined:(NSString *)chatroomId __deprecated_msg("Use [RCChatRoomStatusDelegate onChatRoomJoined:response:] instead");

/*!
 Callback when failing to join a chatroom

 - Parameter chatroomId: Chatroom ID
 - Parameter errorCode:  Error code for join failure

  If the error code is KICKED_FROM_CHATROOM or RC_CHATROOM_NOT_EXIST, the SDK will not automatically rejoin the chatroom. The app needs to handle this according to its own logic.
 */
- (void)onChatRoomJoinFailed:(NSString *)chatroomId errorCode:(RCErrorCode)errorCode;

/*!
 Callback when successfully joining a chatroom but the chatroom has been reset. After receiving this callback, the onChatRoomJoined: callback will also be received.

 - Parameter chatroomId: Chatroom ID
 */
- (void)onChatRoomReset:(NSString *)chatroomId;

/*!
 Callback when successfully leaving a chatroom

 - Parameter chatroomId: Chatroom ID
 */
- (void)onChatRoomQuited:(NSString *)chatroomId;

/*!
 Callback when a chatroom is destroyed. This callback is only received when the user is online and the room is destroyed.

 - Parameter chatroomId: Chatroom ID
 - Parameter type: Reason for chatroom destruction

 */
- (void)onChatRoomDestroyed:(NSString *)chatroomId type:(RCChatRoomDestroyType)type;

@end

Monitoring Chatroom Member Changes

tip

IMLib SDK has supported monitoring chatroom member changes since version 5.1.4.

The IMLib SDK provides the RCChatRoomMemberDelegate protocol in RCChatRoomClient, allowing the current client to monitor join/leave behaviors of other members in the chatroom.

Enabling the Service

You can enable this feature in the Service Configuration page of the IM service in the RC Console under Chatroom > Chatroom Member Change Monitoring. After enabling, when users join/leave a chatroom, the system will send callback notifications to other members in the chatroom via messages, which will increase message volume.

Setting Chatroom Member Change Delegate

Starting from version 5.6.7, IMLib SDK has added a new delegate method that returns an RCChatRoomMemberActionModel object, which includes the current chatroom member count.

Sample Code

[RCChatRoomClient sharedChatRoomClient].memberDelegate = self;

#pragma mark - RCChatRoomMemberDelegate

- (void)memberDidChange:(NSArray<RCChatRoomMemberAction *> *)members inRoom:(NSString *)roomId {
    // Handle the member change with the array of RCChatRoomMemberAction objects and the roomId
}
// Since: 5.6.7
- (void)memberDidChange:(RCChatRoomMemberActionModel *)actionModel {

}

/**
 - Since: 5.6.7
 */
- (void)memberDidChange:(RCChatRoomMemberActionModel *)actionModel {
    // Handle the member change with the RCChatRoomMemberActionModel object
    NSString *roomId = actionModel.roomId;
    NSArray<RCChatRoomMemberAction *> *chatRoomMemberActions = actionModel.chatRoomMemberActions;
    NSUInteger memberCount = actionModel.memberCount;

    for (RCChatRoomMemberAction *action in chatRoomMemberActions) {
        // Access the properties of RCChatRoomMemberAction object
        NSString *memberId = action.memberId;
        RCChatRoomMemberActionType actionType = action.action;

        if (actionType == RCChatRoomMemberActionType_Join) {
            NSLog(@"Action Type: Join");
        } else if (actionType == RCChatRoomMemberActionType_Quit) {
            NSLog(@"Action Type: Leave");
        }
    }
}

When other users join or leave a chatroom, the SDK will trigger both memberDidChange methods simultaneously, with callbacks occurring in a child thread. The RCChatRoomMemberAction list contains information about members who have joined or left the chatroom. The RCChatRoomMemberActionModel additionally encapsulates the current chatroom member count (referring to users who have joined but not left). It is recommended to use the delegate method that returns the RCChatRoomMemberActionModel object.

If the current user disconnects from the chatroom due to network issues, they will not be able to monitor join/leave behaviors of other members during the disconnection period.

Monitoring Chatroom Event Notifications

tip

IMLib SDK has supported monitoring chatroom event notifications since version 5.4.5.

Setting Chatroom Event Notification Delegate

Sample Code

[[RCChatRoomClient sharedChatRoomClient] addChatRoomNotifyEventDelegate:self];

Method Description

To receive information from the RC server about member muting/banning in the current chatroom, as well as information about the current user joining/leaving chatrooms on other devices, you can add a RCChatRoomNotifyEventDelegate delegate through the addChatRoomNotifyEventDelegate method of RCChatRoomClient.

Delegate Method	Trigger Condition	Description
chatRoomNotifyMultiLoginSync:(RCChatRoomSyncEvent *)event;	When a user joins/leaves chatrooms on other clients in a multi-device login scenario	Receives events about the current user joining/leaving chatrooms on this client
chatRoomNotifyBlock:(RCChatRoomMemberBlockEvent *)event;	When muting/unmuting events occur in the user's chatroom	Whether notifications are received depends on whether needNotify was set to true when calling the server-side mute/unmute APIs
chatRoomNotifyBan:(RCChatRoomMemberBanEvent *)event;	When user banning/unbanning events occur in the user's chatroom	Whether notifications are received depends on whether needNotify was set to true when calling the server-side ban/unban APIs

Remove Chatroom Event Notification Delegate

[[RCChatRoomClient sharedChatRoomClient] removeChatRoomNotifyEventDelegate:self];


### Multi-Device Login Event Notification

When a user joins/leaves chatrooms on other clients in a multi-device login scenario, the `chatRoomNotifyMultiLoginSync:(RCChatRoomSyncEvent *)event` method is triggered.

| Trigger Scenario | Notification Scope | Description |
|-----------------|------------------|-------------|
| User joins a chatroom on one device in multi-device login | The joining user | When the user joins a chatroom on one device, online devices will receive notifications while offline devices won't. Returns data including: chatroom ID and join time. |
| User leaves a chatroom on one device in multi-device login | The leaving user | When the user leaves a chatroom on one device, online devices will receive notifications while offline devices won't. Returns data including: chatroom ID and leave time. |
| User in multi-device login gets kicked from a previous chatroom after joining a new one | The current user and all members of the kicked chatroom | No notification if **Single User Joins Multiple Chatrooms** is enabled in Console. Returns data including: chatroom ID and kick time. |

`RCChatRoomSyncEvent` is defined as:

```objectivec
@interface RCChatRoomSyncEvent : NSObject
/*!
 Chatroom ID
 */
@property (nonatomic, copy) NSString *chatroomId;

/**
 Sync notification status
 */
@property (nonatomic, assign) RCChatRoomSyncStatus status;

/**
 For status=0 cases, distinguishes leave types:
 1: Voluntary leave
 2: Kicked due to multi-device login
 */
@property (nonatomic, assign) NSInteger reason;

/**
 Sync notification timestamp
 User join/leave/kick time (millisecond timestamp)
 */
@property (nonatomic, assign) long long time;

/**
 Additional information
 */
@property (nonatomic, copy, nullable) NSString *extra;

@end


### Ban-Related Event Notifications

When user banning/unbanning events occur in the user's chatroom and `needNotify` is set to `true` in the relevant Server API calls, the `chatRoomNotifyBlock:(RCChatRoomMemberBlockEvent *)event` method is triggered.

| Trigger Scenario | Notification Scope | Description |
|-----------------|------------------|-------------|
| [Ban Chatroom User][doc-page-Ban Chatroom User] | All chatroom members | Returns data including: chatroom ID, banned user ID list, ban time and duration, additional info. |
| [Unban Chatroom User][doc-page-Unban Chatroom User] | The unbanned user | Returns data including: chatroom ID, current user ID, additional info. |

`RCChatRoomMemberBlockEvent` is defined as:

```objectivec
@interface RCChatRoomMemberBlockEvent : NSObject
/*!
 Chatroom ID
 */
@property (nonatomic, copy) NSString *chatroomId;

/**
 Ban type: 0=unban, 1=ban
 */
@property (nonatomic, assign) RCChatRoomMemberOperateType operateType;

/**
 Total ban duration (milliseconds) when banning, max 43200 mins (1 month), min 1 min
 */
@property (nonatomic, assign) NSInteger durationTime;

/**
 Operation time (millisecond timestamp)
 */
@property (nonatomic, assign) long long operateTime;

/**
 Banned user ID list; current user ID when unbanning
 */
@property (nonatomic, copy) NSArray<NSString *> *userIdList;

/**
 Additional information
 */
@property (nonatomic, copy, nullable) NSString *extra;

@end


### Mute-Related Event Notifications

When muting/unmuting events occur in the user's chatroom and `needNotify` is set to `true` in the relevant Server API calls, the `chatRoomNotifyBan:(RCChatRoomMemberBanEvent *)event` method is triggered.

| Trigger Scenario | Notification Scope | Description |
|-----------------|------------------|-------------|
| [Mute Specified Chatroom User][doc-page-Mute Specified Chatroom User] | All chatroom members | Returns data including: chatroom ID, muted user ID list, mute time and duration, additional info. |
| [Unmute Specified Chatroom User][doc-page-Unmute Specified Chatroom User] | All chatroom members | Returns data including: chatroom ID, muted user ID list, unmute time, additional info. |
| [Enable Chatroom-Wide Mute][doc-page-Enable Chatroom-Wide Mute] | All chatroom members | Returns data including: chatroom ID, mute time, additional info. |
| [Disable Chatroom-Wide Mute][doc-page-Disable Chatroom-Wide Mute] | All chatroom members | Returns data including: chatroom ID, unmute time, additional info. |
| [Add to Chatroom-Wide Mute Exceptions][doc-page-Add to Chatroom-Wide Mute Exceptions] | All chatroom members | Returns data including: chatroom ID, allowlisted user ID list, allowlist time, additional info. |
| [Remove from Chatroom-Wide Mute Exceptions][doc-page-Remove from Chatroom-Wide Mute Exceptions] | All chatroom members | Returns data including: chatroom ID, removed user ID list, removal time, additional info. |
| [Global User Mute][doc-page-Global User Mute] | Globally muted user | Returns data including: chatroom ID, mute time and duration, additional info. |
| [Cancel Global User Mute][doc-page-Cancel Global User Mute] | Globally unmuted user | Returns data including: chatroom ID, unmute time, additional info. |

`RCChatRoomMemberBanEvent` is defined as:


```objectivec
@interface RCChatRoomMemberBanEvent : NSObject
/*!
 Chatroom ID
 */
@property (nonatomic, copy) NSString *chatroomId;

/**
 Mute operation type, see enum values
 Mute/Unmute operation types:
 0: Unmute specified users in chatroom;
 1: Mute specified users in chatroom;
 2: Disable chatroom-wide mute;
 3: Enable chatroom-wide mute;
 4: Remove user from mute allowlist;
 5: Add user to mute allowlist;
 6: Remove user from global chatroom mute;
 7: Apply global chatroom mute to user
 */
@property (nonatomic, assign) RCChatRoomMemberBanType banType;

/**
 Total mute duration (for mute operations) in milliseconds, max 43200 minutes (1 month), min 1 minute
 */
@property (nonatomic, assign) NSInteger durationTime;

/**
 Operation timestamp (millisecond Unix timestamp)
 */
@property (nonatomic, assign) long long operateTime;

/**
 List of muted/unmuted user IDs
 */
@property (nonatomic, copy) NSArray<NSString *> *userIdList;

/**
 Additional information
 */
@property (nonatomic, copy, nullable) NSString *extra;

@end