public 静态函数 | 方法签名 |
---|---|
void | init(Context appContext, long appId, String appVersion, HummerEventListener listener) |
RequestId | login(long uid, String region, String token, HMR.Completion completion) |
getService(Class | |
RequestId | logout() |
State | getState() |
String | getVersion() |
RequestId | refreshToken(String token, HMR.Completion completion) |
boolean | setLoggerFilePath(String loggerPath) |
public static void init(@NonNull final Context appContext,
final long appId,
final String appVersion,
@NonNull final HummerEventListener listener)
Hummer SDK的初始化方法
注意:
- Hummer 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。
参数 | 描述 |
---|---|
appContext | 上下文环境 |
appId | 用于标识具体业务, 目前需要和 Hummer 服务提供方通过人工申请,详情见 获取AppID |
appVresion | 当前应用版本,主要用于数据统计和应用查障 |
listener | 事件监听器 HummerEventListener |
public static RequestId login(final long uid,
@NonNull final String region,
@NonNull final String token,
@Nullable final HMR.Completion completion)
切换至指定用户的工作上下文,该方法应该在上层业务的用户登录操作完成之后执行
参数 | 描述 |
---|---|
uid | 用户id, uid 不能为0 |
region | 需要连接服务器所处的环境参数,详情咨询相关SDK开发人员 |
token | 用户凭证,用于服务鉴权 |
completion | 该操作的异步回调,详见 HMR.Completion |
public static <Service> Service getService(@NonNull Class<Service> serviceClass)
获取服务实例
参数 | 描述 |
---|---|
serviceClass | 服务实例对应的类 |
public static RequestId logout()
登出SDK
注意:
- 该操作应该在业务进行实际的用户注销(退出登录)之前执行
public static State getState()
获取SDK当前状态,详见 HMR.State
SDK当前状态
public static String getVersion()
获取 SDK 版本信息
public static RequestId refreshToken(@NonNull final String token,
@Nullable final HMR.Completion completion);
刷新用户凭证
参数 | 描述 |
---|---|
token | 待刷新的用户凭证 |
completion | 该操作的异步回调,详见 HMR.Completion |
public static boolean setLoggerFilePath(@NonNull String loggerPath)
需要设置的日志存储路径,调用方应确保路径存在
注意:
- 请勿直接设置为系统根目录!
参数 | 描述 |
---|---|
loggerPath | 需要设置的日志存储路径 |
RequestId queryUserOnlineStatus(@NonNull Set<Long> userIds,
@Nullable HMR.CompletionArg<Map<Long, Boolean>> completion);
批量查询用户在线,可以查询具体用户是否在线
参数 | 描述 |
---|---|
userIds | 需要查询是否在线的用户ID列表 |
completion | 该操作的异步回调,详见 HMR.CompletionArg |
RequestId sendMessage(final long toUserId,
@NonNull final Message message,
@NonNull final MessagingOptions options,
@Nullable HMR.Completion completion);
发送点对点信令消息
注意:
- 单条消息最大限制32KB,消息的extras字段限制最多8个key-value,每个key最大32B,value最大1KB
- key 只能由
a-zA-Z0-9_-
字符组成
参数 | 描述 |
---|---|
toUsedId | 信令消息的接收者标识 |
message | 需要发送的信令消息,详见 Message |
options | 发送消息所需要的配置信息, 预留字段,详见 MessagingOptions |
completion | 该操作的异步回调,详见 HMR.Completion |
RequestId addEventListener(EventListener listener);
添加信令消息的监听器
参数 | 描述 |
---|---|
listener | 需要添加的监听器. 详见 EventListener |
RequestId removeEventListener(EventListener listener);
移除信令消息的监听器
参数 | 描述 |
---|---|
listener | 需要移除的监听器. 详见 EventListener |
RequestId join(@NonNull RoomId roomId,
@Nullable Map<String, String> appExtras,
@Nullable RoomJoiningOptions options,
@Nullable HMR.Completion completion);
进入房间的接口
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
appExtras | 加入房间时的扩展信息 |
options | 加入房间时可选参数,详见 RoomJoiningOptions |
completion | 该操作的异步回调,详见 HMR.Completion |
RequestId leave(@NonNull RoomId roomId, @Nullable HMR.Completion completion);
退出房间的接口
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
completion | 该操作的异步回调,详见 HMR.Completion |
RequestId queryMemberCounts(@NonNull final Set<String> roomIds,
@NonNull String roomRegion,
@Nullable HMR.CompletionArg<Map<RoomId, Integer>> completion);
批量查询房间成员总数
注意:
- 最大同时查询20个房间
- 不支持房间跨区域查询
参数 | 描述 |
---|---|
roomIds | 操作指定的房间标识列表,详见 RoomId.ID |
roomRegion | 房间区域,详见 RoomId.region |
completion | 该操作的异步回调,详见 HMR.CompletionArg |
RequestId queryMembers(@NonNull RoomId roomId,
@Nullable HMR.CompletionArg<List<Long>> completion);
获取指定房间的成员列表
注意:
- 当房间超过500人时候,随机返回500人
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
completion | 该操作的异步回调,详见 HMR.CompletionArg |
RequestId setRoomAttributes(@NonNull RoomId roomId,
@NonNull final Map<String, String> attributes,
@Nullable final RoomAttributeOptions options,
@Nullable HMR.Completion completion);
设置房间属性
注意:
- 支持进房间和不进房间全量设置房间属性
- 房间持续大约10分钟无人的时候,清空房间属性
- 每个属性最大8KB 每个房间最多有32条属性
- 不建议属性设置最大个数和每个属性都设置最大容量,如果都达到峰值有可能引发获取不到属性值的问题
- 设置房间属性的时候Key不能为空(返回错误),Value可以为空
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
attributes | 属性 |
options | 预留字段,详见 RoomAttributeOptions |
completion | 该操作的异步回调,详见 HMR.CompletionArg |
RequestId addOrUpdateRoomAttributes(@NonNull RoomId roomId,
@NonNull final Map<String, String> attributes,
@Nullable final RoomAttributeOptions options,
@Nullable HMR.Completion completion);
添加或者更新指定房间的属性
注意:
- 属性存在则更新;属性不存在则添加
- 房间持续大约10分钟无人的时候,清空房间属性
- 每个属性最大8KB 每个房间最多有32条属性
- 不建议属性设置最大个数和每个属性都设置最大容量,如果都达到峰值有可能引发获取不到属性值的问题
- 设置房间属性的时候Key不能为空(返回错误),Value可以为空
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
attributes | 属性 |
options | 预留字段,详见 RoomAttributeOptions |
completion | 该操作的异步回调,详见 HMR.Completion |
RequestId deleteRoomAttributes(@NonNull RoomId roomId,
@NonNull final Set<String> keys,
@Nullable final RoomAttributeOptions options,
@Nullable HMR.Completion completion);
删除指定房间的指定属性
注意:
- 如果指定房间属性存在并成功删除, 返回成功
- 如果指定房间属性不存在, 返回成功
- 如果指定的房间属性部分存在部分不存在, 返回成功
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
keys | 属性key |
options | 预留字段,详见 RoomAttributeOptions |
completion | 该操作的异步回调,详见 HMR.Completion |
RequestId clearRoomAttributes(@NonNull RoomId roomId,
@Nullable final RoomAttributeOptions options,
@Nullable HMR.Completion completion);
清空指定房间属性
注意:
- 房间持续大约10分钟无人的时候,会自动清空房间属性
- 如果指定房间未设置属性或不存在,返回成功
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
options | 预留字段,详见 RoomAttributeOptions |
completion | 该操作的异步回调,详见 HMR.Completion |
RequestId queryRoomAttributesByKeys(@NonNull RoomId roomId,
@NonNull final Set<String> keys,
@Nullable HMR.CompletionArg<Map<String, String>> completion);
查询指定房间的指定属性
注意:
- 属性keys:对应的单个key不能为空
- 如果查询的属性不存在,返回成功, 但是结果为空
- 如果查询的属性部分存在部分不存在,则只返回存在的属性值
- 如果指定房间属性从未设置过或已超时被清除,但未再次设置的, 返回成功,结果为空
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
keys | 属性 keys |
completion | 该操作的异步回调,详见 HMR.CompletionArg |
RequestId queryRoomAttributes(@NonNull RoomId roomId,
@Nullable HMR.CompletionArg<Map<String, String>> completion);
查询指定房间的全部属性
注意:
- 如果指定房间属性从未设置过或已超时被清除,但未再次设置的, 返回成功,结果为空
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
completion | 该操作的异步回调,详见 HMR.CompletionArg |
RequestId setMemberAttributes(@NonNull final RoomId roomId,
final long userId,
@NonNull final Map<String, String> attributes,
@Nullable final MemberAttributeOptions options,
@Nullable HMR.Completion completion);
设置当前用户在当前房间的属性
注意:
- 目前只支持设置自己的属性
- 单个用户属性的最大值为 8 KB,最多数目为 32 个,
- 不建议属性设置最大个数和每个属性都设置最大容量,如果都达到峰值有可能引发获取不到属性值的问题
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
userId | 操作指定的成员标识 |
attributes | 属性 |
options | 属性可选项,预留,详见 MemberAttributeOptions |
completion | 该操作的异步回调,详见 HMR.Completion |
RequestId addOrUpdateMemberAttributes(@NonNull final RoomId roomId,
final long userId,
@NonNull final Map<String, String> attributes,
@Nullable final MemberAttributeOptions options,
@Nullable HMR.Completion completion);
新增或更新用户在当前房间的用户属性
注意:
- 属性已经存在则更新,不存在则新增
- 目前只支持设置自己的用户属性
- 单个用户属性的最大值为 8 KB,最多数目为 32 个
- 不建议属性设置最大个数和每个属性都设置最大容量,如果都达到峰值有可能引发获取不到属性值的问题
- 可以批量添加或更新本地用户的多个属性
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
userId | 用户标识 |
attributes | 属性 |
options | 属性可选项,预留,详见 MemberAttributeOptions |
completion | 该操作的异步回调,详见 HMR.Completion |
RequestId deleteMemberAttributes(@NonNull final RoomId roomId,
final long userId,
@NonNull final Set<String> keys,
@Nullable final MemberAttributeOptions options,
@Nullable HMR.Completion completion);
删除用户在当前房间的某些用户属性
注意:
- 目前只支持删除自己的用户属性
- 当部分用户属性删除成功, 部分用户属性不存在的时候,都返回成功
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
userId | 用户标识 |
keys | 属性keys |
options | 属性可选项,预留,详见 MemberAttributeOptions |
completion | 该操作的异步回调,详见 HMR.Completion |
RequestId clearMemberAttributes(@NonNull final RoomId roomId,
final long userId,
@Nullable final MemberAttributeOptions options,
@Nullable HMR.Completion completion);
清空用户在房间内的所有属性
注意:
- 目前只支持清空自己的用户属性
- 如果指定用户未设置属性,返回成功
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
userId | 用户标识 |
options | 属性可选项,预留,详见 MemberAttributeOptions |
completion | 该操作的异步回调,详见 HMR.Completion |
RequestId queryMemberAttributesByKeys(@NonNull final RoomId roomId,
final long userId,
@NonNull final Set<String> keys,
@Nullable HMR.CompletionArg<Map<String, String>> completion);
查看用户在当前房间指定属性
注意:
- 如果查询的属性不存在,则返回成功,结果为空
- 如果查询的属性部分存在部分不存在,则存在的只返回成功, 结果为存在的属性
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
userId | 用户标识 |
keys | 属性 keys |
completion | 该操作的异步回调,详见 HMR.CompletionArg |
RequestId queryMemberAttributes(@NonNull final RoomId roomId,
final long userId,
@Nullable HMR.CompletionArg<Map<String, String>> completion);
查看用户在当前房间所有属性
注意:
- 如果用户没有设置任何属性,返回成功,结果为空
参数 | 描述 |
---|---|
roomId | 操作指定的房间标识,详见 RoomId |
userId | 用户标识 |
completion | 该操作的异步回调,详见 HMR.CompletionArg |
RequestId sendMessage(@NonNull RoomId roomId,
@NonNull Message message,
@NonNull MessagingOptions options,
@Nullable HMR.Completion completion);
发送房间消息
注意:
- 单条消息最大限制32KB,消息的extras字段限制最多8个key-value,每个key最大32B,value最大1KB
- key 只能由
a-zA-Z0-9_-
字符组成
参数 | 描述 |
---|---|
roomId | 房间标识,详见 RoomId |
message | 要发送的消息,详见 Message |
options | 发送消息所需要的配置信息,详见 MessagingOptions |
completion | 该操作的异步回调,详见 HMR.Completion |
RequestId addMemberEventListener(MemberEventListener listener);
添加Member的监听器
参数 | 描述 |
---|---|
listener | 需要添加的监听器对象. 详见 MemberEventListener |
RequestId removeMemberEventListener(MemberEventListener listener);
移除Member的监听器
参数 | 描述 |
---|---|
listener | 需要移除的监听器对象. 详见 MemberEventListener |
RequestId addRoomEventListener(RoomEventListener listener);
添加Room的监听器
参数 | 描述 |
---|---|
listener | 需要添加的监听器对象. 详见 RoomEventListener |
RequestId removeRoomEventListener(RoomEventListener listener);
移除Room的监听器
参数 | 描述 |
---|---|
listener | 需要移除的监听器对象. 详见 RoomEventListener |
public enum State { }
SDK 当前状态
枚举值 | 含义 |
---|---|
Disconnected | 未连接 |
Connecting | 连接中 |
Reconnecting | 重连中 |
Connectedsed | 已连接 |
/**
* 操作处理完成后的回调接口
*/
public interface Completion {
void onSuccess(RequestId requestId);
void onFailed(RequestId requestId, Error err);
}
/**
* 操作处理完成后的回调接口,带回调参数,具体参数视具体场景而定
*/
public interface CompletionArg<Argument> {
void onSuccess(RequestId requestId, Argument arg);
void onFailed(RequestId requestId, Error err);
}
/**
* RequestId 实体
*/
public class RequestId {
private String id;
public RequestId(Long val) {
id = String.valueOf(val);
}
public String getId() {
return id;
}
@Override
public String toString() {
return getId();
}
}
/**
* 消息实体
*/
public class Message {
/**
* 消息类型
*/
private String type;
/**
* 消息数据
*/
private byte[] content;
/**
* 扩展信息
*/
private Map<String, String> extras;
public Message(final String type, final byte[] content) {
this.type = type;
this.content = content;
}
public Message(final String type, final byte[] content, final Map<String, String> extras) {
this.type = type;
this.content = content;
this.extras = extras;
}
public String getType() {
return type;
}
public byte[] getContent() {
return content;
}
public Map<String, String> getExtras() {
return extras;
}
}
/**
* 消息选项实体,预留参数
*/
public class MessagingOptions {
}
/**
* 房间标识实体
*/
public class RoomId {
/**
* id只能由 [a-zA-Z0-9_-] 字符组成; 最大为64字节
*/
private String id;
private String region;
public RoomId(@NonNull String id) {
this.id = id;
}
public RoomId(@NonNull String id, @NonNull String region) {
this.id = id;
this.region = region;
}
public String getId() {
return id;
}
public String getRegion() {
if (region != null) {
return region;
}
// 如果用户没有设置默认区域,则会使用Hummer.login接口中填写的用户登录区域。
// 即:显示设置的区域 > login时指定的区域 > 默认
if (HMRContext.region != null) {
return HMRContext.region.area;
}
return HMRContext.Region.AREA_CN;
}
}
/**
* 加入房间时可选项实体,预留参数
*/
public class RoomJoiningOptions {}
/**
* 房间属性可选项实体,预留参数
*/
public class RoomAttributeOptions {}
/**
* 房间成员属性可选项实体,预留参数
*/
public class MemberAttributeOptions {}