聊天室

本文介绍如何快速集成 Hummer ChatRoom SDK Android 版本到项目中的方法

1 Demo体验

下载Demo体验

2 前提条件

3 准备开发环境

本节介绍如何创建项目,并将 Hummer ChatRoom SDK 集成至你的项目中。

3.1 步骤一:创建项目

  1. 打开 Android Studio,点击 Start a new Android Studio project
  2. Choose your project 界面,选择 Phone and Tablet > Empty Activity,然后点击 Next
  3. Configure your project 界面,依次填入以下内容:
    • Name:你的 Android 项目名称,如 HelloWord
    • Package name:你的项目包的名称,如 com.aivacom.helloword
    • Project location:项目的存储路径
    • Language:项目的编程语言,如 Java
    • Minimum API level:项目的最低 API 等级

3.2 步骤二:引入库文件

集成时,请在 Project build.gradle 文件中添加 url source:

buildscript {
    repositories {
        google()
        jcenter()

        maven {url "http://nexus.sunclouds.com:8081/nexus/content/groups/public/" }
    }
}

allprojects {
    repositories {
        google()
        jcenter()

        maven {url "http://nexus.sunclouds.com:8081/nexus/content/groups/public/" }
    }
}

请在模块 build.gradle 文件中增加下述依赖:

implementation "com.hummer.im:core:2.6.107"
implementation "com.hummer.im:chatroom:2.6.107"

代码混淆规则,那么接着在 proguard-rules.pro 文件添加下述代码:

-keep class com.hummer.im.**{*;}
-keepclassmembers class com.hummer.im.** {
   public *;
}

4 聊天室基本操作

本节介绍如何实现聊天室功能。聊天室的 API 调用时序见下图:

登录登出聊天室

sequenceDiagram App->>SDK: 1.初始化SDK(init) App->>SDK: 2.登录SDK(open) SDK-->>App: completion App->>SDK: 3.创建房间(createChatRoom) SDK-->>App: completion App->>SDK: 4.进入聊天室(join) SDK-->>App: completion App->>SDK: 5.离开聊天室(leave) SDK-->>App: completion App->>SDK: 6.退出SDK(close) SDK-->>App: completion

收发消息

sequenceDiagram UserA->>SDK: 发送消息(send) SDK-->>UserA: completion SDK->>UserB: 收到消息(afterReceivingMessage) UserB->>SDK: 发送消息(send) SDK->>UserB: completion SDK->>UserA: 收到消息(afterReceivingMessage)

4.1 步骤一:初始化Hummer SDK

初始化 SDK, 保证 SDK 各个组件之间能够初始化完成保证后续SDK能够正常工作。该接口是一个同步行为,同一个 AppId 的聊天室才能互通。

// content 安卓活动 (Android Activity) 的上下文
// appId 为应用程序开发者签发的 AppId
HMR.init(Demo.appContext(), currentAppId);

4.2 步骤二:登录SDK

由于整个 SDK 依赖于用户登录才能使用,所以需要业务再登录后调用 open 方法告知用户的 uid 以及对应的一些信息保证 SDK 鉴定对应用户的合法性以及建立对应的用户上下文。在鉴定上下文后,也方便之后 SDK 与服务器交互过程中的身份认证。

// uid 当前登录用户的 uid
// region 聊天室所属的区域,目前填入 "china" 即可,方便后期全球化
// tag 该参数为表明用户所属的标签,用于后期消息过滤时使用, 目前可填入空集合
// token 该参数为鉴定用户合法性的票据
// completion 用于登录 SDK 成功后的回调,业务可以根据具体的登录成功或失败来处理对应的业务逻辑
HMR.open(uid, region, null, token, new HMR.Completion() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onFailed(Error err) {

    }
});

4.3 步骤三:创建聊天室

由于聊天室模块的所需的聊天室必须要通过创建才能使用,故需要对应的创建聊天室接口。

// chatRoomInfo 聊天室信息对象,包含名称、描述、公告以及扩展信息
// completion 创建完成后的回调,其中创建成功后会携带对应的聊天室标识返回给业务,用于后面聊天室操作中使用;同时在创建失败后,回调中也携带了对应的失败原因
HMR.getService(ChatRoomService.class).createChatRoom(chatRoomInfo, new HMR.CompletionArg<ChatRoom>() {
    @Override
    public void onSuccess(ChatRoom result) {

    }

    @Override
    public void onFailed(Error error) {

    }
});

4.4 步骤四:加入聊天室

由于目前聊天室只支持单端以及多端进入聊天室,对应具体的配置可以找后台的相关同学进行对应的配置。对于单端进入聊天室则第二个进入聊天室的用户会将第一个进入聊天室的用户踢出聊天室。使用 join 可以加入聊天室。

// chatRoom 需要进入的聊天室的标识
// joinProps 加入聊天室的附带属性,业务可以在加入聊天室时携带一些附带属性
// completion 加入聊天室完成后的回调,业务可以根据对应的加入结果做不同的业务处理,加入失败时也会携带对应的错误原因
HMR.getService(ChatRoomService.class).join(new ChatRoom(ChatRoom chatRoom,new HashMap<String, String>(), new Challenges.JoiningCompletion() {
    @Override
    public void onReceiveChallenge(Challenges.Password challenge) {
    }

    @Override
    public void onReceiveChallenge(Challenges.AppChallenge challenge) {
    }

    @Override
    public void onSucceed() {


    }

    @Override
    public void onFailure(@NonNull Error err) {

    }
});

4.5 步骤五:发送消息

消息通道是一个可以支持多种消息类型的结果,可以通过消息通道发送公屏、单播信令、广播信令。 业务只需要在 Message 的对象中填入对应类型的消息类型既可以。使用 sendMessage 方法可以发送消息。

// message 需要发送的消息对象
// compeltion 发送消息的回调,业务可以根据对应的发送结果做不同的业务逻辑处理
HMR.getService(ChatService.class).send(new Message(new ChatRoom(
long channelId)),new Text(message)), new HMR.Completion() {
		@Override
		public void onSuccess() {

		}

		@Override
		public void onFailed(Error err) {

		}
});

4.6 步骤六:接收消息

可以在 afterReceivingMessage 回调方法中接收消息。在接收到对应的消息后,业务可以根据对应的收到消息的类型以及对应的信息来进行业务处理。

// message 已经收到的消息对象
@Override
public void afterReceivingMessage(@NonNull Message message) {

}

4.7 步骤七:离开房间

在进入聊天室后处理完所有需要处理的逻辑后,可以通过离开聊天室来结束跟聊天室之间的交互,同时也会停止监听聊天室的公屏、信令消息和对应的回调通知。

// chatRoom 需要离开的聊天室的标识
// completion 离开聊天室完成后的回调,业务可以根据对应的离开结果做不同的业务处理,离开失败时也会携带对应的错误原因
HMR.getService(ChatRoomService.class).leave(new ChatRoom(long channelId), new HMR.Completion() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onFailed(Error err) {

    }
});

4.8 步骤八:退出SDK

退出登录 SDK,用于告知 SDK 当前用户已经退出登录了,保证 SDK 及时回收对应的资源。在需要再次使用聊天室等模块的情况下,可以通过 open 再次登录 SDK 即可。该过程是一个异步的操作,故提供了最后一个参数告知退出登录的完成以及对应的结果。 业务需要关注对应的 close 需要在 open 之后才能调用。

// completion 用于退出登录 SDK 完成后的回调,业务可以根据具体的退出登录成功或失败来处理对应的业务逻辑
HMR.close(new HMR.Completion() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onFailed(Error err) {

    }
});

5 API参考

这里写文中涉及的所有api列表。

6 注意事项

<