实时信令

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

1 前提条件

2 准备开发环境

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

2.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.jocloud.helloword
    • Project location:项目的存储路径
    • Language:项目的编程语言,如 Java
    • Minimum API level:项目的最低 API 等级

2.2 步骤二:引入库文件

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

buildscript {
    repositories {
        google()
        jcenter()

        [更换仓库地址域名 todo]
        maven {url "http://nexus.jocloud.com:8081/nexus/content/groups/public/" }
    }
}

allprojects {
    repositories {
        google()
        jcenter()

        [更换仓库地址域名 todo]
        maven {url "http://nexus.jocloud.com:8081/nexus/content/groups/public/" }
    }
}

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

implementation "com.hummer:hmr:3.1.5"
implementation "com.hummer:rts:3.1.5"

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

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

3 基本操作

本节介绍如何使用SDK提供的基本功能。

3.1 初始化、登录

3.1.1 步骤一:初始化Hummer SDK

在调用 Hummer API 前,需要初始化 Hummer SDK,以保证 SDK 各个组件之间能够初始化完成并且保证SDK能够正常工作。调用 init 方法,即可初始化 Hummer SDK。

// Hummer SDK的初始化方法,关于运行环境的参数,欢迎垂询
// appContext 安卓活动 (Android Activity) 的上下文
// appId 服务平台为应用程序开发者签发的 AppId
// listener   事件监听器
HMR.init(appContext, appId, "", new HMR.HummerEventListener() {
    @Override
    public void onHummerStateChanged(HMR.State fromState, HMR.State toState, String reason) {

    }

    @Override
    public void onHummerKicked(int code, String description) {
                
    }

    @Override
    public void onHummerPreviousTokenExpired() {
                
    }
});

3.1.2 步骤二:登录SDK

由于整个 SDK 依赖于用户登录才能使用,所以需要业务在初始化 SDK 后调用 login 方法告知用户的 uid 以及对应的一些信息保证 SDK 鉴定对应用户的合法性以及建立对应的用户上下文。

// java
// uid 用户 id, uid不能为0
// region 区域配置参数
// token 该参数为鉴定用户合法性的票据
// completion 用于登录 SDK 成功后的回调
HMR.login(uid, region, token, new HMR.Completion() {
    @Override
    public void onSuccess(RequestId requestId) {

    }

    @Override
    public void onFailed(RequestId requestId, final Error err) {

    }
});

3.2 实时信令消息使用方法

信令消息的 API 调用时序见下图:

收发点对点信令消息

sequenceDiagram UserA->>SDK: 构建消息(new Message) UserA->>SDK: 发送消息(PeerService.sendMessage) SDK-->>UserA: completion SDK->>UserB: 收到消息(onPeerMessageReceived) UserB->>SDK: 构建消息(new Message) UserB->>SDK: 发送消息(PeerService.sendMessage) SDK-->>UserB: completion SDK->>UserA: 收到消息(onPeerMessageReceived)

Hummer SDK 提供发送、接收点对点信令消息的API,使用方式如下:

3.2.1 步骤一:添加消息监听器


//当收到点对点信令消息时,会收到该事件的通知回调
// message     收到的信令消息
// fromUserId  发送者

 @Override
 public void onPeerMessageReceived(long fromUserId, Message message) {

 }

3.2.2 步骤二:发送点对点信令消息

Hummer SDK 提供发送点对点信令消息的API,使用方式如下:

// java
// 发送点对点信令消息
// message    需要发送的信令消息
// options    发送消息所需要的配置信息
// uid        信令消息的接受者标识
// completion 发送操作的完成回调
Message message = new Message("10086", text.getBytes(), new HashMap<String, String>(0));

HMR.getService(PeerService.class).sendMessage(Long.valueOf(uid), message, new MessagingOptions(), new HMR.Completion() {
    @Override
    public void onSuccess(RequestId requestId) {

    }

    @Override
    public void onFailed(RequestId requestId, Error err) {
                                                    
    }
});

3.3 房间API使用方法

房间的 API 调用时序见下图:

加入/退出房间

sequenceDiagram App->>SDK: 初始化SDK(init) App->>SDK: 登录SDK(login) SDK-->>App: completion App->>SDK: 加入房间(join) SDK-->>App: completion App->>SDK: 离开房间(leave) SDK-->>App: completion App->>SDK: 登出SDK(logout)

房间内收发消息

sequenceDiagram UserA->>SDK: 构建消息(new Message) UserA->>SDK: 发送消息(RoomService.sendMessage) SDK-->>UserA: completion SDK->>UserB: 收到消息(onRoomMessageReceived) UserB->>SDK: 构建消息(new Message) UserB->>SDK: 发送消息(RoomService.sendMessage) SDK-->>UserB: completionHandler SDK->>UserA: 收到消息(onRoomMessageReceived)

3.3.1 步骤一:加入房间

目前房间支持多端进入,对应具体的配置可以找后台的相关同学进行对应的配置。使用方法 join 可以加入房间,进入房间时可通过传入 extras 参数携带自定义扩展信息、使用 options 参数可传入可选参数

// java
// 进入房间的接口
// roomId        需要进入的房间的标识
// extras        加入房间时可携带的附带属性,业务可以在加入房间时携带一些附带属性
// options       加入房间时可选参数
// completion    回调,业务可以根据对应的加入结果做不同的业务处理,加入失败时也会携带对应的错误原因
HMR.getService(RoomService.class).join(roomId, new HashMap<String, String>(0), null, new HMR.Completion() {
    @Override
    public void onSuccess(RequestId requestId) {

    }

    @Override
    public void onFailed(RequestId requestId, Error err) {

    }
});

3.3.2 步骤二:房间内发送消息

业务可以通过使用 sendMessage 方法发送房间消息,在创建 Message 的对象时可填入对应的消息类型用于区分不同类型的消息,options 可传入相关配置信息,传入roomId 指定在对应房间发送该消息

// java
// 发送房间消息方法
// message       消息
// options       发送消息所需要的配置信息
// roomId        房间标识,标识消息要发送的房间
// completion    发送消息的回调,业务可以根据对应的发送结果做不同的业务逻辑处理
Message message = new Message("1008611", text.getBytes());

HMR.getService(RoomService.class).sendMessage(roomId, message, new MessagingOptions(), new HMR.Completion() {
    @Override
    public void onSuccess(RequestId requestId) {

    }

    @Override
    public void onFailed(RequestId requestId, Error err) {

    }
});

3.3.3 步骤三:接收消息

业务需要注册 RoomEventListener 监听者用于接收房间消息,注册后可以在 didRoomMessageReceived 回调方法中接收并处理接收到的消息对象,该回调方法同时回调该消息的发送者标识及房间标识。

// java
// 当有一个用户往房间内发一条消息时,房间内所有的成员都会受到该事件的通知回调
// message       收到的消息
// fromUserId    成员标识,标识当前消息来自哪位成员
// roomId        房间标识
@Override
public void onRoomMessageReceived(@NonNull RoomId roomId, long fromUserId, Message message) {

}

3.3.4 步骤四:离开房间

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

// java
// 退出房间的接口
// roomId        需要离开的房间的标识
// completion    离开聊天室完成后的回调,业务可以根据对应的离开结果做不同的业务处理,离开失败时也会携带对应的错误原因
HMR.getService(RoomService.class).leave(roomId, new HMR.Completion() {
    @Override
    public void onSuccess(RequestId requestId) {

    }

    @Override
    public void onFailed(RequestId requestId, Error err) {

    }
});

3.4 登出SDK

登出 SDK,用于告知 SDK 当前用户已经退出登录了,保证 SDK 即使回收对应的资源。使用 logout 方法退出登录。

// java
// 登出用户上下文
// 该操作应该在业务进行实际的用户注销(退出登录)之前执行
HMR.logout();

4 API参考

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

5 注意事项

  • 如未有特殊说明,如果相关操作是在主线程调用,则相应的 completion 回调是在主线程中;否则,在SDK内部统一的子线程中回调

文档是否有解决您的问题?

有帮助 没帮助
提交成功,非常感谢您的反馈!

反馈

TOP