快速上手
本教程是为了让新手快速了解融云即时通讯界面库(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 仓库。
-
打开根目录下的
build.gradle
(Project 视图下),声明融云的 Maven 代码库。Groovyallprojects {
repositories {
...
//融云 maven 仓库地址
maven {url "https://maven.rongcloud.cn/repository/maven-releases/"}
}
} -
在应用的
build.gradle
中,添加融云即时通讯界面库(IMKit)为远程依赖项。Javadependencies {
...
//此处以集成 IMKit 库为例,您可以按需集成插件
api 'cn.rongcloud.sdk:im_kit:x.y.z'
}提示各个 SDK 的最新版本号可能不相同,还可能是 x.y.z.h,可前往 融云官网 SDK 下载页面 或 融云的 Maven 代码库 查询。
其他导入方式可参考导入 SDK。
使用 App Key 初始化
融云即时通讯客户端 SDK 核心类为 RongIM
和 IMCenter
。在 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 连接
-
监听 IM 连接状态的变化。建议在应用生命周期内设置。为了避免内存泄露,请在不需要监听时,将设置的监听器移除。详见连接状态监听。
Javaprivate RongCoreClient.ConnectionStatusListener connectionStatusListener = new RongCoreClient.ConnectionStatusListener() {
@Override
public void onChanged(ConnectionStatus status) {
//开发者需要根据连接状态码,进行不同业务处理
}
};
public void setIMStatusListener() {
RongCoreClient.addConnectionStatusListener(connectionStatusListener);
} -
在自定义登录页面,使用上一步获取的 token, 连接融云,即模拟 userId 为 1 的用户连接到融云服务器。
Javapublic 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 默认提供的会话列表页面。以下直接以默认会话列表为例。
点击会话列表中的会话,将进入会话页面。在会话页面可发送消息。
IMKit 默认的会话列表页面与会话页面基于 Activity。IMKit 还支持以 Fragment 方式将两种页面集成到您应用自定义的 Activity 中。UI 支持自定义。具体请参见集成会话列表与集成会话界面。
如需显示昵称及头像信息,您需要设置一个用户信息提供者给 IMKit。 IMKit 通过用户信息提供者获取需要显示的用户资料数据。详情请参见用户信息。
测试收发消息
在实际业务运行过程中,应用客户端可以通过用户 ID、群聊会话 ID、或聊天室 ID 等接收消息。
在本教程中,为了快速体验和测试 SDK,我们从控制台「北极星」开发者工具箱 IM Server API 调试页面向当前登录的用户发送一条文本消息,模拟单聊会话。
-
访问控制台「北极星」开发者工具箱的 IM Server API 调试页面。
-
在消息标签下,找到 消息服务 > 发送单聊消息 接口。
以下模拟了从 UserId 为 2 的用户向 UserId 为 1 的用户发送一条文本消息。
-
客户端接收到消息后,自动在会话列表页面展示新的单聊会话。
-
点击会话,即可进入消息列表页面,发送消息。
后续步骤
以上步骤即 IMKit SDK 的快速集成与新手体验流程,您体验了基础 IM 通信能力和 UI 界面,更多详细介绍请参考后续各章节详细说明。