融云开发者文档

更新时间: 2021-04-16

以下内容为快速集成摘要，具体细节可依次参考全局配置

# 导入 SDK

环境要求

名称	版本
Android SDK Build-tools	21 及以上
Android SDK	Android API 19 及以上（安卓 4.4 ）
JAVA	JDK 1.7 及以上
Gradle	3.0 及以上版本

SDK 支持以下两种导入方式：

# Maven 方式

由于 Jcenter 于2021年 5 月 4 日停止提供远程仓库服务，远程仓库统一由 JCenter 迁移到新的融云私有仓库。

不再支持该地址集成： https://dl.bintray.com/rongcloud/maven。

在工程根目录下的 build.gradle 配置脚本的 allprojects 中添加 SDK 的 Maven 仓库地址, 如下:

allprojects {
    repositories {
        jcenter()
        mavenCentral()
        maven {url  "http://maven.rongcloud.cn/repository/maven-releases/"}
    }
}
已复制

1
2
3
4
5
6
7

在项目主工程中的 build.gradle 添加远程依赖, 如下:

dependencies {
    api 'cn.rongcloud.sdk:im_kit:4.0.3.14'
    api 'cn.rongcloud.sdk:im_lib:4.0.3.14'
}
已复制

1
2
3
4

# Module 方式

下载 Module

到融云官网下载 SDK Module (opens new window)
选择需要的 Module 进行下载, 如图:

导入 Module

打开工程， File -> New -> Import Module. 找到下载的 Module 组件导入.
在主工程的 build.gradle 文件中配置 Module, 如下:

dependencies {
    ...
    api project(':IMKit')
    api project(':IMLib')
    ...
}
已复制

1
2
3
4
5
6

查看 SDK 中 API 的方法

导入 javadoc 后可以轻松的在 Android Studio 中查看 API 的详细说明，如图：

导入方法请点击查看 (opens new window)

# 初始化

融云 SDK 需要开发者在工程中调用下面方法来初始化 SDK。在 App 的整个生命周期中，开发者只需要将 SDK 初始化一次。

Appkey 区分 开发环境 与 生产环境，开发者在使用时注意当前环境是否匹配
建议在用户同意隐私协议后，再调用初始化

/**
 * 应用启动时，判断用户是否已接受隐私协议，如果已接受，正常初始化；否则跳转到隐私授权页面请求用户授权。
 */
public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        //伪代码，从 sp 里读取用户是否已接受隐私协议
        boolean isPrivacyAccepted = getPrivacyStateFromSp();
        //用户已接受隐私协议，进行初始化
        if (isPrivacyAccepted) {
            String appKey = "融云开发者后台创建的应用的 AppKey";
            //第一个参数必须传应用上下文
            RongIM.init(this.getApplicationContext(), appKey);
        } else {
            //用户未接受隐私协议，跳转到隐私授权页面。
            goToPrivacyActivity();
        }
        ...
    }
}

/**
 * 该类为隐私授权页面，示范如何在用户接受隐私协议后进行 IM 初始化。
 */
public class PrivacyActivity extends Activity implements View.OnClickListener {
    ...
    @Override
    public void onClick(View v) {
        switch (v.getId()) {
            case R.id.accept_privacy:
                //伪代码，保存到 sp
                savePrivacyStateToSp();

                String appKey = "融云开发者后台创建的应用的 AppKey";
                //第一个参数必须传应用上下文
                RongIM.init(this.getApplicationContext(), appKey);
                break;
            default:
                ...
        }
    }
}
已复制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

# 连接 IM

连接服务器之前需先获取用户 token 才可进行连接. 具体获取方法可参考 Server API 获取 Token

String token = "用户Token";
RongIM.connect(token, new RongIMClient.ConnectCallback() {
    @Override
    public void onDatabaseOpened(RongIMClient.DatabaseOpenStatus code) {
        //消息数据库打开，可以进入到主页面
    }

    @Override
    public void onSuccess(String s) {
        //连接成功
    }

    @Override
    public void onError(RongIMClient.ConnectionErrorCode errorCode) {
        if(errorCode.equals(RongIMClient.ConnectionErrorCode.RC_CONN_TOKEN_INCORRECT)) {
            //从 APP 服务获取新 token，并重连
        } else {
            //无法连接 IM 服务器，请根据相应的错误码作出对应处理
        }
    }
})
已复制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 构建会话列表

创建会话 Activity (以 ConversationListActivity 为例) 以及 Activity 所对应的 xml 布局 (以 activity_conversation_list.xml 为例)
activity_conversation_list.xml 布局中创建 View 容器用于动态添加 ConversationListFragment.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:orientation="vertical"
        android:layout_width="match_parent"
        android:layout_height="match_parent">
        <FrameLayout
            android:id="@+id/container"
            android:layout_width="match_parent"
            android:layout_height="match_parent" />
</LinearLayout>
已复制

1
2
3
4
5
6
7
8
9
10

在 ConversationListActivity 的 onCreate 方法中创建并使用 ConversationListFragment.

class ConversationListActivity extends FragmentActivity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_conversation_list);

        ConversationListFragment conversationListFragment=new ConversationListFragment();
        // 此处设置 Uri. 通过 appendQueryParameter 去设置所要支持的会话类型. 例如
        // .appendQueryParameter(Conversation.ConversationType.PRIVATE.getName(),"false")
        // 表示支持单聊会话, false 表示不聚合显示, true 则为聚合显示
        Uri uri = Uri.parse("rong://" +
                getActivity().getApplicationInfo().packageName).buildUpon()
                .appendPath("conversationlist")
                .appendQueryParameter(Conversation.ConversationType.PRIVATE.getName(), "false") //设置私聊会话是否聚合显示
                .appendQueryParameter(Conversation.ConversationType.GROUP.getName(), "false")//群组
                .appendQueryParameter(Conversation.ConversationType.PUBLIC_SERVICE.getName(), "false")//公共服务号
                .appendQueryParameter(Conversation.ConversationType.APP_PUBLIC_SERVICE.getName(), "false")//订阅号
                .appendQueryParameter(Conversation.ConversationType.SYSTEM.getName(), "true")//系统
                .build();

        conversationListFragment.setUri(uri);
        FragmentManager manager = getSupportFragmentManager();
        FragmentTransaction transaction = manager.beginTransaction();
        transaction.replace(R.id.container, conversationListFragment);
        transaction.commit();

    }
}
已复制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

AndroidManifest.xml 配置 Activity

SDK 内部通过隐式调用的方式来实现跳转到会话列表界面。需在 AndroidManifest.xml 中配置会话列表 ConversationListActivity 下面配置 intent-filter.

必须要给 Activity 配置 intent-filter. 否则使用 IMkit 中启动会话列表的方法将无效.
android:host 的值需填写 App 的 ApplicationId.

<activity
    android:name="xxx.xxx.ConversationListActivity"
    android:screenOrientation="portrait"
    android:windowSoftInputMode="stateHidden|adjustResize">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <data
            android:host="${applicationId}"
            android:pathPrefix="/conversationlist"
            android:scheme="rong" />
    </intent-filter>
</activity>

已复制

1
2
3
4
5
6
7
8
9
10
11
12
13
14

启动会话列表

配置好会话列表后, 可在连接成功后启动会话界面.

supportedConversation 为设置要支持的会话类型.

String 为要支持的会话类型的值, 可通过 ConversationType (opens new window)的 getValue() 方法获取;
Boolean 为当前会话类型是否要支持聚合显示, true 为支持, false 为不支持

Map<String, Boolean> supportedConversation = new HashMap<>();
supportedConversation.put(ConversationType.PRIVATE.getValue(), false);
supportedConversation.put(ConversationType.GROUP.getValue(), false);
supportedConversation.put(ConversationType.SYSTEM.getValue(), true);
RongIM.getInstance().startConversationList(Context , supportedConversation);
已复制

1
2
3
4
5

# 构建会话页面

创建会话 Activity (以 ConversationActivity 为例) 以及 Activity 所对应的 xml 布局 (以 activity_conversation.xml 为例)
activity_conversation.xml 布局中创建 View 容器用于动态添加 ConversationFragment.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:orientation="vertical"
        android:layout_width="match_parent"
        android:layout_height="match_parent">
        <FrameLayout
            android:id="@+id/container"
            android:layout_width="match_parent"
            android:layout_height="match_parent" />
</LinearLayout>
已复制

1
2
3
4
5
6
7
8
9
10

在 ConversationActivity 的 onCreate 方法中创建并使用 ConversationFragment.

ConversationFragment conversationFragment=new ConversationFragment();
FragmentManager manager = getSupportFragmentManager();
FragmentTransaction transaction = manager.beginTransaction();
transaction.replace(R.id.container, conversationFragment);
transaction.commit();
已复制

1
2
3
4
5

AndroidManifest 配置 Activity

SDK 内部通过隐式调用的方式来实现跳转到会话列表界面。需在 AndroidManifest.xml 中配置会话列表 ConversationActivity 下面配置 intent-filter.

Activity 必须配置 intent-filter, 否则将无法正常启动会话页面
android:host 的值需填写 App 的 ApplicationId

<activity
    android:name="xxx.xxx.ConversationActivity"
    android:screenOrientation="portrait"
    android:windowSoftInputMode="stateHidden|adjustResize">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <data
            android:host="${applicationId}"
            android:pathPrefix="/conversation/"
            android:scheme="rong" />
    </intent-filter>
</activity>

已复制

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 设置用户信息

开发者与融云服务器建立连接之后，应该设置用户信息，用于SDK显示和发送。可使用下面方式设置用户信息。可设置缓存用户信息. 当设置 true 后, 优先从缓存中获取用户信息. 更新用户信息, 需调用 RongIM.getInstance().refreshUserInfoCache(userInfo)|

# 同步设置

代码示例

// 是否缓存用户信息. true 缓存, false 不缓存
// 1. <span style="color:red">当设置 true 后, 优先从缓存中获取用户信息.  
// 2. 更新用户信息, 需调用 RongIM.getInstance().refreshUserInfoCache(userInfo)
boolean isCacheUserInfo = true;
RongIM.setUserInfoProvider(new RongIM.UserInfoProvider() {

    /**
     * 获取设置用户信息. 通过返回的 userId 来封装生产用户信息.
     * @param userId 用户 ID
     */
    @Override
    public UserInfo getUserInfo(String userId) {
        UserInfo userInfo = new UserInfo(userId, "userId 对应的名称", Uri.parse("userId 对应的头像地址"))
        return userInfo;
    }

}, isCacheUserInfo);
已复制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 异步设置

在 getUserInfo 方法中返回 null.

// 是否缓存用户信息. true 缓存, false 不缓存
// 1. <span style="color:red">当设置 true 后, 优先从缓存中获取用户信息.  
// 2. 更新用户信息, 需调用 RongIM.getInstance().refreshUserInfoCache(userInfo)
boolean isCacheUserInfo = true;
RongIM.setUserInfoProvider(new RongIM.UserInfoProvider() {

    /**
     * 获取设置用户信息. 通过返回的 userId 来封装生产用户信息.
     * @param userId 用户 ID
     */
    @Override
    public UserInfo getUserInfo(String userId) {
        // 执行异步请求逻辑方法
        return null;
    }

}, isCacheUserInfo);
已复制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

调用刷新方法, 刷新用户信息缓存

UserInfo userInfo = new UserInfo(userId, "userId 对应的名称", Uri.parse("userId 对应的头像地址"))
RongIM.getInstance().refreshUserInfoCache(userInfo);

已复制

1
2
3

文档是否解决您的问题 ?

如果遇到产品相关问题，您可提交工单寻求帮助