聚联云-开发者中心

接口列表

public 静态函数	方法签名
void	init(Context appContext, long appId, String appVersion, HummerEventListener listener)
RequestId	login(long uid, String region, String token, HMR.Completion completion)
Service	getService(Class serviceClass)
RequestId	logout()
State	getState()
String	getVersion()
RequestId	refreshToken(String token, HMR.Completion completion)
boolean	setLoggerFilePath(String loggerPath)
boolean	setLogLevel(HMRLogLevel level)
boolean	setLogCallback(HummerLogCallback callback)
boolean	uploadLogsManually(String remark)

PeerService

public 成员函数	方法签名
RequestId	sendMessage(long toUserId, Message message, MessagingOptions options, HMR.Completion completion)
RequestId	queryUserOnlineStatus(Set userIds, HMR.CompletionArg<Map<Long, Boolean>> completion)
RequestId	addEventListener(EventListener listener)
RequestId	removeEventListener(EventListener listener)

RoomService

注意：房间属性、房间成员属性增删改的接口可以通过options可选参数实例指定是否下发广播通知给房间内其他成员

public 成员函数	方法签名
RequestId	join(RoomId roomId, Map<String, String> appExtras, RoomJoiningOptions options, HMR.Completion completion)
RequestId	leave(RoomId roomId, HMR.Completion completion)
RequestId	queryMemberCounts(RoomId roomId, String roomRegion, HMR.CompletionArg<Map<RoomId, Integer>> completion)
RequestId	queryMembers(RoomId roomId, HMR.CompletionArg<Map<RoomId, Integer>> completion)
RequestId	setRoomAttributes(RoomId roomId, Map<String, String> attributes, RoomAttributeOptions options, HMR.Completion completion)
RequestId	addOrUpdateRoomAttributes(RoomId roomId, Map<String, String> attributes, RoomAttributeOptions options, HMR.Completion completion)
RequestId	deleteRoomAttributes(RoomId roomId, Set keys, RoomAttributeOptions options, HMR.Completion completion)
RequestId	clearRoomAttributes(RoomId roomId, RoomAttributeOptions options, HMR.Completion completion)
RequestId	queryRoomAttributesByKeys(RoomId roomId, Set keys, HMR.CompletionArg<Map<String, String>> completion)
RequestId	queryRoomAttributes(RoomId roomId, HMR.CompletionArg<Map<String, String>> completion)
RequestId	setMemberAttributes(RoomId roomId, Map<String, String> attributes, MemberAttributeOptions options, HMR.Completion completion)
RequestId	addOrUpdateMemberAttributes(RoomId roomId, long userId, Map<String, String> attributes, MemberAttributeOptions options, HMR.Completion completion)
RequestId	deleteMemberAttributes(RoomId roomId, long userId, Set keys, MemberAttributeOptions options, HMR.Completion completion)
RequestId	clearMemberAttributes(RoomId roomId, long userId, MemberAttributeOptions options, HMR.Completion completion)
RequestId	queryMemberAttributes(RoomId roomId, long userId, HMR.CompletionArg<Map<String, String>> completion)
RequestId	queryMemberAttributesByKeys(RoomId roomId, long userId, Set keys, HMR.CompletionArg<Map<String, String>> completion)
RequestId	sendMessage(RoomId roomId, Message message, MessagingOptions options, HMR.Completion completion)
RequestId	addRoomEventListener(RoomEventListener listener)
RequestId	removeRoomEventListener(RoomEventListener listener)
RequestId	addMemberEventListener(MemberEventListener listener)
RequestId	removeMemberEventListener(MemberEventListener listener)

接口详细说明

HMR

HMR.init

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

HMR.login

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

RequestId：递增的一个请求标识，主要用于查障。

HMR.getService

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

获取服务实例

参数

参数	描述
serviceClass	服务实例对应的类

Service 服务实例

HMR.logout

public static RequestId logout()

登出SDK

注意：

该操作应该在业务进行实际的用户注销（退出登录）之前执行

RequestId：递增的一个请求标识，主要用于查障。

HMR.getState

public static State getState()

获取SDK当前状态,详见 HMR.State

SDK当前状态

HMR.getVersion

public static String getVersion()

获取 SDK 版本信息

SDK版本信息

HMR.refreshToken

public static RequestId refreshToken(@NonNull final String token,
                                     @Nullable final HMR.Completion completion);

刷新用户凭证

参数

参数	描述
token	待刷新的用户凭证
completion	该操作的异步回调，详见 HMR.Completion

RequestId：递增的一个请求标识，主要用于查障。

HMR.setLoggerFilePath

public static boolean setLoggerFilePath(@NonNull String loggerPath)

需要设置的日志存储路径，调用方应确保路径存在

注意：

请勿直接设置为系统根目录！

参数

参数	描述
loggerPath	需要设置的日志存储路径

操作结果

HMR.setLogLevel

public static boolean setLogLevel(HMRLogLevel level)

设置日志输出级别

参数

参数	描述
HMRLogLevel	日志等级，详见 HMRLogLevel

操作结果

HMR.setLogCallback

public static boolean setLogCallback(HummerLogCallback callback)

设置日志输出回调

参数

参数	描述
HummerLogCallback	日志输出回调，详见 HummerLogCallback

操作结果

HMR.uploadLogsManually

public static boolean uploadLogsManually(String remark)

手动上报日志

参数

参数	描述
remark	上报时的备注信息

操作结果

PeerService

PeerService.queryUserOnlineStatus

RequestId queryUserOnlineStatus(@NonNull Set<Long> userIds,
                                @Nullable HMR.CompletionArg<Map<Long, Boolean>> completion);

批量查询用户在线，可以查询具体用户是否在线

参数

参数	描述
userIds	需要查询是否在线的用户ID列表
completion	该操作的异步回调，详见 HMR.CompletionArg

RequestId：递增的一个请求标识，主要用于查障。

PeerService.sendMessage

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：递增的一个请求标识，主要用于查障。

PeerService.addEventListener

RequestId addEventListener(EventListener listener);

添加信令消息的监听器

参数

参数	描述
listener	需要添加的监听器. 详见 EventListener

RequestId：递增的一个请求标识，主要用于查障。

PeerService.removeEventListener

RequestId removeEventListener(EventListener listener);

移除信令消息的监听器

参数

参数	描述
listener	需要移除的监听器. 详见 EventListener

RequestId：递增的一个请求标识，主要用于查障。

RoomService

RoomService.join

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：递增的一个请求标识，主要用于查障。

RoomService.leave

RequestId leave(@NonNull RoomId roomId, @Nullable HMR.Completion completion);

退出房间的接口

参数

参数	描述
roomId	操作指定的房间标识，详见 RoomId
completion	该操作的异步回调，详见 HMR.Completion

RequestId：递增的一个请求标识，主要用于查障。

RoomService.queryMemberCounts

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：递增的一个请求标识，主要用于查障。

RoomService.queryMembers

RequestId queryMembers(@NonNull RoomId roomId,
                        @Nullable HMR.CompletionArg<List<Long>> completion);

获取指定房间的成员列表

注意：

当房间超过500人时候，随机返回500人

参数

参数	描述
roomId	操作指定的房间标识，详见 RoomId
completion	该操作的异步回调，详见 HMR.CompletionArg

RequestId：递增的一个请求标识，主要用于查障。

RoomService.setRoomAttributes

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：递增的一个请求标识，主要用于查障。

RoomService.addOrUpdateRoomAttributes

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：递增的一个请求标识，主要用于查障。

RoomService.deleteRoomAttributes

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：递增的一个请求标识，主要用于查障。

RoomService.clearRoomAttributes

RequestId clearRoomAttributes(@NonNull RoomId roomId,
                              @Nullable final RoomAttributeOptions options,
                              @Nullable HMR.Completion completion);

清空指定房间属性

注意：

房间持续大约10分钟无人的时候，会自动清空房间属性

如果指定房间未设置属性或不存在，返回成功

参数

参数	描述
roomId	操作指定的房间标识，详见 RoomId
options	可选项，详见 RoomAttributeOptions
completion	该操作的异步回调，详见 HMR.Completion

RequestId：递增的一个请求标识，主要用于查障。

RoomService.queryRoomAttributesByKeys

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：递增的一个请求标识，主要用于查障。

RoomService.queryRoomAttributes

RequestId queryRoomAttributes(@NonNull RoomId roomId,
                              @Nullable HMR.CompletionArg<Map<String, String>> completion);

查询指定房间的全部属性

注意：

如果指定房间属性从未设置过或已超时被清除，但未再次设置的，返回成功，结果为空

参数

参数	描述
roomId	操作指定的房间标识，详见 RoomId
completion	该操作的异步回调，详见 HMR.CompletionArg

RequestId：递增的一个请求标识，主要用于查障。

RoomService.setMemberAttributes

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：递增的一个请求标识，主要用于查障。

RoomService.addOrUpdateMemberAttributes

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：递增的一个请求标识，主要用于查障。

RoomService.deleteMemberAttributes

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：递增的一个请求标识，主要用于查障。

RoomService.clearMemberAttributes

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：递增的一个请求标识，主要用于查障。

RoomService.queryMemberAttributesByKeys

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：递增的一个请求标识，主要用于查障。

RoomService.queryMemberAttributes

RequestId queryMemberAttributes(@NonNull final RoomId roomId,
                                final long userId,
                                @Nullable HMR.CompletionArg<Map<String, String>> completion);

查看用户在当前房间所有属性

注意：

如果用户没有设置任何属性，返回成功，结果为空

参数

参数	描述
roomId	操作指定的房间标识，详见 RoomId
userId	用户标识
completion	该操作的异步回调，详见 HMR.CompletionArg

RequestId：递增的一个请求标识，主要用于查障。

RoomService.sendMessage

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：递增的一个请求标识，主要用于查障。

RoomService.addMemberEventListener

RequestId addMemberEventListener(MemberEventListener listener);

添加Member的监听器

参数

参数	描述
listener	需要添加的监听器对象. 详见 MemberEventListener

RequestId：递增的一个请求标识，主要用于查障。

RoomService.removeMemberEventListener

RequestId removeMemberEventListener(MemberEventListener listener);

移除Member的监听器

参数

参数	描述
listener	需要移除的监听器对象. 详见 MemberEventListener

RequestId：递增的一个请求标识，主要用于查障。

RoomService.addRoomEventListener

RequestId addRoomEventListener(RoomEventListener listener);

添加Room的监听器

参数

参数	描述
listener	需要添加的监听器对象. 详见 RoomEventListener

RequestId：递增的一个请求标识，主要用于查障。

RoomService.removeRoomEventListener

RequestId removeRoomEventListener(RoomEventListener listener);

移除Room的监听器

参数

参数	描述
listener	需要移除的监听器对象. 详见 RoomEventListener

RequestId：递增的一个请求标识，主要用于查障。

枚举 & 参考类

HMR

HMR.State

public enum State { }

SDK 当前状态

枚举值	含义
Disconnected	未连接
Connecting	连接中
Reconnecting	重连中
Connectedsed	已连接

HMR.HMRLogLevel

public enum HMRLogLevel {
    /**
    * 输出所有级别日志
    */
    HMR_LOG_LEVEL_TRACE(0),

    /**
    * 输出调试信息及以上级别日志
    */
    HMR_LOG_LEVEL_DEBUG(1),

    /**
    * 输出关键信息及以上级别日志
    */
    HMR_LOG_LEVEL_INFO(2),

    /**
    * 输出告警信息及以上级别日志
    */
    HMR_LOG_LEVEL_WARNING(3),

    /**
    * 输出错误信息及以上级别日志
    */
    HMR_LOG_LEVEL_ERROR(4);
}

HMR.Completion

/**
 * 操作处理完成后的回调接口
 */
public interface Completion {
    void onSuccess(RequestId requestId);
    void onFailed(RequestId requestId, Error err);
}

HMR.CompletionArg

/**
 * 操作处理完成后的回调接口，带回调参数，具体参数视具体场景而定
 */
public interface CompletionArg<Argument> {
    void onSuccess(RequestId requestId, Argument arg);
    void onFailed(RequestId requestId, Error err);
}

HMR.HummerLogCallback

public interface HummerLogCallback {
    /**
    * 日志输出回调，设置此回调后，日志信息将通过此接口回调
    *
    * @param level 待输出日志级别
    * @param msg   待输出日志内容
    */
    void onHmrLogWithLevel(HMRLogLevel level, String msg);
}

RequestId

/**
 * 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();
    }
}

PeerService

Message

/**
 * 消息实体
 */
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;
    }
}

MessagingOptions

/**
 * 消息选项实体，预留参数
 */
public class MessagingOptions {

}

RoomService

RoomId

/**
 * 房间标识实体
 */
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;
    }
}

RoomJoiningOptions

/**
 * 加入房间时可选项实体，预留参数
 */
public class RoomJoiningOptions {}

RoomAttributeOptions

/**
 * 房间属性可选项实体，预留参数
 */
public class RoomAttributeOptions {
     /**
      * 是否通知：默认不通知
      */
    private boolean enableNotification = false;

    public boolean getEnableNotification() {
        return enableNotification;
    }

    public RoomAttributeOptions setEnableNotification(boolean enableNotification) {
        this.enableNotification = enableNotification;
        return this;
    }
}

MemberAttributeOptions

/**
 * 房间成员属性可选项实体
 */
public class MemberAttributeOptions {
  /**
   * 是否通知：默认不通知
   */
    private boolean enableNotification = false;

    public boolean getEnableNotification() {
        return enableNotification;
    }

    public MemberAttributeOptions setEnableNotification(boolean enableNotification) {
        this.enableNotification = enableNotification;
        return this;
    }
}