快速入门

最近更新时间:2021-04-06 01:55:58

本文主要介绍如何将 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:使用 JCenter 自动集成 Download 在项目的 /app/build.gradle 文件添加以下代码(1.0.1.8为当前版本号,最新版见上方链接):

    dependencies {
        //rtm
        implementation 'io.anyrtc:rtm:1.0.2.0'
    }
    
  • 方法2:手动复制 SDK 文件

    • 下载最新版的 RTM SDK aar 包
    • 将 SDK目录内的如下文件,拷贝到你的项目路径下:
    文件对应项目文件夹
    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 的应用才能互相通信。

登录

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

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

登录 RTM 服务器之后,才可以实现 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 消息对象不能重复利用再用于发送。