跳到主要内容

快速上手

本教程是为了让新手快速了解融云即时通讯界面库(IMKit)。在本教程中,您可以体验集成 IMKit SDK 的基本流程和 IMKit 提供的 UI 界面。

前置条件

  • 注册开发者账号。注册成功后,控制台会默认自动创建您的首个应用,默认生成开发环境下的 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)或更高版本

开始集成

IMKit 支持通过 Maven、本地 Module 、源码三种方式的方式集成。请提前在融云官网 SDK 下载页面融云的 Maven 仓库查询最新版本。安装 IMKit 将同时集成即时通讯能力库 IMLib。其他插件可按需集成。

导入 SDK

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

  1. 打开根目录下的 build.gradleProject 视图下),声明融云的 Maven 代码库。

    allprojects {
    repositories {
    ...
    //融云 maven 仓库地址
    maven {url "https://maven.rongcloud.cn/repository/maven-releases/"}
    }
    }
  2. 在应用的 build.gradle 中,添加融云即时通讯界面库(IMKit)为远程依赖项。

    dependencies {
    ...
    //此处以集成 IMKit 库为例,您可以按需集成插件
    api 'cn.rongcloud.sdk:im_kit:x.y.z'
    }
    提示

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

其他导入方式可参考导入 SDK

使用 App Key 初始化

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

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

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

IMCenter.init(this, 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 连接状态的变化。建议在应用生命周期内设置。为了避免内存泄露,请在不需要监听时,将设置的监听器移除。详见连接状态监听

    private RongIMClient.ConnectionStatusListener connectionStatusListener = new RongIMClient.ConnectionStatusListener() {
    @Override
    public void onChanged(ConnectionStatus status) {
    //开发者需要根据连接状态码,进行不同业务处理
    }
    };
    public void setIMStatusListener() {
    RongIM.setConnectionStatusListener(connectionStatusListener);
    }
  2. 在自定义登录页面,使用上一步获取的 token, 连接融云,即模拟 userId 为 1 的用户连接到融云服务器。

    public class LoginActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_login);
    TextView login = findViewById(R.id.login);
    login.setOnClickListener(v -> {
    String token = "后台获取的 token";
    RongIM.connect(token, new RongIMClient.ConnectCallback() {
    @Override
    public void onSuccess(String userId) {
    // 登录成功,跳转到默认会话列表页。
    RouteUtils.routeToConversationListActivity(LoginActivity.this, "");
    }

    @Override
    public void onError(RongIMClient.ConnectionErrorCode connectionErrorCode) {

    }

    @Override
    public void onDatabaseOpened(RongIMClient.DatabaseOpenStatus databaseOpenStatus) {

    }
    });
    });
    }
    }

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

收发消息

对融云来说,只要提供对方的 userId,融云就可支持跟对方发起聊天。例如,A 需要 发送消息给 B,只需要将 B 的 userId 告知融云服务即可发送消息。

提示
  • 融云服务器提供消息发送能力,消息发送过程中默认不会做任何权限校验。
  • 好友关系由开发者的应用服务器自行维护。

以下我们将利用 IMKit 默认提供的 UI 页面,进行简单的消息收发体验。

UI 界面

IMKit SDK 已默认提供会话列表页面和会话页面。客户端用户在会话列表页面可查看到当前所有的聊天会话,在会话页面可进行消息查看、回复、发送等活动。

首次登录成功后,即跳转到默认会话列表界面,一般会显示一个空会话列表。客户端接收到消息后,会自动在会话列表页面展示新会话。

下图展示了 IMKit SDK 默认提供的会话列表页面。以下直接以默认会话列表为例。

(width=250) (width=250)

点击会话列表中的会话,将进入会话页面。在会话页面可发送消息。

(width=250)

IMKit 默认的会话列表页面与会话页面基于 Activity。IMKit 还支持以 Fragment 方式将两种页面集成到您应用自定义的 Activity 中。UI 支持自定义。具体请参见集成会话列表集成会话界面

如需显示昵称及头像信息,您需要设置一个用户信息提供者给 IMKit。 IMKit 通过用户信息提供者获取需要显示的用户资料数据。详情请参见用户信息

测试收发消息

在实际业务运行过程中,应用客户端可以通过用户 ID、群聊会话 ID、或聊天室 ID 等接收消息。

在本教程中,为了快速体验和测试 SDK,我们从控制台「北极星」开发者工具箱 IM Server API 调试页面向当前登录的用户发送一条文本消息,模拟单聊会话。

  1. 访问控制台「北极星」开发者工具箱的 IM Server API 调试页面。

  2. 消息标签下,找到 消息服务 > 发送单聊消息 接口。

    以下模拟了从 UserId 为 2 的用户向 UserId 为 1 的用户发送一条文本消息。

    message sent from console

  3. 客户端接收到消息后,自动在会话列表页面展示新的单聊会话。

    (width=250)

  4. 点击会话,即可进入消息列表页面,发送消息。

    (width=250)

后续步骤

以上步骤即 IMKit SDK 的快速集成与新手体验流程,您体验了基础 IM 通信能力和 UI 界面,更多详细介绍请参考后续各章节详细说明。