macOS

The Signaling SDK API reference is divided into the following sections:

• Setup
• User authentication
• Channels
• Topics
• Messages
• Presence
• Storage
• Lock
• Enumerated types
• Troubleshooting

Setup

The API reference for the Signaling SDK documents interface descriptions, methods, basic usage, and return values of the Signaling APIs.

AgoraRtmClientConfig

Description

Use the AgoraRtmClientConfig to set additional properties for Signaling initialization. These configuration properties will take effect throughout the lifecycle of the Signaling client and affect the behavior of the Signaling client.

Method

You can create AgoraRtmClientConfig instances as follows:

__attribute__((visibility("default"))) @interface AgoraRtmClientConfig: NSObject

- (instancetype _Nullable)init NS_UNAVAILABLE;

- (instancetype _Nonnull) initWithAppId:(NSString * _Nonnull)appId
                                 userId:(NSString * _Nonnull)userId;

@property (nonatomic, assign) AgoraRtmAreaCode areaCode;
@property (nonatomic, assign)  AgoraRtmProtocolType protocolType;
@property (nonatomic, assign) unsigned int presenceTimeout;
@property (nonatomic, assign) unsigned int heartbeatInterval;
@property (nonatomic, assign) unsigned int reconnectTimeout;
@property (nonatomic, copy, nonnull) NSString *appId;
@property (nonatomic, copy, nonnull) NSString *userId;
@property (nonatomic, assign) BOOL useStringUserId;
@property (nonatomic, assign) BOOL multipath;
@property (nonatomic, assign) BOOL ispPolicyEnabled;
@property (nonatomic, copy, nullable) AgoraRtmLogConfig * logConfig;
@property (nonatomic, copy, nullable) AgoraRtmProxyConfig * proxyConfig;
@property (nonatomic, copy, nullable) AgoraRtmEncryptionConfig * encryptionConfig;
@property (nonatomic, copy, nullable) AgoraRtmPrivateConfig * privateConfig;
@end

AgoraRtmLogConfig

Use the AgoraRtmLogConfig instance to configure and store local log files named agora.log. During the debugging phase, you can greatly improve efficiency by storing and tracking the running status of the app through logs. If you encounter complex problems and need Agora technical support to assist with the investigation, you need to provide the log information. AgoraRtmLogConfig contains the following properties:

AgoraRtmProxyConfig

Use the AgoraRtmProxyConfig instance to set properties related to the client Proxy service. In some restricted network environments, you might need to use this feature.

AgoraRtmProxyConfig contains the following properties:

AgoraRtmEncryptionConfig

Use the AgoraRtmEncryptionConfig instance to set the properties required for the client-side encryption. After successfully setting encryption modes, encryption keys, and other related properties, the SDK automatically encrypts and decrypts all messages sent or all statuses set by the user on the client side.

AgoraRtmEncryptionConfig contains the following properties:

AgoraRtmPrivateConfig

Use the AgoraRtmPrivateConfig instance to set the properties required for the private deployment. AgoraRtmPrivateConfig contains the following properties:

Basic usage

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

AgoraRtmEncryptionConfig* encryptionConfig = [[AgoraRtmEncryptionConfig alloc] init];
encryptionConfig.encryptionKey = @"you_encryption_key";
encryptionConfig.encryptionMode = AgoraRtmEncryptionAES256GCM;
unsigned char bytes[32] = ;
encryptionConfig.encryptionSalt = [NSData dataWithBytes:bytes length:32];

AgoraRtmLogConfig* log_config = [[AgoraRtmLogConfig alloc] init];
log_config.level= AgoraRtmLogLevelError;
log_config.filePath= @"your_path";
log_config.fileSizeInKB = 512;

AgoraRtmProxyConfig* proxy_config = [[AgoraRtmProxyConfig alloc] initWithServer:@"your_proxy_server" port:8080 proxyType:AgoraRtmProxyTypeHttp];
proxy_config.account = @"username";
proxy_config.password = @"password";

AgoraRtmPrivateConfig* private_config = [[AgoraRtmPrivateConfig alloc] init];
private_config.accessPointHosts = @[@"your_private_server"];
private_config.serviceType = AgoraRtmServiceTypeStream | AgoraRtmServiceTypeMessage;

rtm_config.privateConfig = private_config;
rtm_config.proxyConfig = proxy_config;
rtm_config.logConfig = log_config;
rtm_config.encryptionConfig = encryptionConfig;
rtm_config.useStringUserId = true;
rtm_config.heartbeatInterval = 5;
rtm_config.protocolType = AgoraRtmProtocolTypeTcpUdp;
rtm_config.areaCode = AgoraRtmAreaCodeGLOB;
rtm_config.presenceTimeout = 300;

Create an instance

Description

Call the initWithConfig method to create and initialize the Signaling Client instance.

Method

You can create and initialize an instance as follows:

- (instancetype _Nullable) initWithConfig: (AgoraRtmClientConfig * _Nonnull)config
                                 delegate: (id <AgoraRtmClientDelegate> _Nullable)delegate;
                                    error: (NSError**)error NS_SWIFT_NAME(init(_:delegate:));

Basic usage

AgoraRtmClientConfig* rtm_cfg = [[AgoraRtmClientConfig alloc] initWithAppId:@"your_appid" userId:@"your_userid"];
NSError* initError = nil;
AgoraRtmClientKit* rtm = [[AgoraRtmClientKit alloc] initWithConfig:rtm_cfg delegate:handler error:&initError];

Return Value

• Success: Creates a Signaling client instance for subsequent calls to other Signaling APIs.
• Failure: nil.

Event Listeners

DescriptionAgoraRtmClientDelegate

Signaling event notifications.

Signaling has a total of 8 types of event notifications, as shown in the following table:

Add event listeners

You can add an event listener object through the following ways:

• Add only an event listener object during initialization.
• Add one or more event listener objects at any point during the app's lifecycle by calling the addDelegate method.

Adding During Initialization

When initializing the Signaling client instance using the initWithConfig method, you can refer to the following example code to add an event listener object:

@interface RtmListener : NSObject <AgoraRtmClientDelegate>

@end

@implementation RtmListener

 // triggered when received message from remote
-(void) rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveMessageEvent:(AgoraRtmMessageEvent *)event {}

 // triggered when channel lock info changed
-(void) rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveLockEvent:(AgoraRtmLockEvent *)event {}

 // triggered when prensence info changed
-(void) rtmKit:(AgoraRtmClientKit *)rtmKit didReceivePresenceEvent:(AgoraRtmPresenceEvent *)event {}

 // triggered when subscribed strorage changed
-(void) rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveStorageEvent:(AgoraRtmStorageEvent *)event {}

 // triggered when token will expire
-(void) rtmKit:(AgoraRtmClientKit *)rtmKit tokenPrivilegeWillExpire:(NSString *)channel {}

 // triggered when connection state changed
-(void) rtmKit:(AgoraRtmClientKit *)kit channel:(NSString *)channelName connectionChangedToState:(AgoraRtmClientConnectionState)state reason:(AgoraRtmClientConnectionChangeReason)reason {}

 // triggered when link state changed
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveLinkStateEvent:(AgoraRtmLinkStateEvent *)event {}
@end

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

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

Adding at Any Time

addDelegate At any point during the app's lifecycle, if you need to add multiple event listener objects, you can call the addDelegate method multiple times.

@interface RtmListenerEx : NSObject <AgoraRtmClientDelegate>
 // your listener code
@end

@implementation RtmListenerEx
 // your listener code
@end
RtmListenerEx* handlerEx =  [[RtmListenerEx alloc] init];

[rtm addDelegate:handlerEx];

removeDelegate If you no longer need to listen to a specific event listener object, but still need to listen to other event listener objects, you can call the removeDelegate method to remove the specified event listener object.

[rtm removeDelegate:handlerEx];

AgoraRtmMessageEvent

Message event.

AgoraRtmMessageEvent contains the following properties:

AgoraRtmMessage contains the following properties:

AgoraRtmPresenceEvent

User presence event.

AgoraRtmPresenceEvent contains the following properties:

The AgoraRtmPresenceIntervalInfo data type contains the following properties:

The AgoraRtmUserState data type contains the following properties:

AgoraRtmStateItem data type contains the following properties:

AgoraRtmTopicEvent

Topic event.

AgoraRtmTopicEvent contains the following properties:

The AgoraRtmTopicInfo data type contains the following properties:

The AgoraRtmPublisherInfo data type contains the following properties:

AgoraRtmStorageEvent

Storage event.

AgoraRtmStorageEvent contains the following properties:

AgoraRtmLockEvent

Lock event.

AgoraRtmLockEvent contains the following properties:

The AgoraRtmLockDetail data type contains the following properties:

AgoraRtmLinkStateEvent

SDK link state event. AgoraRtmLinkStateEvent data type contains the following properties:

AgoraRtmClientKit

Signaling client instance

loginByToken

Description

After creating and initializing the Signaling instance, you need to perform the loginByToken operation to log in to the Signaling service. After successful login, the client establishes a long connection with the Signaling server, and then the SDK allows the client to access Signaling resources.

Method

You can log in to the Signaling system as follows:

- (void) loginByToken: (NSString* _Nullable)token
           completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

After calling most of the APIs of the Signaling Objective-C SDK, the SDK executes a completionBlock callback, which includes response and errorInfo parameters. Based on different calling results, the SDK returns different parameter values:

• Success: Returns the corresponding data in the response parameter, and the nil in the errorInfo parameter.
• Failure: Returns nil in the response parameter, and error information in the errorInfo parameter.

The \errorInfo` of AgoraRtmErrorInfo` data type contains the error code, error reason, and API operation name for this call, as shown in the following table:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

Basic usage

[rtm loginByToken:@"token" completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"login success!!");
    } else {
        NSLog(@"login failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

logout

Description

When you no longer need to operate, you can log out of the system. This operation affects the PCU item in your billing data.

Method

You can log out as follows:

- (void) logout: (AgoraRtmOperationBlock _Nullable)completionBlock;

Basic usage

[rtm logout:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"logout success!!");
    } else {
        NSLog(@"logout failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

releaseLock

Description

Once you no longer need the Signaling service, it is best to destroy the AgoraRtmClientKit instance. Doing so protects you from the performance degradation caused by memory leaks, errors, and exceptions.

Method

You can destroy the AgoraRtmClientKit instance as follows:

- (AgoraRtmErrorCode) destroy;

Basic usage

[rtm destroy];

Return Value

The releaseLock method returns an AgoraRtmErrorCode data structure. See Error code.

User authentication

Authentication is the process of validating the identity of each user before they access a system. Agora uses digital tokens to authenticate users and their privileges.

Signaling provides 3 types of channels: message channels, user channels and stream channels. Different types of channels require different types of tokens:

• For message channels and user channels: When logging in to the Signaling system using the loginByToken method, you only need to pass the token that enables Signaling service.
• For stream channels: In addition to the Signaling token, when joining a stream channel using the joinTopic method, you also need to pass the token that enables RTC service.

The token is valid for up to 24 hours. Agora recommends that you update the token before it expires. This article describes how to update the token.

For more information on generating and using tokens, see Secure authentication with tokens.

AgoraRtmClientKit.renewToken

Description

Call the AgoraRtmClientKit.renewToken method to renew the Signaling token.

To ensure timely token updates, Agora recommends listening for the tokenPrivilegeWillExpire callback. See Event listeners for details. Once you successfully add the event listener, when the Signaling token is about to expire within 30 seconds, the SDK triggers the tokenPrivilegeWillExpire callback to notify the user about the impending token expiration.

Upon receiving this callback, you can generate a new Signaling token on the server-side and call the renewToken method to provide the SDK with the newly generated Signaling token.

Method

You can call the AgoraRtmClientKit.renewToken method as follows:

- (void) renewToken:(NSString* _Nonnull)token
         completion:(AgoraRtmOperationBlock _Nullable)completionBlock NS_SWIFT_NAME(renewToken(_:completion:));

Basic usage

[rtm renewToken:@"new token" completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"renew token success!!");
    } else {
        NSLog(@"renew token failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

AgoraRtmStreamChannel.renewToken

Description

Call the AgoraRtmStreamChannel.renewToken method to renew the RTC token.

To ensure timely token updates, Agora recommends listening for the tokenPrivilegeWillExpire callback. See Event listeners for details. Once you successfully add the event listener, when the RTC token is about to expire within 30 seconds, the SDK triggers the tokenPrivilegeWillExpire callback to notify the user about the impending token expiration.

Upon receiving this callback, you can generate a new RTC token on the server-side and call the renewToken method to provide the SDK with the newly generated RTC token.

Method

You can call the AgoraRtmStreamChannel.renewToken method as follows:

- (void)renewToken:(NSString* _Nonnull)token
        completion:(AgoraRtmOperationBlock _Nullable)completionBlock NS_SWIFT_NAME(renewToken(_:completion:));

Basic usage

[streamChannel renewToken:@"new token" completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"renew token success!!");
    } else {
        NSLog(@"renew token failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

Channels

Signaling provides a highly efficient channel management mechanism for data transmission. Any user who subscribes or joins a channel can receive messages and events transmitted within 100 milliseconds. Signaling allows clients to subscribe to hundreds or even thousands of channels. Most Signaling APIs perform actions such as sending, receiving, and encrypting based on channels.

Based on capabilities of Agora, Signaling channels are divided into two types to match different application use-cases:

• Message Channel: Follows the industry-standard Pub/Sub (publish/subscribe) mode. You can send and receive messages within the channel by subscribing to a channel, and do not need to create the channel in advance. There is no limit to the number of publishers and subscribers in a channel.

• User Channel: Point-to-point message sending and receiving based on the Pub/Sub (publish/subscribe) model. Users do not need to subscribe to the channel, they can directly specify the user ID to send messages. To receive messages, they only need to listen to didReceiveMessageEvent events.

• Stream Channel: Follows a concept similar to the observer pattern in the industry, where users need to create and join a channel before sending and receiving messages. You can create different topics in the channel, and messages are organized and managed through topics.

AgoraRtmClientKit Signaling client instance

subscribeTopic

Description

Signaling provides event notification capabilities for messages and states. By listening for callbacks, you can receive messages and events within subscribed channels. For information on how to add and set event listeners, see Event Listeners.

By calling the subscribeTopic method, the client can subscribe to a message channel and start receiving messages and event notifications within the channel. After successfully calling this method, users who subscribe to the channel and enable the presence event listener can receive a AgoraRtmPresenceEventTypeRemoteJoinChannel type of the didReceivePresenceEvent event. See Event Listeners.

Method

You can call the subscribeTopic method as follows:

- (void)subscribeWithChannel:(NSString * _Nonnull)channelName
                      option:(AgoraRtmSubscribeOptions * _Nullable)subscribeOption
                  completion:(AgoraRtmOperationBlock _Nullable)completionBlock;

AgoraRtmSubscribeOptions contains the following properties:

Basic usage

AgoraRtmSubscribeOptions* opt = [[AgoraRtmSubscribeOptions alloc] init];
opt.features = AgoraRtmSubscribeChannelFeatureMessage|AgoraRtmSubscribeChannelFeaturePresence;
[rtm subscribeWithChannel:@"you_channel" option:opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe success!!");
    } else {
        NSLog(@"subscribe failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

unsubscribeTopic

Description

If you no longer need to subscribe to a channel, you can call the unsubscribeTopic method to unsubscribe from the channel. After successfully calling this method, users who subscribe to the channel and enable event listeners can receive the AgoraRtmPresenceEventTypeRemoteLeaveChannel type of the didReceivePresenceEvent event notification. See Event Listeners.

Method

You can call the unsubscribeTopic method as follows:

- (void) unsubscribeWithChannel: (NSString* _Nonnull)channelName
                     completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

Basic usage

[rtm unsubscribeWithChannel:@"you_channel" option:opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe success!!");
    } else {
        NSLog(@"subscribe failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

initWithConfig

Description

Before using a stream channel, you need to call the initWithConfig method to create the AgoraRtmStreamChannel instance. After successfully creating the instance, you can call its relevant methods to implement functions, such as joining the channel, leaving the channel, sending messages in a topic, and subscribing to messages in a topic.

Method

You can call the initWithConfig method as follows:

- (AgoraRtmStreamChannel * _Nullable)createStreamChannel:(NSString * _Nonnull)channelName
                                                   error:(NSError**)error NS_SWIFT_NAME(createStreamChannel(_:));

Basic usage

AgoraRtmStreamChannel* stream_channel = [rtm createStreamChannel:@"your_channel"];
    if (stream_channel == nil) {
        NSLog("create stream channel failed");
    } else {
        NSLog("create stream channel success");
    };

Return Value

• Success: Returns an instance of AgoraRtmStreamChannel to use for subsequent calls to other stream channel APIs.
• Failure: nil.

AgoraRtmStreamChannel Stream channel instance

joinTopic

Description

After successfully creating a stream channel, you can call the joinTopic method to join the stream channel. Once you join the channel, you can implement channel-related functions. At this point, users who subscribe to the channel and add event listeners can receive the following event notifications:

• For the local user:
  • The AgoraRtmPresenceEventTypeSnapshot type of the didReceivePresenceEvent event.
  • The AgoraRtmTopicEventTypeSnapshot type of the didReceiveTopicEvent event.
• For remote users: The AgoraRtmPresenceEventTypeRemoteJoinChannel type of the didReceivePresenceEvent event.

Method

You can call the joinTopic method as follows:

- (void)joinWithOption: (AgoraRtmJoinChannelOption * _Nonnull)option
            completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

The AgoraRtmJoinChannelOption data type contains the following properties:

Basic usage

AgoraRtmJoinChannelOption* join_opt =  [[AgoraRtmJoinChannelOption alloc] init];
join_opt.token =  @"your_token";
join_opt.features = AgoraRtmSubscribeChannelFeaturePresence | AgoraRtmSubscribeChannelFeatureMetadata;

[stream_channel joinWithOption:join_opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"join channel success!!");
    } else {
        NSLog(@"join channel failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

leaveTopic

Description

If you no longer need to stay in a channel, you can call the leaveTopic method to leave the channel. After leaving the channel, you can no longer receive any messages, states, or event notifications from this channel. At the same time, you can no loger be the topic publisher or subscriber of all topics. If you want to restore your previous publisher role and subscribing relationship, you need to call joinTopic, joinTopic and subscribeTopic methods in order.

After successfully leaving the channel, remote users in the channel can receive the AgoraRtmPresenceEventTypeRemoteLeaveChannel type of the didReceivePresenceEvent event notification. For details, see Event Listeners.

Method

You can call the leaveTopic method as follows:

- (void)leave: (AgoraRtmOperationBlock _Nullable)completionBlock;

Basic usage

[stream_channel leave:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"leave channel success!!");
    } else {
        NSLog(@"leave channel failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

releaseLock

Description

If you no longer need a channel, you can call the releaseLock method to destroy the corresponding stream channel instance and release resources. Calling the releaseLock method does not destroy the stream channel, and it can be re-joined later by calling initWithConfig and joinTopic again.

Method

You can call the releaseLock method as follows:

- (AgoraRtmErrorCode) destroy;

Basic usage

[stream_channel destroy];
stream_channel = nil;

Return Value

The releaseLock method returns an AgoraRtmErrorCode data structure. See Error code.

Topics

Topic is a data stream management mechanism in stream channels. Users can use topics to subscribe to and distribute data streams, as well as notify events in data streams in stream channels.

AgoraRtmStreamChannel Stream channel instance

joinTopic

Description

The purpose of joining a topic is to register as one of the message publishers for the topic, so that the user can send messages in the topic. This operation does not affect whether or not the user becomes a subscriber to the topic.

After successfully joining a topic, users who subscribe to that topic and add event listeners can receive the AgoraRtmTopicEventTypeRemoteJoinTopic type of the didReceiveTopicEvent event notification. For details, see Event Listeners.

Method

You can call the joinTopic method as follows:

- (void) joinTopic:(NSString * _Nonnull)topic
            option:(AgoraRtmJoinTopicOption * _Nullable)option
        completion:(AgoraRtmOperationBlock _Nullable)completionBlock

The AgoraRtmJoinTopicOption data type contains the following properties:

Basic usage

AgoraRtmJoinTopicOption* join_topic_opt = [[AgoraRtmJoinTopicOption alloc] init];
join_topic_opt.qos = AgoraRtmMessageQosOrdered;
[stream_channel joinTopic:@"your_topic" option:join_topic_opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"join topic success!!");
    } else {
        NSLog(@"join topic failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

publishTopicMessage

Description

Use the publishTopicMessage method to send messages to a topic. Users who have subscribed to the topic and the message publisher in the channel can receive the message within 100 milliseconds. Before calling the publishTopicMessage method, users need to join the stream channel, and then register as a message publisher for that topic by calling the joinTopic method.

The messages sent by users are encrypted with TLS during transmission, and data link encryption is enabled by default and cannot be disabled. To achieve a higher level of data security, users can also enable client encryption during initialization. For details, see Setup.

Method

You can call the publishTopicMessage[1/2] and publishTopicMessage[2/2] method as follows:

 // publishTopicMessage[1/2]
- (void) publishTopicMessage:(NSString * _Nonnull)topic
                     message:(NSString * _Nonnull)message
                      option:(AgoraRtmTopicMessageOptions * _Nullable)options
                  completion:(AgoraRtmOperationBlock _Nullable)completionBlock

 // publishTopicMessage[2/2]
- (void) publishTopicMessage:(NSString * _Nonnull)topic
                        data:(NSData * _Nonnull)data
                      option:(AgoraRtmTopicMessageOptions * _Nullable)options
                  completion:(AgoraRtmOperationBlock _Nullable)completionBlock

The AgoraRtmTopicMessageOptions data type contains the following properties:

Basic usage

Example 1: Send string messages to a specified channel.

NSString* message = @"Hello Agora!";
NSString* channel = @"your_channel";
[stream_channel publishTopicMessage:@"your_topic" message:raw_message option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

Example 2: Send byte messages to a specified channel.

unsigned char byte_array[5] = {0,1,2,3,4};
NSData* raw_message = [[NSData alloc] initWithBytes:byte_array length:5];
NSString* channel = @"your_channel";
[stream_channel publishTopicMessage:@"your_topic" data:raw_message option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

leaveTopic

Description

When you no longer need to publish messages to a topic, to release resources, you can call the leaveTopic method to unregister as a message publisher for that topic. This method does not affect whether or not you subscribe to that topic or any other operations performed by other users on that topic.

After successfully calling this method, users who subscribe to the channel and enable event listeners can receive the AgoraRtmTopicEventTypeRemoteLeaveTopic type of the didReceiveTopicEvent event notification. See Event Listeners.

Method

You can call the leaveTopic method as follows:

- (void) leaveTopic: (NSString * _Nonnull)topic
         completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

Basic usage

[stream_channel leaveTopic:@"your_topic" completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"leave topic success!!");
    } else {
        NSLog(@"leave topic failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);

    }
}];

subscribeTopic

Description

After joining the channel, you can call the subscribeTopic method to subscribe to the message publisher of the topic in the channel.

subscribeTopic is an incremental method. For example, if you call this method for the first time with a subscribing list of [UserA, UserB], and then call it again with a subscribing list of [UserB, UserC], the final successful subscribing result is [UserA, UserB, UserC].

A user can subscribe to a maximum of 50 topics in each channel, and a maximum of 64 message publishers in each topic. See API usage restrictions.

Method

You can call the subscribeTopic method as follows:

- (void) subscribeTopic:(NSString * _Nonnull)topic
                 option:(AgoraRtmTopicOption * _Nullable)option
             completion:(AgoraRtmTopicSubscriptionBlock _Nullable)completionBlock

The AgoraRtmTopicOption data type contains the following properties:

The AgoraRtmTopicSubscriptionResponse data type contains the following properties:

Basic usage

Example 1: Subscribe to the specified message publisher in the topic.

AgoraRtmTopicOption* topic_opt = [[AgoraRtmTopicOption alloc] init];
topic_opt.users = @[@"user1", @"user2"];
[stream_channel subscribeTopic:@"your_topic" option:topic_opt completion:^(AgoraRtmTopicSubscriptionResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe topic success!!");
    } else {
        NSArray<NSString *> *sucees_users = response.succeedUsers;
        NSArray<NSString *> *fail_users = response.failedUsers;
        NSLog(@"subscribe topic failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

Example 2: Randomly subscribe to 64 message publishers in the topic.

[stream_channel subscribeTopic:@"your_topic" option:nil completion:^(AgoraRtmTopicSubscriptionResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe topic success!!");
    } else {
        NSLog(@"subscribe topic failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

unsubscribeTopic

Description

If you are no longer interested in a specified topic, or no longer need to subscribe to one or more message publishers in the topic, you can call the unsubscribeTopic method to unsubscribe from the topic or the specified message publishers in the topic.

Method

You can call the unsubscribeTopic method as follows:

- (void) unsubscribeTopic:(NSString * _Nonnull)topic
                   option:(AgoraRtmTopicOption * _Nullable)option
               completion:(AgoraRtmOperationBlock _Nullable)completionBlock

The AgoraRtmTopicOption data type contains the following properties:

Basic usage

Example 1: Unsubscribe the specified message publisher in the topic

AgoraRtmTopicOption* topic_opt = [[AgoraRtmTopicOption alloc] init];
topic_opt.users = @[@"user1", @"user2"];
[stream_channel unsubscribeTopic:@"your_topic" option:topic_opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe topic success!!");
    } else {
        NSLog(@"subscribe topic failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

Example 2: Randomly unsubscribe 64 message publishers from the topic.

[stream_channel unsubscribeTopic:@"your_topic" option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"subscribe topic success!!");
    } else {
        NSLog(@"subscribe topic failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

Messages

Sending and receiving messages is the most basic function of the Signaling service. Any message sent by the Signaling server can be delivered to any online subscribing user within 100 ms. Depending on your business requirements, you can send messages to one user only or broadcast messages to multiple users.

Signaling offers 3 types of channels: message channels, user channels, and stream channels. These channel types have the following differences in how messages are transmitted and methods are called:

• Message Channel: The real-time channel. Messages are transmitted through the channel, and the channel is highly scalable. Local users can call the publishTopicMessage method, set the channelType parameter to AgoraRtmChannelTypeMessage, and set the channelName parameter to the channel name to send messages in the channel. The remote users can call the subscribeTopic method to subscribe to the channel and receive messages.
• User Channel: The real-time channel. Messages are transmitted to the specified user. Local users can call the publishTopicMessage method, set the channelType parameter to AgoraRtmChannelTypeUser, and set the channelName parameter to the user ID to send messages to the specified user. The specified remote users receive messages through the didReceiveMessageEvent event notifications.
• Stream Channel: The streaming transmission channel. Messages are transmitted through the topic. Users need to join a channel first, and then join a topic. Local users can call the publishTopicMessage method to send messages in the topic, and remote users can call the subscribeTopic method to subscribe to the topic and receive messages.

This section introduces how to send and receive messages in a message channel or a user channel.

AgoraRtmClientKit Signaling client instance

publishTopicMessage

Description

You can directly call the publishTopicMessage method to send messages to all online users subscribed to this channel. Even if you do not subscribe to the channel, you can still send messages in the channel.

After successfully calling this method, the SDK triggers a didReceiveMessageEvent event notification. Users who subscribe to the channel and enabled the event listener can receive this event notification. For details, see Event Listeners.

Method

You can call the publishTopicMessage [1/2] and publishTopicMessage [2/2] methods as follows:

 // publish[1/2]
- (void) publish:(NSString* _Nonnull)channelName
         message:(NSString* _Nonnull)message
          option:(AgoraRtmPublishOptions* _Nullable)publishOption
      completion:(AgoraRtmOperationBlock _Nullable)completionBlock

 // publish[2/2]
- (void) publish:(NSString* _Nonnull)channelName
            data:(NSData* _Nonnull)data
          option:(AgoraRtmPublishOptions* _Nullable)publishOption
      completion:(AgoraRtmOperationBlock _Nullable)completionBlock

The AgoraRtmTopicMessageOptions data type contains the following properties:

Basic usage

Example 1: Send string messages to a specified channel.

NSString* message = @"Hello Agora!";
NSString* channel = @"your_channel";
[rtm publish:channel message:message option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

Example 2: Send byte messages to a specified channel.

unsigned char byte_array[5] = {0,1,2,3,4};
NSData* raw_message = [[NSData alloc] initWithBytes:byte_array length:5];
NSString* channel = @"your_channel";
[rtm publish:channel data:raw_message option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

Example 3: Send string messages to a specified user.

NSString* message = @"Hello Agora!";
NSString* user = @"Tony";

AgoraRtmPublishOptions* publish_option = [[AgoraRtmPublishOptions alloc] init];
publish_option.channelType = AgoraRtmChannelTypeUser;

[rtm publish:user message:message option:publish_option completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

Example 4: Send byte messages to a specified user.

NSData* raw_message = [[NSData alloc] initWithBytes:byte_array length:5];
NSString* user = @"Tony";

AgoraRtmPublishOptions* publish_option = [[AgoraRtmPublishOptions alloc] init];
publish_option.channelType = AgoraRtmChannelTypeUser;

[rtm publish:user data:raw_message option:publish_option completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

Receive

Signaling provides event notifications for messages, states, and event changes. By listening for callbacks, you can receive messages and events within subscribed channels. As an example, the code snippet below shows how to receive messages from the user channel.

• Adding during initialization:

    @interface RtmHandler : NSObject <AgoraRtmClientDelegate>
    @end

    @implementation RtmHandler
    // triggered when received message from remote users
    -(void) rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveMessageEvent:(AgoraRtmMessageEvent *)event {
        NSString* channel = event.channelName;
        AgoraRtmChannelType channel_type = event.channelType;
        if (channel_type == AgoraRtmChannelTypeUser) {
            // process user message
        }
    }
    @end

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

    RtmListener* handler =  [[RtmListener alloc] init];
    NSError* initError = nil;
    AgoraRtmClientKit* rtm = [[AgoraRtmClientKit alloc] initWithConfig:rtm_cfg delegate:handler error:&initError];

• Adding at any time:

    @interface RtmHandler : NSObject <AgoraRtmClientDelegate>
    @end

    @implementation RtmHandler
    // triggered when received message from remote users
    -(void) rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveMessageEvent:(AgoraRtmMessageEvent *)event {
        NSString* channel = event.channelName;
        AgoraRtmChannelType channel_type = event.channelType;
        if (channel_type == AgoraRtmChannelTypeUser) {
            // process user message
        }
    }
    @end

    RtmListener* handler =  [[RtmListener alloc] init];
    [rtm addDelegate:handler];

For information on how to add and set event listeners, see Event Listeners.

Presence

The presence feature provides the ability to monitor user online, offline, and user historical state change. With the Presence feature, you can get real-time access to the following information:

• Real-time event notification when a user joins or leaves a specified channel.
• Real-time event notification when the custom temporary user state changes.
• Query which channels a specified user has joined or subscribed to.
• Query which users have joined a specified channel and their temporary user state data.

AgoraRtmPresence Presence instance

getOnlineUsers

Description

By calling the getOnlineUsers method, you can query real-time information about the number of online users, the list of online users, and the temporary state of online users in a specified channel.

Method

You can call the getOnlineUsers method as follows:

-(void) getOnlineUsers: (NSString * _Nonnull) channelName
   channelType: (AgoraRtmChannelType)channelType
       options: (AgoraRtmGetOnlineUsersOptions* _Nullable)options
    completion: (AgoraRtmGetOnlineUsersBlock _Nullable)completionBlock;

The AgoraRtmGetOnlineUsersOptions data type contains the following properties:

The AgoraRtmGetOnlineUsersResponse data type contains the following properties:

The AgoraRtmUserState data type contains the following properties:

AgoraRtmStateItem data type contains the following properties:

Basic usage

AgoraRtmGetOnlineUsersOptions* presence_opt = [[AgoraRtmPresence alloc] init];
presence_opt.includeState = false;
presence_opt.includeUserId = false;

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

getUserChannels

Description

In use-cases such as statistic analytics and debugging, you may need to know all the channels that a specified user has subscribed to or joined. Call the getUserChannels method to get the list of channels where the specified user is in real time.

Method

You can call the getUserChannels method as follows:

-(void) getUserChannels: (NSString * _Nonnull) userId
      completion: (AgoraRtmGetUserChannelsBlock _Nullable)completionBlock;

The AgoraRtmGetUserChannelsResponse data type contains the following properties:

The AgoraRtmChannelInfo data type contains the following properties:

Basic usage

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

setState

Description

To meet different requirements in different business use-cases for setting user states, Signaling provides the setState method to customize the temporary user state. Users can add custom states such as scores, game state, location, mood, and hosting state for themselves.

After successful setup, as long as the user keeps subscribing to the channel and stays online, the custom states can persist in the channel. setState method sets the temporary user state, and the state disappears when the user leaves the channel or disconnects from Signaling. If you need to restore user states when rejoining a channel or reconnecting, you need to cache the data locally in real time. If you want to permanently save user states, Agora recommends you use the setUserMetadata method of the storage function instead.

If a user modifies the temporary user state, Signaling triggers the AgoraRtmPresenceEventTypeRemoteStateChanged type of the didReceivePresenceEvent event in real time. You can receive the event by subscribing to the channel and configuring the corresponding property.

Method

You can call the setState method as follows:

-(void) setState: (NSString * _Nonnull) channelName
     channelType: (AgoraRtmChannelType)channelType
           items: (NSArray<AgoraRtmStateItem *> * _Nonnull) items
      completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

Basic usage

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

Description

To get the temporary user state of a specified user in the channel, you can use the getState method.

Method

You can call the getState method as follows:

-(void) getState: (NSString * _Nonnull) channelName
     channelType: (AgoraRtmChannelType)channelType
          userId: (NSString * _Nonnull) userId
      completion: (AgoraRtmPresenceGetStateBlock _Nullable)completionBlock;

The AgoraRtmPresenceGetStateResponse data type contains the following properties:

The AgoraRtmUserState data type contains the following properties:

AgoraRtmStateItem data type contains the following properties:

Basic usage

[[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

Description

When a temporary user state is no longer needed, you can call the removeState method to remove one or more of your temporary states. When the user state is removed, the user who has subscribed to the channel and enabled the presence event listener receives the AgoraRtmPresenceEventTypeRemoteStateChanged type of didReceivePresenceEvent event notification. See Event Listeners.

Method

You can call the removeState method as follows:

-(void) removeState:(NSString * _Nonnull)channelName
        channelType:(AgoraRtmChannelType)channelType
               keys:(NSArray<NSString *> * _Nonnull)keys
         completion:(AgoraRtmOperationBlock _Nullable)completionBlock

Basic usage

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);
    }
}];

Storage

The storage feature provides a database mechanism that allows developers to dynamically set, store, update, and delete data such as channel metadata and user metadata.

AgoraRtmStorage Storage instance

setChannelMetadata

Description

The setChannelMetadata method sets metadata for a message channel or stream channel. A channel can only have one set of metadata, but each set of metadata can have one or more metadata items. If you call this method multiple times, the SDK retrieves the key of the metadata items in turn and apply settings according to the following rules:

• If you set metadata with different key, the SDK adds each set of metadata in sequence according to the order of the method calls.
• If you set metadata with the same key, the value of the last setting overwrites the previous one.

After successfully setting channel metadata, users who subscribe to the channel and enable event listeners can receive the AgoraRtmStorageTypeChannel type of the didReceiveStorageEvent event notification. See Event listeners.

Channel metadata also introduces the version control logic CAS (Compare And Set). This method provides two independent version control fields, and you can set one or more of them according to your actual business use-case:

• Enable version number verification for the entire set of channel metadata by setting the majorRevision property in the AgoraRtmMetadata data type.
• Enable version number verification for a single metadata item by setting the revision property in the AgoraRtmMetadataItem class.

When setting channel metadata or metadata items, you can control whether to enable version number verification by specifying the revision property:

• The default value of the revision property is -1, indicating that this method call does not perform any CAS verification. If the channel metadata or metadata item already exists, the latest value overwrites the previous one. If the channel metadata or metadata item does not exist, the SDK creates it.
• If the revision property is a positive integer, this method call performs the CAS verification. If the channel metadata or metadata item already exists, the SDK updates the corresponding value after the version number verification succeeds. If the channel metadata or metadata item does not exist, the SDK returns the error code.

Method

You can call the setChannelMetadata method as follows:

- (void) setChannelMetadata: (NSString * _Nonnull)channelName
                channelType: (AgoraRtmChannelType)channelType
                       data: (AgoraRtmMetadata* _Nonnull)data
                    options: (AgoraRtmMetadataOptions* _Nullable)options
                       lock: (NSString * _Nullable)lock
                 completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

The AgoraRtmMetadataOptions data type contains the following properties:

Basic usage

 //get metadata
AgoraRtmMetadata* metadata = [[AgoraRtmMetadata alloc] init];

 //set metadata items
AgoraRtmMetadataItem* apple = [[AgoraRtmMetadataItem alloc] init];
apple.key = @"Apple";
apple.value = @"100";
apple.revision = 174298200;
AgoraRtmMetadataItem* banana = [[AgoraRtmMetadataItem alloc] init];
banana.key = @"Banana";
banana.value = @"200";
banana.revision = 174298100;

NSArray *item_array = [NSArray arrayWithObjects:apple,banana];
metadata.items = item_array;
metadata.majorRevision = 174298100;

AgoraRtmMetadataOptions* metadata_opt = [[AgoraRtmMetadataOptions alloc] init];
metadata_opt.recordUserId = true;
metadata_opt.recordTs = true;

[[rtm getStorage] setChannelMetadata:@"channel_name" channelType:AgoraRtmChannelTypeMessage data:metadata options:metadata_opt lock:@"lockName" completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"setChannelMetadata success!!");
    } else {
        NSLog(@"setChannelMetadata failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

getChannelMetadata

Description

The getChannelMetadata method can get the metadata of the specified channel.

Method

You can call the getChannelMetadata method as follows:

- (void) getChannelMetadata: (NSString * _Nonnull)channelName
                channelType: (AgoraRtmChannelType)channelType
                 completion: (AgoraRtmGetMetadataBlock _Nullable)completionBlock;

The AgoraRtmGetMetadataResponse data type contains the following properties:

Basic usage

[[rtm getStorage] getChannelMetadata:@"channel_name" channelType:AgoraRtmChannelTypeMessage completion:^(AgoraRtmGetMetadataResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"getChannelMetadata success!!");
        AgoraRtmMetadata* data = response.data; //get storage data;
        NSArray<AgoraRtmMetadataItem *> * items = [data getMetadataItems];
        for (int i = 0; i < items.count; i++) {
            NSLog(@"key: %@ value: %@ revision: %lld", items[i].key, items[i].value, items[i].revision);
        }

    } else {
        NSLog(@"getChannelMetadata failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

removeChannelMetadata

Description

The removeChannelMetadata method can remove channel metadata or metadata items.

When removing channel metadata or metadata items, you can control whether to enable version number verification by specifying the revision property:

• The default value of the revision property is -1, indicating that this method call does not perform any CAS verification. If the channel metadata or metadata item already exists, the SDK removes it. If the channel metadata or metadata item does not exist, the SDK returns the error code.
• If the revision property is a positive integer, this method call performs the CAS verification. If the channel metadata or metadata item already exists, the SDK removes the corresponding value after the version number verification succeeds. If the channel metadata or metadata item does not exist, the SDK returns the error code.

After successfully removing channel metadata or metadata items, users who subscribe to the channel and enable event listeners can receive the AgoraRtmStorageTypeChannel type of the didReceiveStorageEvent event notification. See Event listeners.

Method

You can call the removeChannelMetadata method as follows:

- (void) removeChannelMetadata: (NSString * _Nonnull)channelName
                   channelType: (AgoraRtmChannelType)channelType
                          data: (AgoraRtmMetadata* _Nonnull)data
                       options: (AgoraRtmMetadataOptions* _Nullable)options
                          lock: (NSString * _Nullable)lock
                    completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

The AgoraRtmMetadataOptions data type contains the following properties:

Basic usage

AgoraRtmMetadata* metadata = [[AgoraRtmMetadata alloc] init];

AgoraRtmMetadataItem* apple = [[AgoraRtmMetadataItem alloc] init];
apple.key = @"Apple";
apple.revision = 174298200;

NSArray *item_array = [NSArray arrayWithObjects:apple];
metadata.items = item_array;
metadata.majorRevision = 174298100;

[[rtm getStorage] removeChannelMetadata:@"channel_name" channelType:AgoraRtmChannelTypeMessage data:metadata options:metadata_opt lock:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"removeChannelMetadata success!!");
    } else {
        NSLog(@"removeChannelMetadata failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

updateChannelMetadata

Description

The updateChannelMetadata method can update existing channel metadata. Each time you call this method, you can update one channel metadata or a channel metadata item.

After successfully updating channel metadata, users who subscribe to the channel and enable event listeners can receive the AgoraRtmStorageTypeChannel type of the didReceiveStorageEvent event notification. See Event listeners.

Method

You can call the updateChannelMetadata method as follows:

- (void) updateChannelMetadata: (NSString * _Nonnull)channelName
                   channelType: (AgoraRtmChannelType)channelType
                          data: (AgoraRtmMetadata* _Nonnull)data
                       options: (AgoraRtmMetadataOptions* _Nullable)options
                          lock: (NSString * _Nullable)lock
                    completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

The AgoraRtmMetadataOptions data type contains the following properties:

Basic usage

// get metadata
AgoraRtmMetadata* metadata = [[AgoraRtmMetadata alloc] init];

// set metadata items
AgoraRtmMetadataItem* apple = [[AgoraRtmMetadataItem alloc] init];
apple.key = @"Apple";
apple.value = @"120";
apple.revision = 174298200;
AgoraRtmMetadataItem* banana = [[AgoraRtmMetadataItem alloc] init];
banana.key = @"Banana";
banana.value = @"220";
banana.revision = 174298100;

NSArray *item_array = [NSArray arrayWithObjects:apple,banana];
metadata.items = item_array;
metadata.majorRevision = 174298100;

AgoraRtmMetadataOptions* metadata_opt = [[AgoraRtmMetadataOptions alloc] init];
metadata_opt.recordUserId = true;
metadata_opt.recordTs = true;

[[rtm getStorage] updateChannelMetadata:@"channel_name" channelType:AgoraRtmChannelTypeMessage data:metadata options:metadata_opt lock:@"lockName" completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"updateChannelMetadata success!!");
    } else {
        NSLog(@"updateChannelMetadata failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

setUserMetadata

Description

The setUserMetadata method can set metadata for a user. If you call this method multiple times, the SDK retrieves the key of the metadata items in turn and apply settings according to the following rules:

• If you set metadata with different key, the SDK adds each set of metadata in sequence according to the order of the method calls.
• If you set metadata with the same key, the value of the last setting overwrites the previous one.

After successfully setting user metadata, users who subscribe to the user and enable event listeners can receive the AgoraRtmStorageTypeUser type of the didReceiveStorageEvent event notification. See Event listeners.

User metadata also introduces the version control logic CAS (Compare And Set). This method provides two independent version control fields, and you can set one or more of them according to your actual business use-case:

• Enable version number verification for the entire set of channel metadata by setting the majorRevision property in the AgoraRtmMetadata data type.
• Enable version number verification for a single metadata item by setting the revision property in the AgoraRtmMetadataItem class.

When setting user metadata or metadata items, you can control whether to enable version number verification by specifying the revision property:

• The default value of the revision property is -1, indicating that this method call does not perform any CAS verification. If the user metadata or metadata item already exists, the latest value overwrites the previous one. If the user metadata or metadata item does not exist, the SDK creates it.
• If the revision property is a positive integer, this method call performs the CAS verification. If the user metadata or metadata item already exists, the SDK updates the corresponding value after the version number verification succeeds. If the user metadata or metadata item does not exist, the SDK returns the error code.

Method

You can call the setUserMetadata method as follows:

- (void) setUserMetadata: (NSString * _Nonnull)userId
                    data: (AgoraRtmMetadata* _Nonnull)data
                 options: (AgoraRtmMetadataOptions* _Nullable)options
              completion: (AgoraRtmOperationBlock _Nullable)completionBlock;

The AgoraRtmMetadataOptions data type contains the following properties:

Basic usage

AgoraRtmMetadata* metadata = [[AgoraRtmMetadata alloc] init];

AgoraRtmMetadataItem* name = [[AgoraRtmMetadataItem alloc] init];
name.key = @"Name";
name.value = @"Tony";
name.revision = 174298200;
AgoraRtmMetadataItem* mute = [[AgoraRtmMetadataItem alloc] init];
mute.key = @"Mute";
mute.value = @"true";
mute.revision = 174298100;

NSArray *item_array = [NSArray arrayWithObjects:name,mute];
metadata.items = item_array;
metadata.majorRevision = 174298200;

AgoraRtmMetadataOptions* metadata_opt = [[AgoraRtmMetadataOptions alloc] init];
metadata_opt.recordUserId = true;
metadata_opt.recordTs = true;
[[rtm getStorage] setUserMetadata:@"Tony" data:metadata options:metadata_opt completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"setUserMetadata success!!");
    } else {
        NSLog(@"setUserMetadata failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];