Create and Initialize an AgoraRtmKit Instance

Before creating an AgoraRtmKit instance, ensure that you prepare the development environment.

Implementation

  1. Import the following tbd files and frameworks:

    • libc++.tbd
    • SystemConfiguration.framework
    • CoreTelephony.framework
    • libresolv.9.tbd
  2. Call the initWithAppId method to create an AgoraRtmKit instance. You need to:

    • Pass the App ID issued by Agora to you. Only apps with the same App ID can join the same channel.
    • Specify an event handler. The Agora RTM SDK process event handlers with the AgoraRtmDelegate instance to inform the app about runtime events, such as connection state changes and receiving peer-to-peer messages.
@interface ViewController ()<AgoraRtmChannelDelegate, AgoraRtmDelegate>

@property(nonatomic, strong)AgoraRtmKit* kit;

@end

@implementation ViewController
- (void)viewDidLoad {
    [super viewDidLoad];

    // Create an AgoraRtmKit instance.
    _kit = [[AgoraRtmKit alloc] initWithAppId:YOUR_APP_ID delegate:self];
    // Note: The SDK does not trigger the callback if the AgoraRtmKit reference is not held and released.
    // A token is mandatory if security options are enabled for your appId.
}

Considerations

Next steps

You have created an AgoraRtmKit instance and can start using the Agora RTM SDK:

Log in Agora's RTM System

Before logging in Agora's RTM system, ensure that you create an AgoraRtmKit instance.

Implementation

Call the loginByToken method to log in Agora's RTM system. You need to:

  • Pass a token that identifies the role and permission of the user. Set token as "nil" for low-security requirements. A token is generated at the server of the app.
  • Pass a user ID that identifies the user. The userId parameter must not include non-printable characters, and can neither exceed 64 bytes in length nor start with a space. Do not set userId as "nil".
  • Pass the AgoraRtmLoginBlock and connectionStateChanged callbacks, which indicate whether the login succeeds or fails.
[_kit loginByToken:nil user:@"testuser" completion:^(AgoraRtmLoginErrorCode errorCode) {
    if (errorCode != AgoraRtmLoginErrorOk) {
        NSLog(@"login failed %@", @(errorCode));
    } else {
        NSLog(@"login success");
    }
}];

#pragma AgoraRtmDelegate
...
- (void)rtmKit:(AgoraRtmKit *)kit connectionStateChanged:(AgoraRtmConnectionState)state reason:(AgoraRtmConnectionChangeReason)reason
{
    NSLog(@"connection state changed to %@", @(reason));
}

You can call the logoutWithCompletion method to log out of Agora's RTM system.

[_kit logoutWithCompletion:^(AgoraRtmLogoutErrorCode errorCode) {
    if (errorCode != AgoraRtmLogoutErrorOk) {
        NSLog(@"login failed %@", @(errorCode));
    } else {
        NSLog(@"login success");
    }
}];

After calling the logoutWithCompletion method to log out of Agora's RTM system, you can call the loginByToken method again to switch to another account.

Next steps

After logging in Agora's RTM system, you can:

Send a Peer-to-peer Message

After logging in Agora's RTM system, you can send a peer-to-peer message.

Implementation

Send a peer-to-peer message

Call the sendMessage method to send a peer-to-peer message to a specific user (peer).

- (void)sendYourPeerToPeerMessage {
    [_kit sendMessage:[[AgoraRtmMessage alloc] initWithText:@"testmsg"] toPeer:@"peer" completion:^(AgoraRtmSendPeerMessageState state) {
        if (state == AgoraRtmSendPeerMessageStateReceivedByPeer) {
            NSLog(@"sent success");
        }
    }];
}

#pragma AgoraRtmDelegate
...
- (void)rtmKit:(AgoraRtmKit *)kit messageReceived:(AgoraRtmMessage *)message fromPeer:(NSString *)peerId
{
    NSLog(@"message received from %@: %@", message.text, peerId);
}

Receive a peer-to-peer message

  • The sender receives the AgoraRtmSendPeerMessageBlock callback with the state of sending the peer-to-peer message.
  • The receiver receives the messageReceived callback with the sent message and the user ID (peerId) of the sender.

Consideration

You cannot reuse an Agora AgoraRtmMessage object that has been received by a user.

Next steps

You can send a channel message.

Send a Channel Message

After logging in Agora's RTM system, you can send a channel message.

Implementation

Create an AgoraRtmChannel instance and join a channel

  1. Call the createChannelWithId method in the AgoraRtmChannel instance to create an Agora RTM channel. You need to:

    • Pass the channel ID. The channelId parameter must be in the string format, less than 64 bytes, and cannot be empty or set as "nil".
    • Specify a reference to AgoraRtmChannelDelegate, through which the Agora RTM SDK informs the app about channel events, such as receiving channel messages and a user joining or leaving a channel.
  2. Call the joinWithCompletion method in the AgoraRtmChannel instance to join a channel. The AgoraRtmJoinChannelBlock and memberJoined callbacks indicate whether this method call succeeds or fails.

@interface ViewController ()<AgoraRtmChannelDelegate, AgoraRtmDelegate>

...
@property(nonatomic, strong)AgoraRtmChannel* channel;

@implementation
- (void)createAndJoinChannel {
    _channel = [_kit createChannelWithId:@"testchannel" delegate:self];
    [_channel joinWithCompletion:^(AgoraRtmJoinChannelErrorCode state) {
        if(state == AgoraRtmJoinChannelErrorOk) {
            NSLog(@"join success");
        } else {
            NSLog(@"join failed: %@", @(state));
        }
    }];
}
#pragma AgoraRtmChannelDelegate
...
- (void)rtmKit:(AgoraRtmKit *)kit channel:(AgoraRtmChannel *)channel memberLeft:(AgoraRtmMember *)member
{
    NSLog(@"%@ left channel %@", member.userId, member.channelId);
}

- (void)rtmKit:(AgoraRtmKit *)kit channel:(AgoraRtmChannel *)channel memberJoined:(AgoraRtmMember *)member
{
    NSLog(@"%@ joined channel %@", member.userId, member.channelId);
}

Send a channel message

Call the sendMessage method in the AgoraRtmChannel instance to send a channel message. You need to:

- (void)sendYourChannelMessage {
    [_channel sendMessage:[[AgoraRtmMessage alloc] initWithText:@"channelmsg"] completion:^(AgoraRtmSendChannelMessageState state) {
        if(state == AgoraRtmSendChannelMessageStateReceivedByServer) {
            NSLog(@"sent success");
        }
    }];
}

#pragma AgoraRtmDelegate
...
- (void)rtmKit:(AgoraRtmKit *)kit channel:(AgoraRtmChannel *)channel messageReceived:(AgoraRtmMessage *)message fromMember:(AgoraRtmMember *)member
{
    NSLog(@"message received from %@ in channel %@: %@", message.text, member.channelId, member.userId);
}

Receive a channel message

Retrieve the member list of a channel

Call the getMembersWithCompletion method in the AgoraRtmChannel interface to retrieve the member list of a channel. The AgoraRtmGetMembersBlock callback returns the member list of the channel.

Leave a channel

Call the leaveWithCompletion method in the AgoraRtmChannel instance to leave a channel.

[_channel leaveWithCompletion:^(AgoraRtmLeaveChannelErrorCode state) {
    if(state == AgoraRtmLeaveChannelErrorOk) {
        NSLog(@"leave success");
    } else {
        NSLog(@"leave failed: %@", @(state));
    }
}];

You can rejoin the channel by calling the joinWithCompletion method again.

Considerations

  • To use the channel feature, each client must first call the createChannelWithId method in the AgoraRtmKit instance to create a channel instance.
  • You can create multiple channel instances in an AgoraRtmKit instance and users can join multiple channels at the same time. The channelId parameter and AgoraRtmChannelDelegate interface of different channels must be different.
  • If you pass an illegal channel ID or if the channel ID is being used, the createChannelWithId method returns "nil".
  • You cannot reuse an AgoraRtmMessage object that has been received by a user.
  • When you leave a channel and do not join it again, you can call the destroyChannelWithId method in the AgoraRtmKit instance to release all resources used by the channel instance.
  • Except for the callback triggered by the failure of the basic parameter validity check, all other callbacks are called asynchronously, unless otherwise specified.

Next steps

You can send a peer-to-peer message.