本页介绍在正式使用 Agora RTM Android SDK 进行实时消息通讯前,需要准备的开发环境要求及 SDK 集成方法等内容。

示例项目体验

Agora 在 GitHub 上提供一个开源的实时消息示例项目 Agora-RTM-Tutorial-Android 供你参考。

快速跑通示例项目

如果你是第一次使用声网的服务,我们推荐观看下面的视频,了解关于声网服务的基本信息以及如何快速跑通示例项目。

点击参与视频教程问卷调查,帮助我们改进体验。

视频中展示的 UI 可能有部分调整更新,请以当前最新版为准。

开发环境要求

如果你的网络环境部署了防火墙,请根据应用企业防火墙限制打开相关端口并设置域名白名单。

准备开发环境

开发环境的准备包含以下内容:

获取 App ID

参考以下步骤获取一个 App ID。若已有App ID,可以直接查看快速集成 SDK

获取 App ID
  1. 进入控制台,并按照屏幕提示注册账号并登录控制台。详见创建新账号

  2. 点击左侧导航栏的 图标进入项目管理页面,点击创建按钮。

  1. 在弹出的对话框内输入项目名称,选择 App ID 作为鉴权机制,再点击“提交”。

  1. 项目创建成功后,你会在项目列表下看到刚刚创建的项目,并找到对应的 App ID。

快速集成 SDK

选择以下任意一种方式将 Agora RTM Android SDK 集成到你的项目中。

方法 1:使用 JCenter 自动集成

在项目的 /app/build.gradle 文件添加以下代码(1.4.0 为当前版本号):


...
dependencies {
    ...
    implementation 'io.agora.rtm:rtm-sdk:1.4.0'
}

方法 2:手动复制 SDK 文件

  1. 下载最新版的 Agora RTM Android SDK 并解压。
  2. 将 SDK 包内 libs 路径下的如下文件,拷贝到你的项目路径下:
文件 对应项目文件夹
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/

添加设备权限

打开 app/src/main/AndroidManifest.xml 文件,添加必要的设备权限。比如:

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

防止混淆代码

app/proguard-rules.pro 文件文件中添加如下行,防止代码混淆:

   -keep class io.agora.**{*;}

实时消息和基本频道操作

本节主要提供实现实时消息和基本频道操作的相关示例代码。

初始化

在创建实例前,请确保你已完成环境准备,安装包获取等步骤。

创建实例需要填入准备好的 App ID, 只有 App ID 相同的应用才能互通。

指定事件回调 RtmClientListener,SDK 通过该回调通知应用程序:

  • SDK 与 RTM 系统的连接状态变化;
  • 接收点对点消息;
  • 其他相关事件。
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 init fatal error!");
                throw new RuntimeException("You need to check the RTM init process.");
        }
}

登录

APP 必须在登录 RTM 服务器之后,才可以使用 RTM 的点对点消息和群聊功能。在此之前,请确保 RtmClient 初始化完成。

  • 传入能标识用户角色和权限的 Token。如果安全要求不高,也可以将值设为 null。Token 需要在应用程序的服务器端生成,具体生成办法,详见 校验用户权限
  • 传入能标识每个用户的 ID。用户 ID 为字符串,必须是可见字符(可以带空格),不能为空或者多于 64 个字符,也不能是字符串 "null"
  • 传入结果回调,用于接收登录 RTM 服务器成功或者失败的结果回调。
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!");
        }
});

如果需要退出登录,可以调用 logout() 方法,退出登录之后可以调用 login() 重新登录或者切换账号。

mRtmClient.logout(null);

点对点消息

在成功登录 RTM 服务器之后,可以开始使用 RTM 的点对点消息功能。

发送点对点消息

调用 sendMessageToPeer 方法发送点对点消息。在该方法中:

  • 传入目标消息接收方的用户 ID。
  • 传入 RtmMessage 对象实例。该消息对象由 RtmClient 类的的 createMessage() 实例方法创建,并使用消息实例的 setText() 方法设置消息内容。
  • 传入消息发送结果监听器,用于接收消息发送结果回调,如:服务器已接收,发送超时,对方不可达等。
public 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) {

            }
        });
    }

接收点对点消息

点对点消息的接收通过创建 RtmClient 实例的时候传入的 RtmClientListener 回调接口进行监听。在该回调接口的 onMessageReceived(RtmMessage message, String peerId) 回调方法中:

  • 通过 message.getText() 方法可以获取到消息文本内容。
  • peerId 是消息发送方的用户 ID。

频道消息

App 在成功登录 RTM 服务器 之后,可以开始使用 RTM 的频道消息功能。

创建 、加入频道实例

  • 传入能标识每个频道的 ID。ID 为字符串,不能为空或者多于 64 个字符,也不能是字符串 "null"
  • 指定一个频道监听器。SDK 通过回调通知应用程序频道的状态变化和运行事件等,如: 接收到频道消息、用户加入和退出频道等。
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());
                }
        });

收发频道消息

在成功加入频道之后,用户可以开始向该频道发送消息。频道消息的接收通过创建频道消息的时候传入的回调接口进行监听。

调用频道实例的 sendChannelMessage() 方法向该频道发送消息。在该方法中:

  • 传入 RtmMessage 对象实例。该消息对象由 RtmClient 类的 createMessage() 实例方法创建,并使用消息实例的 setText() 方法设置消息内容。
  • 传入消息发送结果监听器,用于接收消息发送结果回调,如:服务器已接收,发送超时等。
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) {
                }
        });
}

退出频道

调用实例的 leave() 方法可以退出该频道。退出频道之后可以调用 join() 方法再重新加入频道。

开发注意事项

  • RTM 支持多个相互独立的 RtmClient 实例。

  • 在收发点对点消息或进行其他频道操作前,请确保你已成功登录 Agora RTM 系统(即确保已经收到 onSuccess)。

  • 使用频道核心功能前必须通过调用 createChannel 方法创建频道实例。

  • 你可以创建多个 RtmClient 客户端实例,但是每个客户端实例最多只能同时加入 20 个频道。每个频道都应有不同的 channelId 参数。

  • 当离开了频道且不再加入该频道时,可以调用 release 方法及时释放频道实例所占用的资源。

  • 接收到的 RtmMessage 消息对象不能重复利用再用于发送。