0基础入门Android端实时聊天

ZEGO 提供 ZIM + RTC 服务联动的场景解决方案，公开语聊房、秀场直播等业务场景搭建的示例源码，帮助开发者能在极短的时间内搭建完美的业务场景。

ZIM SDK 提供了如下接入方案：

在此方案中，您需要通过您自己的业务系统实现以下业务逻辑：

• 搭建客户端的用户管理逻辑，并下发用户 ID 用于客户端登录。
• 鉴权 Token，建议由您的业务后台自行实现，保证鉴权数据安全。

1 前提条件

在使用 ZIM SDK 前，请确保：

开发环境满足以下要求：

• Android Studio 2.1 或以上版本。
• Android SDK 25、Android SDK Build-Tools 25.0.2、Android SDK Platform-Tools 25.x.x 或以上版本。
• Android 9.0 或以上版本，且支持音视频的 Android 设备或模拟器（推荐使用真机）。

已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID 和 ServerSecret。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考 项目管理 - 即时通讯）、或联系 ZEGO 技术支持开通。

已获取登录 SDK 所需的 Token，详情请参考 使用 Token 鉴权。

2 集成 SDK

2.1 新建项目

1. 打开 Android Studio，选择 “File > New > New Project” 菜单。

2. 填写项目名及项目存储路径。

3. 其它按照默认设置，单击 “Next”，最后单击 “Finish” 完成新工程创建。

2.2 导入 SDK

目前支持的平台架构包括：arm64-v8a、armeabi-v7a、x86、x86_64。

开发者可通过以下任意一种方式实现集成 SDK。

方式一：使用 JitPack 自动集成 SDK

1. 进入项目根目录，打开 “build.gradle” 文件，在 “allprojects” 中加入如下代码。

...
allprojects {
    repositories {
        maven { url 'https://www.jitpack.io' }
        google()
        jcenter()
    }
}

2. 进入 “app” 目录，打开 “build.gradle” 文件，在 “dependencies” 中添加 implementation 'com.github.zegolibrary:zim:x.y.z'。“x.y.z” 为 SDK 的版本号，请参考 发布日志 中的发布历史获取。

...
dependencies {
    ...
    // x.y.z 请填写具体版本号，如：1.2.0
    // 可通过 SDK 发布历史取得最新版本号
    implementation 'com.github.zegolibrary:zim:x.y.z'
}

方式二：复制 SDK 文件手动集成

1. 请参考 下载 SDK，下载最新版本的 SDK。

2. 将 SDK 包解压至项目目录下，例如 “app/libs”。

3. 添加 SDK 引用。进入到 “app” 目录，打开 “build.gradle” 文件。

在 “defaultConfig” 节点添加 “ndk” 节点，指定支持的平台类型。

ndk {
    abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86_64', 'x86' 
}

在 “android” 节点添加 “sourceSets” 节点，指定 “libs” 所在目录。

示例代码中 “libs” 目录仅为举例，开发者可根据实际路径填写。

```gradle
sourceSets {
    main {
        jniLibs.srcDirs = ['libs']
    }
}
```

* 在 “dependencies” 节点引入 “libs” 下所有的 jar。  

```gradle
implementation fileTree(dir: 'libs', include: ['*.jar'])
```

2.3 设置权限

开发者可以根据实际应用需要，设置应用所需权限。

进入 “app/src/main” 目录，打开 “AndroidManifest.xml” 文件，添加权限。

<!-- SDK 必须使用的权限 -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

2.4 防止混淆代码

在 “proguard-rules.pro” 文件中，为 SDK 添加 -keep 类的配置，防止混淆 SDK 公共类名称。

-keep class **.zego.**{*;}

3 实现基本收发消息

以下流程中，我们以客户端 A 和 B 的消息交互为例：

3.1 实现流程

请参考 跑通示例源码 获取源码，相关功能的源码请查看 “app/src/main/java/im/zego/zimexample/ui/room/ZIMPeerSessionActivity” 目录下的文件。

1). 导入类文件

在项目文件中引入类文件。

import im.zego.zim.ZIM;

2). 创建 ZIM 实例

首先我们需要在 SDK 中创建 ZIM 实例，一个实例对应的是一个用户，表示一个用户以客户端的身份登录系统。

例如，客户端 A、B 分别调用 create 接口，传入在 2 前提条件 中获取到的 AppID，创建了 A、B 的实例：

// 创建 ZIM 对象，传入 APPID 与 Android 中的 Application
zim = ZIM.create(appID, application);

ZIM 创建单例的示例

由于大多数开发者，在整个流程中，只需要将 ZIM 实例化一次，因此 ZEGO 建议您将 ZIM 单例化并保存。

创建一个 SDKManager 类，在该类中声明并实现了一个 “sharedInstance” 静态方法，该方法将会在首次调用时创建并返回一个 SDKManager 的对象，在该对象中调用 ”create“，此后在项目的任意位置导入 SDKManager 类，调用 “SDKManager.sharedInstance().zim” 将会返回 zim 对象。

public class SDKManager {
    private static SDKManager sdkManager;
    public ZIM zim;

    public static SDKManager sharedInstance() {
        if (sdkManager == null) {
            synchronized (SDKManager.class) {
                if (sdkManager == null) {
                    sdkManager = new SDKManager();
                }
            }
        }
        return sdkManager;
    }

    public void create(Application application) {
        zim = ZIM.create(ZegoAppID.appID, application);
    }
}

3). 设置 setEventHandler 回调

在客户端登录前，开发者可以通过调用 setEventHandler 接口，自定义 ZIM 中的事件回调，接收到 SDK 异常、消息通知回调等的通知。

zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onReceivePeerMessage(ZIM zim, ArrayList<ZIMMessage> messageList, String fromUserID) {
        // 收到“单聊”通信的消息回调
    }
});

4). 登录 ZIM

创建实例后，客户端 A 和 B 需要登录 ZIM，只有登录成功后才可以开始发送、接收消息、更新 Token 等。

客户端需要使用各自的用户信息和 Token 进行登录。调用 login 接口进行登录，传入用户信息 ZIMUserInfo 对象，以及在 2 前提条件 中获取到的 Token 进行鉴权，鉴权通过后才能登录成功。

• “userID”、“userName” 支持开发者自定义规则生成。建议开发者将 “userID” 设置为一个有意义的值，可将其与自己的业务账号系统进行关联。
• 如果 Token 过期，需要在 tokenWillExpire 即将过期回调接口中，调用 renewToken 接口，更新 Token 后才能正常使用 SDK。

// 登录时，需要开发者 按照 "使用 Token 鉴权" 文档生成 token 即可
// userID 和 userName，最大 32 字节的字符串。仅支持数字，英文字符 和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', '/', '\'。
ZIMUserInfo zimUserInfo = new ZIMUserInfo();
zimUserInfo.userID = userID;
zimUserInfo.userName = userName;
zim.login(zimUserInfo, token, new ZIMLoggedInCallback() {
    @Override
    public void onLoggedIn(ZIMError error) {
          // 开发者可根据 ZIMError 来判断是否登录成功。          
    }
 });

5). 发送单聊消息

客户端 A 登录成功后，可以向客户端 B 发送消息。

目前 ZIM 支持的消息类型如下：

消息类型	说明	特性及适用场景
ZIMTextMessage(1)	文本消息。消息大小不超过 32 KB，单个客户端发送频率限制为 10 次/秒。	消息可靠有序，可存储为历史消息；一般适用于“单聊”、“群聊”等即时聊天的场景。
ZIMCommandMessage(2)	开发者可自定义数据类型的信令消息。消息大小不超过 5 KB，单个客户端发送频率限制为 10 次/秒。	支持更高的并发；一般适用于“语聊房”、“在线课堂”等房间内的即时聊天；房间解散后，消息不保存。
ZIMBarrageMessage(20)	房间内弹幕文本消息。消息大小不超过 5 KB，单个客户端发送频率无限制。	专门用于房间内的高频、不可靠、允许丢掉的消息，一般适用于发送“弹幕消息”的场景中。 支持高并发，但不可靠，不保证消息送达。

客户端 A 可以调用 sendPeerMessage 接口，传入客户端 B 的 userID、消息内容等信息，即可发送一条消息到 B 的客户端，同时可以通过 onMessageSent 接口的回调信息，判断消息是否发送成功。

// 发送“单聊”通信的信息

String toUserID = "xxxx";

ZIMTextMessage zimMessage = new ZIMTextMessage();
zimMessage.message = "消息内容";

ZIMMessageSendConfig config = new ZIMMessageSendConfig();
// 消息优先级，取值为 低:1 默认,中:2,高:3
config.priority = ZIMMessagePriority.LOW;
// 设置消息的离线推送配置
ZIMPushConfig pushConfig = new ZIMPushConfig();
pushConfig.title = "离线推送的标题";
pushConfig.content= "离线推送的内容";
pushConfig.extendedData = "离线推送的扩展信息";
config.pushConfig = pushConfig;

zim.sendPeerMessage(zimMessage, toUserID, config, new ZIMMessageSentCallback() {
    @Override
    public void onMessageSent(ZIMMessage zimMessage, ZIMError error) {
        // 开发者可以通过该回调监听消息是否发送成功。
    }
});

6). 接收单聊消息

客户端 B 登录 ZIM 后，将会收到在 setEventHandler 回调中设置的 onReceivePeerMessage 监听接口，收到客户端 A 发送过来的消息。

收到消息时，由于类型是基类，首先需要判断消息类型是 Text 还是 Command，开发者需要强转基类为具体的子类，然后从 message 字段获取消息内容。

zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onReceivePeerMessage(ZIM zim, ArrayList<ZIMMessage> messageList, String fromUserID) {

      for (ZIMMessage zimMessage : messageList) {
          if (zimMessage instanceof ZIMTextMessage) 
          {
            ZIMTextMessage zimTextMessage = (ZIMTextMessage) zimMessage;
            Log.e(TAG, "收到的消息:"+ zimTextMessage.message);
          }   
      }
   }
});

7). 退出登录

如果客户端需要退出登录，直接调用 logout 接口即可。

zim.logout();

8). 销毁 ZIM 实例

如果不需要 ZIM 实例，可直接调用 destroy 接口，销毁实例。

zim.destroy();

3.2 API 时序图

通过以上的实现流程描述，API 接口调用时序图如下：

获取更多ZEGO SDK技术支持：

• ZIM不仅具备全平台互动、消息海量并发、合规安全可靠等产品特性。同时还可结合即构 RTC
  SDK实现各类音视频场景的用户互动，满足Avatar , 直播，语聊房等实时互动场景。
• 七周年福利：提交表单联系商务，有机会获取即构IM1个月免费试用。；