Add an event listener

To receive message and event notifications when you subscribe to or join channels, you add an event listener. An event listener is triggered by the SDK to inform the client about Signaling events and state changes. The listener enables you to respond to events like successful connection to Signaling, token expiration, received messages, and other presence, storage, and lock events.

Prerequisites

Ensure that you have integrated the Signaling SDK in your project and implemented the framework functionality from the SDK quickstart page.

Implement event listeners

This section shows how to use the Signaling SDK to implement event listeners.

Add an event listener

Signaling uses RtmListener to process messages and event notifications. Each message and event notification has a corresponding event handler, where you implement your own processing logic. Refer to the following code to create and use an instance of RtmListener:

// Define the Event Listener
@interface RtmListener : NSObject <AgoraRtmClientDelegate>

@end

@implementation RtmListener

// Triggered when messages are received from remote users
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveMessageEvent:(AgoraRtmMessageEvent *)event {
    NSString* channel = event.channelName;
    AgoraRtmChannelType channel_type = event.channelType;
    if (channel_type == AgoraRtmChannelTypeStream) {
        NSString* topic = event.channelTopic; // if message from stream channel, user can get topic name
    }

    if (event.message.rawData != nil) {
        NSData* message =event.message.rawData; // get binary message
    } else {
        NSString* message = event.message.stringData; // get string message
    }
    NSString* publisher = event.publisher;

}

// Triggered when the channel lock info changes
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveLockEvent:(AgoraRtmLockEvent *)event {
    NSString* channel = event.channelName;
    AgoraRtmChannelType channel_type = event.channelType;
    AgoraRtmLockEventType event_type = event.eventType;
    if (event.lockDetailList != nil) {
        NSArray<AgoraRtmLockDetail *> *lock_details = event.lockDetailList; //get detail lock info

    }
}

// Triggered when the presence info changes
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceivePresenceEvent:(AgoraRtmPresenceEvent *)event {
    NSString* channel = event.channelName;
    AgoraRtmChannelType channel_type = event.channelType;
    AgoraRtmPresenceEventType event_type = event.type;
    NSString* publisher = event.publisher;
    if (event_type  == AgoraRtmPresenceEventTypeInterval) {
        AgoraRtmPresenceIntervalInfo* interval = event.interval;
    }else if (event_type == AgoraRtmPresenceEventTypeSnapshot) {
        NSArray<AgoraRtmUserState *> * snapshot = event.snapshot;
    } else {
        NSArray<AgoraRtmStateItem *> *states = event.states;
    }
}

// Triggered when the subscribed storage info changes
-(void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveStorageEvent:(AgoraRtmStorageEvent *)event {
    AgoraRtmStorageType storage_type = event.storageType;
    if (storage_type == AgoraRtmStorageTypeChannel) {
        NSString* channel = event.target;
        AgoraRtmChannelType channel_type = event.channelType;
    } else {
        NSString* user = event.target;
    }
    AgoraRtmMetadata* data = event.data;
}

// Triggered when the token is about to expire
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit tokenPrivilegeWillExpire:(NSString *)channel {
    if (channel != nil) {
        // Renew specific stream channel token
    } else {
        // Renew rtm client token
    }
}

// Triggered when the connection state changes
- (void)rtmKit:(AgoraRtmClientKit *)kit channel:(NSString *)channelName connectionChangedToState:(AgoraRtmClientConnectionState)state reason:(AgoraRtmClientConnectionChangeReason)reason {
    if (channelName != nil) {
        NSLog(@"stream channel connection changed now state is %d change reason is %d",state, reason);
    } else {
        NSLog(@"rtm client connection changed now state is %d change reason is %d",state, reason);
    }
}

// Triggered when the link state changes
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveLinkStateEvent:(AgoraRtmLinkStateEvent *)event {
    if (event.serviceType == AgoraRtmServiceTypeStream) {
        // receive stream channel link event
    } else {
        // receive message link event
    }
}
@end

AgoraRtmClientConfig* rtm_cfg = [[AgoraRtmClientConfig alloc] initWithAppId:@"your_appid" userId:@"your_userid"];

// Add the event listener
RtmListener* handler =  [[RtmListener alloc] init];
NSError* initError = nil;
AgoraRtmClientKit* rtm = [[AgoraRtmClientKit alloc] initWithConfig:rtm_cfg delegate:handler error:&initError];
Copy

Remove event listeners

To avoid performance degradation caused by memory leaks, errors, and exceptions, best practice is to unregister an event handler when you no longer need to use it. For example, if you don't want to use the -(void) rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveLockEvent:(AgoraRtmLockEvent *) event, delete the definition of the function.

Signaling events

Signaling offers the following notification callbacks:

Event Listener	Description
`didReceiveMessageEvent`	Receive message notifications from all the message channels you have subscribed to, or topic message notifications subscribed to from all the stream channels you have joined. The event payload data includes channel name, channel type, topic name, event sender, message payload data type, and other information.
`didReceivePresenceEvent`	Receive online status event notifications from remote users in all the message channels you have subscribed to and stream channels you have joined. The event payload data includes channel name, channel type, event type, event sender, user temporary status data, and other information.
`didReceiveTopicEvent`	Receive notifications of topic change events in all the stream channels you have joined. The event payload data includes information such as channel name, event type, topic name, and event sender.
`didReceiveStorageEvent`	Receive all channel metadata event notifications in all message channels you have subscribed to and stream channels you have joined, as well as user metadata event notifications from all subscribed users. The event payload data includes information such as channel name, channel type, event type, and specific metadata.
`didReceiveLockEvent`	Receive all lock event notifications in all the message channels you have subscribed to and stream channels you have joined. The event payload data contains information such as channel name, channel type, event type, and lock details.
`didReceiveLinkStateEvent`	Receive event notifications for client network connection status changes, including the connection status before and after the change, service type, operation type that caused the change, reason for the change, channel list, and other information.
`tokenPrivilegeWillExpire`	Receive event notifications that the client token is about to expire.
`connectionChangedToState`	(Deprecated) Receive event notifications of client network connection status changes, including channel name, connection status, and reason for change.

For details on the parameters passed in by each event, refer to Event listeners in the API reference.

Prerequisites​

Implement event listeners​

Add an event listener​

Remove event listeners​

Signaling events​

Prerequisites

Implement event listeners

Add an event listener

Remove event listeners

Signaling events