You can use this guide to quickly start messaging with the Agora RTM Android SDK.
We provide an open-source demo project on GitHub, Agora-RTM-Tutorial-Android, which implements an elementary messaging system.
Android SDK API Level 16 or higher
To run your app on Android 9, see Android Privacy Changes for more information.
Android Studio 3.0 or later
A valid Agora account. (Sign up for free)
We will walk you through the following steps in this section:
You can skip to Integrate the SDK into your project if you already have an App ID.
Sign up for a developer account at Agora Console. See Sign in and Sign up.
Click in the left navigation menu to enter the Project Management page.
Click Create.
Choose either of the following methods to integrate the Agora RTM Android SDK into your project.
Method 1: Automatically integrate the SDK using JCenter
Add the following line in the /app/build.gradle file of your project (1.4.1 is the version number):
...
dependencies {
...
implementation 'io.agora.rtm:rtm-sdk:1.4.1'
}
Method 2: Manually copy the SDK files
File | Project Folder |
---|---|
agora-rtm_sdk.jar | ~/app/libs/ |
/arm64-v8a/libagora-rtm-sdk-jni.so | ~/app/src/main/jniLibs/arm64-v8a/ |
/armeabi-v7a/libagora-rtm-sdk-jni.so | ~/app/src/main/jniLibs/armeabi-v7a/ |
/x86/libagora-rtm-jni.so | ~/app/src/main/jniLibs/x86/ |
/x86_64/libagora-rtm-sdk-jni.so | ~/app/src/main/jniLibs/x86_64/ |
Add the following permissions in the /app/src/main/AndroidManifest.xml file for device access according to your needs:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="io.agora.rtmtutorial">
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
...
</manifest>
Add the following line in the app/proguard-rules.pro file to prevent code obfuscation:
-keep class io.agora.**{*;}
This section provides API call sequence diagrams and sample codes related to peer-to-peer messaging and channel messaging.
App ID
you get from Console when creating and initializing an Agora RTM client. RtmClientListener
, the SDK uses its callbacks to notify the app of ongoing events, including:import io.agora.rtm.ErrorInfo;
import io.agora.rtm.ResultCallback;
import io.agora.rtm.RtmChannel;
import io.agora.rtm.RtmChannelListener;
import io.agora.rtm.RtmChannelMember;
import io.agora.rtm.RtmClient;
import io.agora.rtm.RtmClientListener;
import io.agora.rtm.RtmMessage;
import io.agora.rtm.SendMessageOptions;
public void init() {
try {
mRtmClient = RtmClient.createInstance(mContext, APPID,
new RtmClientListener() {
@Override
public void onConnectionStateChanged(int state, int reason) {
Log.d(TAG, "Connection state changes to "
+ state + " reason: " + reason);
}
@Override
public void onMessageReceived(RtmMessage rtmMessage, String peerId) {
String msg = rtmMessage.getText();
Log.d(TAG, "Message received " + " from " + peerId + msg
);
}
});
} catch (Exception e) {
Log.d(TAG, "RTM SDK initialization fatal error!");
throw new RuntimeException("You need to check the RTM initialization process.");
}
}
Only when you successfully log in the Agora RTM system, can you use most of the core features provided by the Agora RTM SDK. When logging in the Agora RTM system, you need to:
token
as null. You need to generate an RTM Token from your business server. For more information, see Token Security.userId
is the unique identifier of each user. You must not set it as empty, null, or "null". ResultCallback
instance, which returns the onSuccess
or onFailure
callback. mRtmClient.login(null, userId, new ResultCallback<Void>() {
@Override
public void onSuccess(Void responseInfo) {
loginStatus = true;
Log.d(TAG, "login success!");
}
@Override
public void onFailure(ErrorInfo errorInfo) {
loginStatus = false;
Log.d(TAG, "login failure!");
}
});
To log out of the system:
mRtmClient.logout(null);
You need to call the following method to send an peer-to-peer message to a specified user.
sendMessageToPeer(@NonNull String, @NonNull RtmMessage, @NonNull SendMessageOptions, @Nullable ResultCallback<void>)
You need to:
createMessage
method to create an RtmMessage
instance and pass it topublic void sendPeerMessage(String dst, String content) {
final RtmMessage message = mRtmClient.createMessage();
message.setText(content);
SendMessageOptions option = new SendMessageOptions();
option.enableOfflineMessaging = true;
mRtmClient.sendMessageToPeer(dst, message, option, new ResultCallback<Void>() {
@Override
public void onSuccess(Void aVoid) {
}
@Override
public void onFailure(ErrorInfo errorInfo) {
}
});
}
You can use the RtmClientListener
instance that you passed in when creating an RtmClient
instance to listen for events that a peer-to-peer message is received. The onMessageReceived(RtmMessage message, String peerId)
callback of the listener takes an RtmMessage
instance with it.
message.getText()
method to get the text content of the message.peerId
refers to the user ID of the message sender. The received
RtmMessage
object cannot be reused.
Ensure that you have logged in the Agora RTM system before being able to use the channel messaging function.
When creating an RtmChannel, you need to pass a channel ID, a string that must not be empty, null, "null", or exceed 64 Bytes in length. You also need to specify a channel listener:
private RtmChannelListener mRtmChannelListener = new RtmChannelListener() {
@Override
public void onMessageReceived(RtmMessage message, RtmChannelMember fromMember) {
String text = message.getText();
String fromUser = fromMember.getUserId();
}
@Override
public void onMemberJoined(RtmChannelMember member) {
}
@Override
public void onMemberLeft(RtmChannelMember member) {
}
};
try {
mRtmChannel = mRtmClient.createChannel("demoChannelId", mRtmChannelListener);
} catch (RuntimeException e) {
Log.e(TAG, "Fails to create channel. Maybe the channel ID is invalid," +
" or already in use. See the API Reference for more information.");
}
mRtmChannel.join(new ResultCallback<Void>() {
@Override
public void onSuccess(Void responseInfo) {
Log.d(TAG, "Successfully joins the channel!");
}
@Override
public void onFailure(ErrorInfo errorInfo) {
Log.d(TAG, "join channel failure! errorCode = "
+ errorInfo.getErrorCode());
}
});
After successfully joining a channel, you can send messages to the channel. As we mentioned in the previous section, you need to set a channel listener for events such as a channel message is received.
When calling a sendChannelMessage()
message method to send channel messages, you need to:
RtmMessage
object. You need to use the createMessage()
method of the RtmClient
class to create an RtmMessage
object and use the setText()
method to set the message content. ResultCallback
instance.public void sendChannelMessage(String msg) {
RtmMessage message = mRtmClient.createMessage();
message.setText(msg);
mRtmChannel.sendMessage(message, new ResultCallback<Void>() {
@Override
public void onSuccess(Void aVoid) {
}
@Override
public void onFailure(ErrorInfo errorInfo) {
}
});
}
You can call the leave()
method to leave a channel.
The Agora RTM SDK supports creating multiple RtmClient instances that are independent of each other.
To send and receive peer-to-peer or channel messages, ensure that you have successfully logged in the Agora RTM system (i.e., ensure that you have received onSuccess).
To use any of the channel features, you must first call the createChannel method to create a channel instance.
You can create multiple channel instances for each RtmClient instance, but you can only join a maximum of 20 channels at the same time. The channelId
parameter needs to be channel-specific.
When you leave a channel and do not want to join it again, you can call the release method to release all resources used by the channel instance.
You cannot reuse a received RtmMessage instance.