快速集成直播聊天室
本教程主要描述如何使用融云 IM SDK 在 Android 端(Java)快速实现一个直播聊天室。
前置条件
创建融云开发者账号,获取 App Key。
步骤 1:导入 SDK
利用 Android Studio 中的 Gradle 构建系统,您可以将融云即时通讯能力库(IMLib)作为远程依赖项或本地 Android 库模块(Module)添加到您的构建中。
本教程以在 Gradle 中添加远程依赖项为例。请注意使用 融云的 Maven 仓库。
-
打开根目录下的
build.gradle
(Project 视图下),声明融云的 Maven 代码库。Groovyallprojects {
repositories {
...
//融云 maven 仓库地址
maven {url "https://maven.rongcloud.cn/repository/maven-releases/"}
}
} -
在应用的
build.gradle
中,添加融云即时通讯能力库(IMLib)为远程依赖项。Groovydependencies {
...
api 'cn.rongcloud.sdk:im_libcore:5.4.1'
api 'cn.rongcloud.sdk:im_chatroom:5.4.1'
}
步骤 2:初始化 SDK
在 Application 的 onCreate()
方法中初始化 SDK,传入 App Key 和初始化配置(InitOption
)。如果 App Key 不属于中国(北京)数据中心,必须在初始化配置中传入指定的导航服务器和统计服务器地址。
String appKey = "Your_AppKey";
InitOption initOption = new InitOption.Builder()
.setNaviServer("http(s)://naviServer") // 如果 App Key 属于新加坡或北美数据中心,必须配置为对应导航服务器地址
.setStatisticServer("http(s)://StatisticServer") // 如果 App Key 属于新加坡或北美数据中心,必须配置为对应的统计服务器地址
.build();
RongCoreClient.init(context, appKey, initOption);
- 新加坡数据中心 Navi Server 地址:nav.sg-light-edge.com(主)、nav-b.sg-light-edge.com(备)
- 新加坡数据中心 StatisticServer 地址: stats.sg-light-edge.com
步骤 3:添加消息监听器
应用需要通过 SDK 提供的消息监听器接收消息与通知。当前用户会通过该监听器接收所有类型的消息。建议在应用生命周期内注册消息监听。
RongCoreClient.addOnReceiveMessageListener(
new OnReceiveMessageWrapperListener() {
@Override
public boolean onReceivedMessage(Message message, int left, boolean hasPackage, boolean offline) {
///
return false;
}
});
步骤 4:建立 IM 连接
使用融云即时通讯功能前必须与融云服务器建立 IM 连接。建立 IM 连接时需要传入用户 Token。
建立 IM 时传入的用户 Token 表示用户在融云的唯一标识。您需要自行维护 App 用户注册流程,为用户分配唯一的用户标识(User ID),并使用该用户 ID 向融云申请建立 IM 连接所需使用的 Token。
步骤 4.1:获取 Token
客户端 SDK 不提供获取 Token 的 API。您需要通过融云服务端 API 获取 Token。
通过 App 层定义的用户 ID(userId
)换取融云服务中使用的身份验证 Token。同一个用户 ID 可多次获取 Token,如果 Token 在有效期内,均可用于连接融云服务。同一用户 ID 如需重新获取 Token 使用同一接口。
调用融云服务端 API 必须进行身份验证。请在请求中添加以下 HTTP 标头(Header)字段:
App-Key
: App KeyNonce
: 随机数Timestamp
: Unix 时间戳Signature
: 按以下顺序将 App Secret、Nonce、Timestamp 拼接成一个字符串,进行 SHA1 哈希计算。App Secret 与 App Key 对应,可从融云控制台 App Key 页面获取。
如果 App Key 不属于中国(北京)数据中心,必须请求海外的 API 服务地址。
- 北京:api.rong-api.com
- 新加坡:api.sg-light-api.com(主)、api-b.sg-light-api.com(备)
在获取 Token 时,HTTP 请求正文中需要传入用户 ID(userId
)、名称(name
)和头像(portraitUri
)。
POST /user/getToken.json HTTP/1.1
Host: api.rong-api.com
App-Key: Your_AppKey
Nonce: 14314
Timestamp: 1408710653491
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded
userId=jlk456j5&name=Ironman&portraitUri=http%3A%2F%2Fabc.com%2Fmyportrait.jpg
用户 ID 支持大小写英文字母与数字的组合,最大长度 64 字节。注意,名称(name
)和头像(portraitUri
)仅供移动端远程推送时使用。在重新获取 Token 时如果传入新的数据,则会覆盖旧的名称与头像数据。
返回结果中会包含传入的用户 ID 与对应的 Token。Token 长度在 256 字节以内,您可以缓存在应用内。
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"code":200, "userId":"jlk456j5", "token":"sfd9823ihufi"}