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

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

image

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

  • 搭建客户端的用户管理逻辑,并下发用户 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” 菜单。

image

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

image

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”。

image

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

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

image

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

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

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

image

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

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

image

```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 的消息交互为例:
image

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 接口调用时序图如下:

image

获取更多ZEGO SDK技术支持:

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