跳到主要内容

快速上手

本教程是为了让新手快速了解融云即时通讯能力库（IMLib）。在本教程中，您可以体验集成 SDK 的基本流程和 IMLib 的基础通信能力。

前置条件​

  • 注册开发者账号。注册成功后，控制台会默认自动创建您的首个应用，默认生成开发环境下的 App Key，使用国内数据中心。

  • 获取开发环境的应用 App Key。如不使用默认应用，请参考 如何创建应用，并获取对应环境 App Key 和 App Secret。

    提示

    每个应用具有两个不同的 App Key，分别对应开发环境与生产环境，两个环境之间数据隔离。在您的应用正式上线前，可切换到使用生产环境的 App Key，以便上线前进行测试和最终发布。

环境要求​

  • （SDK ≧ 5.6.3）使用 Android 5.0（API 21）或更高版本
  • （SDK < 5.6.3）使用 Android 4.4（API 19）或更高版本

开始集成​

IMLib 支持通过 Maven、本地 Android 库模块（Module）的方式集成。请提前在融云官网 SDK 下载页面或融云的 Maven 仓库查询最新版本。

导入 SDK​

本教程以在 Gradle 中添加远程依赖项为例，将 IMLib SDK 导入到您的应用工程中。请注意使用 融云的 Maven 仓库。

  1. 打开根目录下的 build.gradle（Project 视图下），声明融云的 Maven 代码库。

    allprojects {
        repositories {
            ...
            //融云 maven 仓库地址
            maven {url "https://maven.rongcloud.cn/repository/maven-releases/"}
        }
    }

  2. 在应用的 build.gradle 中，添加融云即时通讯能力库（IMLib）为远程依赖项。

    dependencies {
    	...
    	//此处以集成 IMLib 为例
    	api 'cn.rongcloud.sdk:im_lib:x.y.z'
    }
    提示

    各个 SDK 的最新版本号可能不相同，还可能是 x.y.z.h，可前往 融云官网 SDK 下载页面 或 融云的 Maven 代码库 查询。

其他导入 SDK 方式请参见导入 SDK。

初始化 SDK​

融云即时通讯客户端 SDK 核心类为 RongCoreClient 和 RongIMClient。在 Application 的 onCreate() 方法中，调用 RongCoreClient 的初始化方法，传入生产或开发环境的 App Key。

如果 SDK 版本 ≧ 5.4.2，请使用以下初始化方法。

String appKey = "Your_AppKey"; // example: bos9p5rlcm2ba
InitOption initOption = new InitOption.Builder().build();

RongCoreClient.init(getApplicationContext(), appKey, initOption);

初始化配置（InitOption）中封装了区域码（AreaCode），导航服务地址（naviServer）、文件服务地址（fileServer）、数据统计服务地址（statisticServer）配置，以及是否开启推送的开关（enablePush）和主进程开关（isMainProcess）。不传入任何配置表示全部使用默认配置。SDK 默认连接北京数据中心。

如果 App Key 不属于中国（北京）数据中心，则必须传入有效的初始化配置。初始化详细说明参见初始化。

获取用户 Token​

用户 Token 是与用户 ID 对应的身份验证令牌，是应用程序的用户在融云的唯一身份标识。应用客户端在使用融云即时通讯功能前必须与融云建立 IM 连接，连接时必须传入 Token。

在实际业务运行过程中，应用客户端需要通过应用的服务端调用 IM Server API 申请取得 Token。详见 Server API 文档 注册用户。

在本教程中，为了快速体验和测试 SDK，我们将使用控制台「北极星」开发者工具箱，从 API 调试页面调用 获取 Token 接口，获取到 userId 为 1 的用户的 Token。提交后，可在返回正文中取得 Token 字符串。

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200,"userId":"1","token":"gxld6GHx3t1eDxof1qtxxYrQcjkbhl1V@sgyu.cn.example.com;sgyu.cn.example.com"}

建立 IM 连接​

  1. 监听 IM 连接状态的变化，以便 UI 上给用户以提示，提高体验。建议在应用生命周期内设置。为了避免内存泄露，请在不需要监听时，将设置的监听器移除。详见连接状态监听。

    private IRongCoreListener.ConnectionStatusListener connectionStatusListener = new IRongCoreListener.ConnectionStatusListener() {
      @Override
      public void onChanged(ConnectionStatus status) {
            //开发者需要根据连接状态码，进行不同业务处理
      }
    };
    public void setIMStatusListener() {
        // 添加连接状态监听器 since 5.1.6
        RongCoreClient.addConnectionStatusListener(ConnectionStatusListener);
    }

  2. 使用以上步骤中获取的 Token, 模拟 userId 为 1 的用户连接到融云服务器。

    String token = "用户Token";
    RongCoreClient.connect(token, new IRongCoreCallback.ConnectCallback() {
        /**
         * 数据库回调.
         * @param code 数据库打开状态. DATABASE_OPEN_SUCCESS 数据库打开成功; DATABASE_OPEN_ERROR 数据库打开失败
         */
        @Override
        public void OnDatabaseOpened(IRongCoreEnum.DatabaseOpenStatus code) {

        }
        /**
         * 成功回调
         * @param userId 当前用户 ID
         */
        @Override
        public void onSuccess(String userId) {

        }
        /**
         * 错误回调
         * @param errorCode 错误码
         */
        @Override
        public void onError(IRongCoreEnum.ConnectionErrorCode errorCode) {

        }
    });

SDK 已实现自动重连机制，请参见连接。

监听消息​

设置消息接收监听器，用于接收所有类型的实时或者离线消息。

RongCoreClient.addOnReceiveMessageListener(
    new io.rong.imlib.listener.OnReceiveMessageWrapperListener() {
        @Override
        public void onReceivedMessage(Message message, ReceivedProfile profile) {
            //  针对接收离线消息时，服务端会将 200 条消息打成一个包发到客户端，客户端对这包数据进行解析。该参数表示每个数据包数据逐条上抛后，还剩余的条数
            int left = profile.getLeft();
            // 消息是否离线消息
            boolean isOffline = profile.isOffline();
            // 是否在服务端还存在未下发的消息包
            boolean hasPackage = profile.hasPackage();
        }
    }
);

发送消息​

向 userId 为 2 的用户发送一条消息。

String content = “您好，这是从用户1发出的消息”;
String targetId = "2";
ConversationType conversationType = ConversationType.PRIVATE;
// 构建消息
TextMessage messageContent = TextMessage.obtain(content);
Message message = Message.obtain(targetId, conversationType, messageContent);

// 发送消息
RongCoreClient.getInstance().sendMessage(message, null, null, new IRongCoreCallback.ISendMessageCallback() {
    @Override
    public void onAttached(Message message) {

    }

    @Override
    public void onSuccess(Message message) {

    }

    @Override
    public void onError(Message message, IRongCoreEnum.ErrorCode errorCode) {

    }
});

最后于 更新