简体中文
  • 简体中文
  • English
实时消息服务
产品类别 实时消息服务 聊天室 客户端API Android

实时消息产品SDK的代号为 Hummer。

  • HMR 接口类提供了 SDK 初始化登录以及配置的功能。
  • ChatRoomService 接口类提供了对应的聊天室管理的调用接口。
  • ChatService 接口类提供了消息发送的通道，可以用于发送对应的公屏、信令广播和信令单播。

HMR

getState

获取SDK当前状态，详见 State。

public static State getState()
返回

SDK当前状态。

init

public static void init(@NonNull final Context appContext, final long appId)

初始化Hummer。

注意：

Hummer 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

参数
参数描述
appContext上下文环境
appId用于标识具体业务, 目前需要和 Hummer 服务提供方通过人工申请

open

public static void open(final long uid,
                  @NonNull final String region,
                  @Nullable final Set<String> tags,
                  @NonNull final String token,
                  @Nullable final Completion completion)

登录SDK,同时开始监听服务器消息以及拉取对应消息数据

参数
参数描述
uid用户id, uid 不能为0
region需要连接服务器所处的环境参数，详情咨询相关SDK开发人员
tags保留字段，暂时可以填空集合
token用于服务初始化时所需的用户凭证
completion结果回调，详见 Completion

close

public static void close(@Nullable final Completion completion)

登出SDK

注意：

  • 登出SDK是一个异步操作
  • 应该在completion回调中处理错误的情况
参数
参数描述
completion结果回调，详见 Completion

refreshToken

public static void refreshToken(@NonNull final String token)

刷新用户凭证

注意：

该方法已弃用，请改用 refreshToken1。

说明：

当收到 didHummerTokenWillExpire （Token即将过期）或 didHummerPreviousTokenExpired （Token过期）回调时，需重新 生成Token，并调用该API刷新Token；否则Token过期后，SDK和服务器会断开连接，导致房间不可用。

参数
参数描述
token待刷新的用户凭证

refreshToken

public static void refreshToken(@NonNull final String token,
																@Nullable final Completion completion)

废弃

注意：

该方法已弃用，请改用 refreshToken1。

刷新用户凭证

参数
参数描述
token待刷新的用户凭证
completion结果回调，详见 Completion

refreshToken1

public static void refreshToken1(@NonNull final String token,
								@Nullable final Completion completion)

刷新Token。

Token具有时效性，当收到 onHummerTokenWillExpired（Token即将过期）或 onHummerPreviousTokenExpired（Token过期）回调时，客户端需重新调用该API刷新Token；否则Token过期后，SDK与服务器会断开连接，导致服务中断。

参数
参数描述
token待刷新的Token
completion结果回调：0-成功，其他-失败，详见 错误码
注意事项
  • API调用频率为2 次/s，超时时间为15s，接口调用超过频率限制或超时时间，会返回错误码。
  • Token刷新成功，会触发 onConnectionStateChanged（SDK连接状态改变回调），连接状态变为 Connected。
  • Token刷新失败，系统会主动断开SDK与服务器的连接，并触发 onConnectionStateChanged（SDK连接状态改变回调），连接状态变为 Reconnecting，直至刷新成功。

setLoggerFilePath

public static boolean setLoggerFilePath(@NonNull String loggerPath)

自定义日志存储路径。

参数
参数描述
path日志存储路径（存在且可写），格式为：JoLogs/Hummer，默认路径为data/data/{package_name}/cache
返回
  • true：成功
  • false：失败
注意事项
  • 请勿直接使用根目录当日志路径。
  • 需要设置的日志存储路径，调用方应确保路径存在。
  • 建议在SDK初始化后调用该API，为保证日志完整性，不建议频繁调用该方法。

setLogLevel

public static boolean setLogLevel(HMRLogLevel logLevel)

设置SDK日志输出优先级别，默认为 VERBOSE。

日志级别分为6个级别，由低到高为：VERBOSE < DEBUG < INFO < WARNING < ERROR < RELEASE。SDK会输出当前以及高于当前设置的日志级别的日志。例如，设置的日志级别为 INFO，则将会输出 INFO、WARNING、 和 RELEASE 级别的日志，低于 INFO 级别的 VERBOSE 和 DEBUG 的日志不会被输出。

参数
参数描述
logLevel日志等级，详见 HMRLogLevel
返回
  • true：成功。
  • false：失败。

setLogCallback

public static boolean setLogCallback(HMRLogCallback callback)

注册日志输出回调来输出日志。

调用该方法设置 logger，SDK 会将日志的输出和打印交给SDK接入方来处理，接入方需要保证日志的上报，用于后期故障定位排查。

参数
参数描述
callbackSDK 日志输出回调，详见 HMRLogCallback
返回)
  • true：成功。
  • false：失败。

uploadLogsManually

public static boolean uploadLogsManually(String remark)

上传日志至服务治理平台的日志管理后台。

参数
参数描述
remark上报时的备注信息
返回
  • true：成功。
  • false：失败。

createTextMessage

public static TextMessage createTextMessage(String text)

创建文本消息对象 TextMessage ，用于发送文本消息。

参数
参数描述
text备注信息
返回

创建的文本消息对象 TextMessage。

sendP2PMessage

public static void sendP2PMessage(@NonNull User receiver,
                                  @NonNull BaseMessage message,
                                  P2PMessageOptions options,
                                  HMR.Completion completion)

发送点对点消息（P2P）。

用户登录 Hummer 系统后，可通过该接口给其他用户发送点对点文本消息，发送后会触发 onP2PTextMessageReceived 消息回调，消息目标用户可通过监听 onP2PTextMessageReceived 接收该文本消息。

参数
参数描述
message消息对象，目前仅支持 TextMessage（文本消息对象，由 createTextMessage 创建 ）
user该条消息的接收者，详见 User
options发送消息所需要的配置信息，目前可配置该消息是否支持离线功能，详见 P2PMessageOptions ，业务可通过设置参数 options 的 isOffline 字段 ，控制该次发送的消息是否开启离线功能，该功能默认关闭。
completion结果回调（Completion）：0-成功，其他-失败，详见 错误码
注意事项
  • 调用该接口发送文本消息前，需先调用 createTextMessage 创建 TextMessage 对象。
  • 登录 Hummer 系统即可调用该接口，操作者和接收者均无任何是否在通道内/房间内限制。
  • 单个用户调用频率限制：180次/3秒。
  • 每个接收端最多保存 200 条离线消息，最长保存七天。当保存的离线消息超出限制时，最新消息将覆盖最老消息。

fetchUserOnlineStatus

public static void fetchUserOnlineStatus(@NonNull Set<User> users,
                                         HMR.CompletionArg<Set<UserOnlineStatus>> completion)

查询用户在线状态。

用户登录过 Hummer 系统后，系统会维护一份当前用户在线状态信息，当前登录在线的用户会返回在线，登出下线的用户会返回不在线状态。

参数
参数描述
users目标用户ID列表，不能超过200 个，详见 User
completion结果回调（Completion）：0-成功，并携带用户的对应在线状态（UserOnlineStatus）、其他-失败，详见 错误码
注意事项
  • 单个用户调用频率限制：10次/5s。
  • 单次最多查询200个用户的在线状态。

addStateListener

public static void addStateListener(@NonNull final StateListener listener)

添加 SDK 状态变更监听器

参数
参数描述
listener待添加的监听器，详见 StateListener

removeStateListener

public static void removeStateListener(@NonNull final StateListener listener)

移除 SDK 状态变更监听器

参数
参数描述
listener待移除的监听器，详见 StateListener

addTokenInvalidListener

public static void addTokenInvalidListener(@NonNull final TokenInvalidListener listener)

添加 token过期监听器

参数
参数描述
listener待添加的监听器，详见 TokenInvalidListener

removeTokenInvalidListener

public static void removeTokenInvalidListener(@NonNull final TokenInvalidListener listener)

移除 token 过期监听器

参数
参数描述
listener待移除的监听器，详见 TokenInvalidListener

addHummerListener

public static void addHummerListener(@NonNull final HummerListener listener)

添加 HummerListener 监听器用于监听 HMR 类接口的事件、获取相关数据。例如Token即将过期、SDK与服务器连接状态等。

参数
参数描述
listenerHummerListener 监听器

removeHummerListener

public static void removeHummerListener(@NonNull final HummerListener listener)

移除 HummerListener 监听器。

参数
参数描述
listenerHummerListener 监听器

getVersion

public static String getVersion()

获取 SDK 版本信息

返回
  • SDK版本信息

getService

public static <Service> Service getService(@NonNull Class<Service> serviceClass)

获取服务实例

返回

服务实例

getConnectionState

public static ConnectionState getConnectionState() {

获取当前连接状态，详见 ConnectionState。

返回

SDK当前连接状态

ChannelStateService

getState

public ChannelState getState()

获取当前连接状态，详见 ChannelState

废弃

注意：

该方法已弃用，请改用 getConnectionState。

返回

SDK当前连接状态

addChannelStateListener

public void addChannelStateListener(@NonNull ChannelStateListener listener)

废弃

注意：

该方法已弃用，请改用 addHummerListener。

添加 连接 状态变更监听器

参数
参数描述
listener待添加的监听器，详见 ChannelStateListener

removeChannelStateListener

public void removeChannelStateListener(@NonNull ChannelStateListener listener)

废弃

注意：

该方法已弃用，请改用 removeHummerListener。

移除 连接 状态变更监听器

参数
参数描述
listener待移除的监听器，详见 ChannelStateListener

ChatRoomService

setRegion

void setRegion(String region);

设置聊天室区域

注意：

  • 需要在使用聊天室相关功能之前调用设置
  • 未设置将默认中国区域
参数
参数描述
region聊天室区域

createChatRoom

void createChatRoom(@NonNull ChatRoomInfo chatRoomInfo,
                    @NonNull CompletionArg<ChatRoom> completion);

创建聊天室

注意：

  • 由于聊天室模块的所需的聊天室必须要通过创建才能使用，故需要对应的创建聊天室接口。
  • 在创建聊天室完成后，服务器会返回对应的聊天室标识，用于后续在使用聊天室时的标识。
  • 同时在创建聊天室时需要提供对应的聊天室信息，如名称、描述、公告以及扩展信息等。
参数
参数描述
chatRoomInfo聊天室信息对象，包含名称、描述、公告以及扩展信息 ，详见 ChatRoomInfo
completion结果回调，详见 CompletionArg
- 成功：本地用户收到回调 onSuccess。
- 失败：本地用户收到回调 onFailed。错误码详见 Code

dismissChatRoom

void dismissChatRoom(@NonNull ChatRoom chatRoom,
                     @Nullable Completion completion);

解散聊天室

注意：

  • 销毁时需要提供对应的聊天室标识用于服务器识别对应的聊天室，并正常销毁。
  • 销毁需要 Owner 权限
  • 单个用户调用频率限制：10次/5s
参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
completion结果回调，详见 CompletionArg
- 成功：本地用户收到回调 onSuccess。
- 失败：本地用户收到回调 onFailed。错误码详见 Code

join

void join(@NonNull ChatRoom chatRoom,
          @NonNull Map<String, String> joinProps,
          @NonNull Challenges.JoiningCompletion completion);

加入聊天室

注意：

  • 对应聊天室操作都需要进入聊天室之后才能正常的操作，如发公屏、发信令以及接受信令都要进入聊天室之后才能正常处理。

  • 加入聊天室会涉及多端互踢的逻辑，相关互踢逻辑请咨询后台配置。

  • 单个用户进入聊天室：10次/5s

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
joinProps扩展字段，用于业务扩展，SDK 只负责透传
completion结果回调 JoiningCompletion
- 成功：本地用户收到回调 onSucceed。
- 失败：本地用户收到回调 onFailure。错误码详见 Code

leave

void leave(@NonNull ChatRoom chatRoom, @Nullable Completion completion);

退出聊天室

注意：

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

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
completion结果对象 Completion
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

kick

void kick(@NonNull ChatRoom chatRoom,
          @NonNull User member,
          @Nullable Map<EKickInfo, String> extraInfo,
          @NonNull Completion completion);

将用户踢出聊天室

说明

该接口从 v2.15.0 开始废弃，相关功能请使用 kickUser 代替。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
member踢出的聊天室成员，详见 User
extraInfo踢人的额外信息。key值详见 EKickInfo
目前支持的Key主要是两个：
1. Reason, 用于携带踢人原因的 Key， 其 Key 对应的 Value 只需填写对应的踢人原因的字符串即可；
2. Time 用于携带限制时长的 Key(单位:秒)， 其 Key 对应的 Value 只需要填写踢人限制时长的秒数转换成字符串即可, 这些字段都是透传字段，服务器不做处理
completion结果对象 Completion
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

kickUser

void kickUser(@NonNull ChatRoom chatRoom,
              @NonNull User user,
              Map<String, String> extraInfo,
              KickUserOptions options,
              HMR.Completion completion);

把聊天室内用户踢出聊天室。

踢人成功后，聊天室内所有用户会收到通知 onMemberCountChanged、onChatRoomMemberLeave，被踢用户同时会收到通知 onUserKicked。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
user需要踢出聊天室的用户，详见 User
extraInfo踢人的额外信息，目前支持的Key是 Reason， 用于携带踢人原因的 Key， 其 Key 对应的 Value 只需填写对应的踢人原因的字符串即可
options预留字段，详见 KickUserOptions
completion结果回调 Completion ：0-成功，其他-失败，详见 错误码
注意事项
  • 执行踢人操作时，操作者和被操作者均需要在指定聊天室内。
  • 聊天室管理员 admin 角色只能踢普通用户，不能踢 admin 和 owner。
  • 聊天室创建者 owner 可以踢聊天室管理员 admin、普通用户。
  • 单次调用只能指定一个用户，不支持批量操作。
  • 单个用户调用频率限制：10次/5s。

addRole

void addRole(@NonNull ChatRoom chatRoom,
             @NonNull User member,
             @NonNull String role,
             @NonNull Completion completion);

添加聊天室权限角色。

说明

  • 该接口从 v2.15.0 开始已废弃，有相关需求请改用 setUserRole。
参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
member被添加角色的聊天室成员，详见 User
role角色类型,目前只能填写 Admin，详情见 Roles
completion结果对象 Completion
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

setUserRole

void setUserRole(@NonNull ChatRoom chatRoom,
                 @NonNull User user,
                 @NonNull String role,
                 RoleOptions options,
                 HMR.Completion completion);

设置聊天室用户角色。

角色属性在整个聊天室生命周期内固定存在，即使用户退出了该聊天室，该用户的角色属性仍然存在，除非该聊天室销毁。调用成功后会触发设置聊天室用户角色通知 onUserRoleSet。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
user被添加角色的聊天室成员，详见 User
role角色类型，当前仅支持 admin
options预留字段，详见 RoleOptions
completion结果回调 Completion ：0-成功，其他-失败，详见 错误码
注意事项
  • 单个聊天室内，最多可以指定 10 个 Admin 用户。
  • 只有 Owner 才可以指定 Admin，且 Owner 指定 Admin 时，可以不在聊天室内，被操作者必须在聊天室内。
  • Owner 不能设置自己为 Admin。
  • 一个用户只能被指定为一个角色，不能同时存在多个角色。
  • 目前只能设置 Admin。
  • 单个用户调用频率限制：10次/5s。

removeRole

void removeRole(@NonNull ChatRoom chatRoom,
                @NonNull User member,
                @NonNull String role,
                @NonNull Completion completion);

移除聊天室权限角色。

说明

该接口从 v2.15.0 开始已废弃，有相关需求请改用 deleteUserRole。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
member被移除角色的聊天室成员，详见 User
role角色类型, 目前只能填写 Admin，详情见 Roles
completion结果对象 Completion
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

deleteUserRole

void deleteUserRole(@NonNull ChatRoom chatRoom,
                    @NonNull User user,
                    RoleOptions options,
                    HMR.Completion completion);

删除用户的角色。

调用成功会触发聊天室用户角色被删通知 onUserRoleDeleted。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
user被移除角色的用户，详见 User
options预留字段，详见 RoleOptions
completion结果回调（Completion）：0-成功，其他-失败，详见 错误码
注意事项
  • 只有 Owner 有权限删除指定用户的角色。
  • 单个用户调用频率限制：10次/5s。

fetchMembers

void fetchMembers(@NonNull ChatRoom chatRoom, 
                  int num, 
                  int offset,
                  @NonNull CompletionArg<List<User>> completion);

获取聊天室在线用户列表

注意：

  • 由于一些场景下，一个聊天室的内的用户可能有十几万，故聊天室 SDK 提供了对应的按需分页获取用户的结果。同时也会按照一定的默认规则来进行排序对应的用户列表。
  • 获取用户列表的接口，可以在不进入聊天室时也可以获取。
  • 单个用户调用频率限制：10次/5s
参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
num设置每页的返回成员数（建议不超过200）
offset第几页 (第一页从0开始)
completion结果回调（CompletionArg）
成功：返回 onSuccess
失败：返回 onFailed，原因详见 错误码

fetchRoleMembers

void fetchRoleMembers(@NonNull ChatRoom chatRoom, 
                      boolean online,
                      @NonNull CompletionArg<Map<String, List<User>>> completion);

获取聊天室带有角色的用户列表

说明

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
online是否只获取在线的成员：
true：只获取在线的、有角色的列表
false：获取所有带有角色的成员列表
completion结果回调（CompletionArg）
成功：返回 onSuccess
失败：返回 onFailed，原因详见 错误码

fetchUserRole

void fetchUserRole(@NonNull ChatRoom chatRoom,
                   @NonNull User user,
                   HMR.CompletionArg<String> completion);

获取用户在目标聊天室的角色信息。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
user指定查询的聊天室用户，详见 User
completion结果回调（CompletionArg）
成功：返回 onSuccess
失败：返回 onFailed，原因详见 错误码
注意事项

单个用户调用频率限制：10次/5s。

fetchRoomUsersByRole

void fetchRoomUsersByRole(@NonNull ChatRoom chatRoom,
                          String role,
                          HMR.CompletionArg<Map<String, List<User>>> completion);

根据用户角色获取用户列表。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
role用户角色
null 表示查询所有当前在房间内的所有带角色的用户列表
completion结果回调（CompletionArg）
成功：返回 onSuccess
失败：返回 onFailed，原因详见 错误码
注意事项
  • 单个用户调用频率限制：10次/5s
  • 返回的只是创建者 owner、管理员 admin 角色列表，不支持返回普通用户列表。

fetchBasicInfo

void fetchBasicInfo(@NonNull ChatRoom chatRoom,
                    @NonNull CompletionArg<ChatRoomInfo> completion);

获取聊天室基本属性信息。

注意：

  • 获取聊天室信息可以获取到对应聊天室的名称、描述、公告以及对应的扩展字段信息。
  • 获取聊天室信息无需进入聊天室也可以获取。
  • 单个用户调用频率限制：10次/5s
参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
completion结果回调（CompletionArg）
成功：返回 onSuccess
失败：返回 onFailed，原因详见 错误码

fetchRoomBasicAttributes

void fetchRoomBasicAttributes(@NonNull ChatRoom chatRoom,
                              Set<String> keys,
                              HMR.CompletionArg<FetchRoomBasicAttributesResult> completion);

获取指定聊天室的基本属性信息。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
keys属性值，key-value键值对
key 值仅支持： Name-名称、Description-描述、Bulletin-公告
value 最大长度为8k
completion结果回调（Completion）：0-成功，其他-失败，详见 错误码
注意事项
  • 无角色限制，任何用户均可以执行查询房间基础属性操作。
  • 无在聊天室内限制，任何用户均可以执行查询房间基础属性操作。
  • 单个用户调用频率限制：10次/5s。

fetchChatRoomInfo

void fetchChatRoomInfo(@NonNull ChatRoom chatRoom,
                       @Nullable CompletionArg<Map<String, String>> completion);

获取聊天室全部属性信息

说明

该接口从 v2.14.0 开始已废弃删除，有相关需求请改用 fetchBasicInfo 、fetchRoomExtraAttributes

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
completion结果回调（CompletionArg）
成功：返回 onSuccess 和 对应的 聊天室信息
失败：返回 onFailed，原因详见 错误码

fetchMemberCount

void fetchMemberCount(@NonNull ChatRoom chatRoom,
                      @NonNull CompletionArg<Integer> completion);

获取聊天室人数。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
completion结果回调（Completion）：0-成功，其他-失败，详见 错误码

changeBasicInfo

void changeBasicInfo(@NonNull ChatRoom chatRoom,
                     @NonNull Map<ChatRoomInfo.BasicInfoType, String> propInfo,
                     @NonNull Completion completion);

变更聊天室基本属性信息

注意：

  • 可以修改一个或多个属性，只需要在参数中指定需要修改的聊天室信息的键值对即可。
  • 需要 Admin 或者 Owner 的角色。角色定义详见：Roles。
  • 单个用户调用频率限制：10次/5s
参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
propInfo修改的属性值，其中key值参见枚举详见：BasicInfoType
completion结果回调（CompletionArg）
成功：返回 onSuccess 和 对应的 聊天室信息
失败：返回 onFailed，原因详见 错误码

updateRoomBasicAttributes

void updateRoomBasicAttributes(@NonNull ChatRoom chatRoom,
                               @NonNull Map<String, String> attributes,
                               RoomBasicAttributesOptions options,
                               HMR.Completion completion);

更新聊天室基本信息。

调用该接口成功后会触发通知 onRoomBasicAttributesUpdated。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
attributes属性值，key-value键值对
key 值仅支持： Name-名称、Description-描述、Bulletin-公告
value 最大长度为8k
options预留字段，详见 RoomBasicAttributesOptions
completion结果回调（Completion）：0-成功，其他-失败，详见 错误码
注意事项
  • 操作者需要在该聊天室房间内。
  • 仅 owner 和 admin 权限的用户才可以执行该操作。
  • 单个用户调用频率限制：10次/5s。

addOrUpdateChatRoomInfo

void addOrUpdateChatRoomInfo(@NonNull ChatRoom chatRoom,
                             @NonNull Map<String, String> infoMap,
                             @Nullable Completion completion);

更新指定聊天室的属性。

说明

该接口从 v2.14.0 开始已废弃删除，有相关需求请改用 setRoomExtraAttributes 、updateRoomExtraAttributes

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
infoMap修改的属性值，可自定义
completion结果回调（Completion）：0-成功，其他-失败，详见 错误码

setRoomExtraAttributes

void setRoomExtraAttributes(@NonNull ChatRoom chatRoom,
                            @NonNull Map<String, String> attributes,
                            @Nullable ChatRoomAttributeOptions options,
                            @Nullable HMR.Completion completion);

设置房间扩展属性。

调用该接口会触发房间扩展属性回调 onRoomExtraAttributesSet。

参数
参数描述
attributes扩展属性，由 key-value组成
key：单个属性 Key 最大32字节，不能为空
value：单个属性value最大8KB，可以为空
chatRoom聊天室标识符，详见 ChatRoom
options预留参数，详见 ChatRoomAttributeOptions
completion结果回调（Completion）：0-成功，其他-失败，详见 错误码
注意事项
  • 单个房间最多支持32个扩展属性。
  • 仅 Owner 和 Admin 用户有权限设置房间扩展属性，且操作者需要在该房间内。
  • 单个用户调用频率限制：10次/5s。

updateRoomExtraAttributes

void updateRoomExtraAttributes(@NonNull ChatRoom chatRoom,
                               @NonNull Map<String, String> attributes,
                               @Nullable ChatRoomAttributeOptions options,
                               @Nullable HMR.Completion completion);

更新房间扩展属性。

当属性（key）不存在时，代表增加属性； 当属性（key）已经存在时，代表更新属性。调用该接口会触发onRoomExtraAttributesUpdated 回调。

参数
参数描述
attributes扩展属性，由 key-value组成
key：单个属性 Key 最大32字节，不能为空
value：单个属性value最大8KB，可以为空
chatRoom房间标识符，详见 ChatRoom
options预留参数 ChatRoomAttributeOptions
completion结果回调（Completion）：0-成功，其他-失败，详见 错误码
注意事项
  • 单个房间最多支持32个扩展属性。
  • 仅 Owner 和 Admin 用户有权限更新房间扩展属性，且操作者需要在该房间内。
  • 单个用户调用频率限制：10次/5s。

deleteRoomExtraAttributes

void deleteRoomExtraAttributes(@NonNull ChatRoom chatRoom,
                               @NonNull Set<String> keys,
                               @Nullable ChatRoomAttributeOptions options,
                               @Nullable HMR.Completion completion);

删除指定房间扩展属性。

用户传入目标属性 key值集合，该接口仅删除key值集合所对应的属性，不能传入空key值集合，调用该接口会触发 onRoomExtraAttributesDeleted 回调。

参数
参数描述
keys要删除的属性 key 集合，不能为空，单个 Key 最大为32字节
chatRoom聊天室标识符，详见 ChatRoom
options预留参数，详见 ChatRoomAttributeOptions
completion结果回调（Completion）：0-成功，其他-失败，详见 错误码
注意事项
  • 仅 Owner 和 Admin 用户有权限执行该操作。
  • 操作者需要在该房间内。

clearRoomExtraAttributes

void clearRoomExtraAttributes(@NonNull ChatRoom chatRoom,
                              @Nullable ChatRoomAttributeOptions options,
                              @Nullable HMR.Completion completion);

清空房间扩展属性。

不需要传入任何key值或属性值，该接口会直接清空目标房聊天室的所有属性，调用该接口会触发 onRoomExtraAttributesCleared 回调。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
options预留参数 ChatRoomAttributeOptions
completion结果回调（Completion）：0-成功，其他-失败，详见 错误码
注意事项
  • 仅 Owner 和 Admin 用户有权限执行该操作。
  • 操作者需要在该房间内。

fetchRoomExtraAttributes

void fetchRoomExtraAttributes(@NonNull ChatRoom chatRoom,
                              @Nullable Set<String> keys,
                              @Nullable HMR.CompletionArg<ChatRoomExtraAttribute> completion);

查询指定房间的扩展属性。

所有用户无论是否已加入房间均有权限执行该操作。

参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
keys要查询的属性 key 集合
默认为空，表示查询全量属性
单个属性 Key 最大32字节
completion结果回调（Completion）：0-成功，其他-失败，详见 错误码

fetchHistoryMessages

void fetchHistoryMessages(@NonNull ChatRoom chatRoom,
                          @NonNull FetchingParams params,
                          CompletionArg<FetchingResult> completion);

获取公屏历史消息。

注意事项：

  • 历史消息存储时间限制一个月。
  • 无进入聊天室限制，无权限角色限制，所有用户均可调用该接口。
  • 单次查询结果最大支持100条，最少1条。
  • 单个用户调用频率限制：10次/5s。
参数
参数描述
chatRoom聊天室标识符，详见 ChatRoom
params消息拉取条件，具体参数详见：FetchingParams
completion结果对象 Completion
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

muteMember

void muteMember(@NonNull ChatRoom chatRoom,
                @NonNull User member,
                @Nullable String reason,
                @NonNull Completion completion);

禁言聊天室内的用户

注意：

  • 业务可以根据对应的需要禁言某个用户，目前后台默认的禁言时间为三天，到期自动解禁。
  • 禁言需要 Admin 或者 Owner 的角色， Owner 可以禁言聊天室内的所有人包括 Admin, 而 Admin 则只可以禁言普通用户。角色定义详见：Roles。
  • 禁言的用户需要在聊天室内。
  • 单个用户调用频率限制：10次/5s
参数
参数描述
chatRoom成员所在的聊天室
member需要禁言的成员
reason禁言的原因
completion结果对象 Completion
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

unmuteMember

void unmuteMember(@NonNull ChatRoom chatRoom,
                  @NonNull User member,
                  @Nullable String reason,
                  @NonNull Completion completion);

解禁聊天室内的用户

注意：

  • 解禁的用户需要在聊天室内
  • 解除禁言需要 Admin 或者 Owner 的角色， Owner 可以解禁聊天室内的所有人包括 Admin, 而 Admin 则只可以解禁普通用户。角色定义详见：Roles。
  • 单个用户调用频率限制：10次/5s
参数
参数描述
chatRoom成员所在的聊天室
member需要解禁言的成员
reason解禁言的原因
completion结果对象 Completion
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

fetchMutedUsers

void fetchMutedUsers(@NonNull ChatRoom chatRoom, 
                     @NonNull CompletionArg<Set<User>> completion);

获取聊天室内的禁言列表

注意：

  • 获取的禁言列表里面的有些用户可能不存在聊天室内
  • 单个用户调用频率限制：10次/5s
参数
参数描述
chatRoom需要获取禁言列表的聊天室
completion结果对象 CompletionArg
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

isMuted

void isMuted(@NonNull ChatRoom chatRoom,
             @NonNull User member,
             @NonNull CompletionArg<Boolean> completion);

判别某一个用户是否在聊天室的禁言列表里

注意：

单个用户调用频率限制:10次/5s

参数
参数描述
chatRoom需要判别的聊天室
member需要判别的用户
completion结果对象 CompletionArg
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

setUserInfo

void setUserInfo(@NonNull final ChatRoom chatRoom,
                 @NonNull final Map<String, String> infoMap,
                 @Nullable final Completion completion);

设置自己的用户信息

注意：

  • 容量上限：
    设置用户属性，最大支持属性个数：32个
    单个用户属性的最大值:8k
  • 单个用户调用频率限制：10次/5s
参数
参数描述
chatRoom成员所在的聊天室
infoMap待设置用户信息
completion结果对象 CompletionArg
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

deleteUserInfoByKeys

void deleteUserInfoByKeys(@NonNull ChatRoom chatRoom,
                          @NonNull Set<String> keys,
                          @Nullable Completion completion);

删除自己的用户信息

注意：

  • 容量上限：
    用户属性，最大支持属性个数：32个
    单个用户属性的最大值:8k
  • 单个用户调用频率限制:10次/5s
参数
参数描述
chatRoom成员所在的聊天室
keys待删除信息的key
completion结果对象 Completion
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

addOrUpdateUserInfo

void addOrUpdateUserInfo(@NonNull ChatRoom chatRoom,
                         @NonNull Map<String, String> infoMap,
                         @Nullable Completion completion);

添加或更新指定用户信息。

注意：

属性信息存在则更新；不存在则添加。

参数
参数描述
chatRoom成员所在的聊天室
infoMap属性信息
completion设置信息返回的回调，可以根据错误码进行处理

fetchUserInfo

void fetchUserInfo(@NonNull ChatRoom chatRoom,
                   @NonNull User member,
                   @NonNull CompletionArg<Map<String, String>> completion

获取指定用户的用户信息。

参数
参数描述
chatRoom成员所在的聊天室
member目标用户
completion结果对象 CompletionArg
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

batchFetchUserInfos

void batchFetchUserInfos(@NonNull ChatRoom chatRoom,
                         @NonNull Set<User> users,
                         @Nullable CompletionArg<Map<User, Map<String, String>>> completion);

批量获取指定用户的用户信息

参数
参数描述
chatRoom成员所在的聊天室
users目标用户（批量）
completion设置信息返回的回调，可以根据错误码进行处理

fetchOnlineUserInfoList

void fetchOnlineUserInfoList(@NonNull ChatRoom chatRoom,
                             @NonNull CompletionArg<Map<User, Map<String, String>>> completion);

获取聊天室已设置用户信息的在线用户列表

注意：

获取的人员列表最多返回100个，超过100个的随机返回100个。

参数
参数描述
chatRoom待查询聊天室
completion结果对象 CompletionArg
- 方法调用成功：本地用户收到回调 onSuccess。
- 方法调用失败：本地用户收到回调 onFailed。错误码详见 Code

addListener

void addListener(@NonNull final ChatRoomListener listener);

添加聊天室回调监听器

参数
参数描述
listener监听器对象，详见 ChatRoomListener

removeListener

void removeListener(@NonNull final ChatRoomListener listener);

移除聊天室回调监听器

参数
参数描述
listener监听器对象，详见 ChatRoomListener

addMemberListener

void addMemberListener(@NonNull final MemberListener listener);

添加聊天室用户回调监听器

参数
参数描述
listener监听器对象，详见 MemberListener

removeMemberListener

void removeMemberListener(@NonNull final MemberListener listener);

移除聊天室用户的回调监听器

参数
参数描述
listener监听器对象，详见 MemberListener

ChannelService

getInstance

public static ChannelService getInstance()

获取 ChannelService 实例

返回
  • 返回 ChannelService 实例

joinChannel

public abstract void joinChannel(@NonNull ChannelId channelId,
                                 ChannelJoiningOptions options,
                                 HMR.Completion completion)

加入消息通道 （Channel）。

调用该接口加入指定的底层消息通道，并由 Hummer系统后台直接创建。

参数
参数描述
channelId消息通道ID ，由 [A,Z]、[a,z]、[0,9]、-、_ 组成，最大长度为 64 字节，详见 ChannelId
options预留参数，详见 ChannelJoiningOptions
completionHandler结果回调（Completion）：0-成功，其他-失败，详见 错误码
注意事项
  • 单个用户同时最多支持加入20 个通道。
  • 对应 Channel 操作都需要进入 Channel 之后才能正常的操作，如发送通道内广播消息以及接收通道内广播都要进入Channel 之后才能正常处理。

leaveChannel

public abstract void leaveChannel(@NonNull ChannelId channelId,
                                  HMR.Completion completion);

退出消息通道 （Channel）。

离开通道后，将不能继续接收通道内的广播消息。

参数
参数描述
channelId消息通道ID ，由 [A,Z]、[a,z]、[0,9]、-、_ 组成，最大长度为 64 字节，详见 ChannelId
completionHandler结果回调（Completion）：0-成功，其他-失败，详见 错误码

sendP2CMessage

public abstract void sendP2CMessage(@NonNull ChannelId channelId,
                                    @NonNull BaseMessage message,
                                    P2CMessageOptions options,
                                    HMR.Completion completion);

在通道（ Channel ）内发送广播消息。

在已加入的 Channel 内发送广播消息，发送后会触发 onP2CTextMessageReceived 消息回调，通道内用户均能通过监听 onP2CTextMessageReceived 接收到该消息。

参数
参数描述
message消息对象，仅支持 TextMessage（文本消息对象，由 createTextMessage 创建 ）
channelId消息通道ID ，由 [A,Z]、[a,z]、[0,9]、-、_ 组成，最大长度为 64 字节，详见 ChannelId
options预留参数，可不填，详见 P2CMessageOptions
completionHandler结果回调（Completion）：0-成功，其他-失败，详见 错误码
注意事项
  • 单个用户调用频率限制：90 次/3秒。
  • 仅已加入通道的用户，才能往该通道发送广播消息。
  • 离开通道后，将不能继续接收通道内的广播消息。

ChatService

send

void send(@NonNull Message message, @Nullable Completion completion);

发送公屏（仅支持文本）、单播、广播消息，消息内容详情见 Content。

说明：

  • 业务可以通过自己构造消息体，并且填写对应的消息内容将该消息发送出去。
  • 该接口也可以在消息发送失败的情况下进行重发消息。
  • 单个用户调用频率限制：
    发送公屏消息：10次/5s
    发送自定义单播消息：50次/5s
    发送自定义广播消息：50次/5s
  • 单条消息最大长度：
    单播：2k
    广播：2k
    公屏：1200字节
  • 消息的拓展字段kvExtra最多32个
  • 对于单播、广播]，如果message的appExtra填了值，会默认加入到kvExtra中作为一个单独的key-value，即自定义的kvExtra的最大个数变为31个
参数
参数描述
message消息实例，详见 Message
completion发送操作的完成回调

回调

completion回调只处理了最终完成回调，但消息发送过程中可能会有多个阶段/状态。可以通过监听MessageListener来得到相应的回调。

addMessageListener

void addMessageListener(@Nullable Identifiable target, @NonNull MessageListener listener);

添加一个消息收发监听器

参数
参数描述
target需要监听消息收发的消息对象，详见 Identifiable
listener需要增加的listener对象

removeMessageListener

void removeMessageListener(@Nullable Identifiable target, @NonNull MessageListener listener);

移除一个消息收发监听器

参数
参数描述
target需要取消监听消息收发的消息对象，详见 Identifiable
listener需要移除的listener对象

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

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

反馈

TOP