跳到主要内容

快速上手

本教程是为了让新手快速了解融云即时通讯能力库(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.gradleProject 视图下),声明融云的 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 核心类为 RongCoreClientRongIMClient。在 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) {

}
});