快速入门

本文主要介绍如何将 RTM Android SDK 实时消息集成到你的项目中以及相关注意事项。

开发环境要求

Android SDK API Level ≥ 19
如果你的 App 以 Android 9 及以上为目标平台，请关注 Android 隐私权变更。
Android Studio 3.0 或以上版本。
一个有效的开发者账号。

快速集成

本小节介绍如何获取 AppID 以及如何快速将 SDK 集成到项目中。

获取 AppID

参考以下步骤获取一个 AppID。若已经拥有 AppID，请跳过当前步骤，直接查看快速集成。

1. 创建项目

首先我们需要在开发者控制台创建一个「项目」。
2. 获取 APP ID

获取项目的「APP ID」。

导入 SDK

方法 1：使用 Gradle 自动集成,在项目的 /app/build.gradle 文件添加以下代码
```
dependencies {
    //rtm
    implementation 'io.anyrtc:rtm:1.0.2.4'
}
```
方法2：手动复制 SDK 文件
- 下载最新版的 RTM SDK aar 包
- 将 SDK目录内的如下文件，拷贝到你的项目路径下：
文件对应项目文件夹
rtm-release.aar ~/app/libs/

文件	对应项目文件夹
rtm-release.aar	~/app/libs/

添加设备权限

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

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="org.ar.rtm">

    <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 ID, 只有 App ID 相同的应用才能互通。

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

SDK 与 RTM 系统的连接状态变化；
接收点对点消息；
其他相关事件。

public void init() {
        try {
            //替换你申请的APPID
            mRtmClient = RtmClient.createInstance(mContext, "APP ID", new RtmClientListener() {
                @Override
                public void onConnectionStateChanged(int state, int reason) {
                  
                }

                @Override
                public void onMessageReceived(RtmMessage rtmMessage, String peerId) {
                   
                }

                @Override
                public void onTokenExpired() {

                }

                @Override
                public void onPeersOnlineStatusChanged(Map<String, Integer> status) {
                }
            });

        } catch (Exception e) {
            throw new RuntimeException("NEED TO check rtm sdk init fatal error\n" + Log.getStackTraceString(e));
        }

    }

使用相同 App ID 的应用才能互相通信。

传入能标识用户角色和权限的 Token。如果安全要求不高，也可以将值设为 null。
传入能标识每个用户的 ID。用户 ID 为字符串，必须是可见字符（可以带空格），不能为空或者多于 64 个字符，也不能是字符串 "null"。
传入结果回调，用于接收登录 RTM 服务器成功或者失败的结果回调。

mRtmClient.login(“”, userId, new ResultCallback<Void>() {
        @Override
        public void onSuccess(Void responseInfo) {
                Log.d(TAG, "login success!");
        }
        @Override
        public void onFailure(ErrorInfo errorInfo) {
                Log.d(TAG, "login failure!");
        }
});

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

mRtmClient.logout(null);

点对点消息

点对点消息包括：发送点对点消息，接收点对点消息。

发送点对点消息

调用 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() 方法可以退出该频道。release()方法可以释放该频道所有资源，leave() release()之后可以调用 join() 方法再重新加入频道。

登出

rtmClient 的实例提供了 logout 方法可以登出 RTM 系统。

如果需要切换账号，可以在退出登录切换 uid 再次调用 login 实现切换账号。

public void logout() {
        mRtmClient.logout(new ResultCallback<Void>() {
            @Override
            public void onSuccess(Void aVoid) {
            }

            @Override
            public void onFailure(ErrorInfo errorInfo) {
            }
        });
}

开发注意事项

RTM 支持多个相互独立的 RtmClient 实例。
在收发点对点消息或进行其他频道操作前，请确保你已成功登录 RTM 系统（即确保已经收到 onSuccess）。
使用频道核心功能前必须通过调用 createChannel 方法创建频道实例。
你可以创建多个 RtmClient 客户端实例，但是每个客户端实例最多只能同时加入 20 个频道。每个频道都应有不同的 channelId 参数。
当离开了频道且不再加入该频道时，可以调用 release 方法及时释放频道实例所占用的资源。
接收到的 RtmMessage 消息对象不能重复利用再用于发送。