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

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

Hummer

state

@property (class, nonatomic, assign, readonly) HMRHummerState state;

获取SDK当前状态，详见 HMRHummerState

返回
  • SDK当前状态

channelState

@property (class, nonatomic, assign, readonly) HMRChannelState channelState;

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

注意事项 该方法已弃用，请改用 connectionState。

返回
  • SDK当前连接状态

connectionState

@property (class, nonatomic, assign, readonly) HMRConnectionState connectionState;

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

返回
  • SDK当前连接状态

startSDKWithAppId:

+ (void)startSDKWithAppId:(UInt64)appId;

初始化Hummer

注意事项

  • 目前 SDK 只支持一个 Hummer 实例，每个应用程序仅应创建一个 Hummer 对象。
  • Hummer 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。
  • 对于所有操作的回调，如无特殊说明，返回的NSError为 nil 代表成功，否则为操作失败，具体的错误码及含义参见 HMRErrorCode中的错误码定义。
参数
参数描述
appId用于标识具体业务, 详见 APPID申请

openWithUid:environment:msgFetchStrategy:tags:token:completionHandler:

+ (void)openWithUid:(UInt64)uid
        environment:(NSString *)environment
   msgFetchStrategy:(HMRMsgFetchStrategy)msgFetchStrategy
               tags:(NSSet<NSString *> *_Nullable)tags
              token:(NSString *)token
  completionHandler:(HMRCompletionHandler)completionHandler;

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

参数
参数描述
uid用户id, uid 不能为0
environment需要连接服务器所处的环境参数，详情咨询相关SDK开发人员
msgFetchStrategy消息拉取策略，详见 HMRMsgFetchStrategy
tags保留字段，暂时可以填空集合
token用于服务初始化时所需的用户凭证
completionHandler完成后的处理回调，详见 HMRCompletionHandler

closeWithCompletionHandler:

+ (void)closeWithCompletionHandler:(HMRCompletionHandler _Nullable)completionHandler;

登出SDK

注意事项

登出SDK是一个异步操作，应该在completionHandler回调中处理错误的情况

参数
参数描述
completionHandler完成后的处理回调，详见 HMRCompletionHandler

refreshToken:

+ (void)refreshToken:(NSString *)token;

刷新用户凭证。

注意事项

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

refreshToken:completion:

+ (void)refreshToken:(NSString *)token
          completion:(HMRCompletionHandler)completion;

刷新用户凭证。

注意事项

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

参数
参数描述
token待刷新用户凭证
completion回调，会返回对应错误码，业务需要对错误码进行处理，详见 HMRCompletionHandler

refreshToken1:completion:

+ (void)refreshToken1:(NSString *)token
          completion:(HMRCompletionHandler)completion;

刷新Token。

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

参数
参数描述
token新Token
completion结果回调，详见 HMRCompletionHandler

注意事项

  • API调用频率为2 次/s，超时时间为15s，接口调用超过频率限制或超时时间，会返回错误码。
  • Token刷新成功，会触发 didConnectionStateChanged（SDK连接状态改变回调），连接状态变为 Connected。
  • Token刷新失败，系统会主动断开SDK与服务器的连接，并触发 didConnectionStateChanged（SDK连接状态改变回调），连接状态变为 Reconnecting，直至刷新成功。

setLoggerFilePath:

+ (BOOL)setLoggerFilePath:(NSString *)path;

自定义日志存储路径。

参数
参数描述
path日志存储路径（存在且可写），格式为：JoLogs/Hummer，默认路径为: /Library/Caches/JoLogs/Hummer
返回
  • YES：成功。
  • NO：失败。

注意事项

  • 请勿直接使用根目录当日志路径。
  • 需要设置的日志存储路径，调用方应确保路径存在。
  • 建议在SDK初始化后调用该API，为保证日志完整性，不建议频繁调用该方法。

setLogLevel:

+ (BOOL)setLogLevel:(HMRLoggerLevel)logLevel;

设置SDK日志输出优先级别，不调用此接口，使用默认日志等级 HMRLoggerLevelVerbose

日志级别分为6个级别，由低到高为：Verbose < Debug < Info < Warning < Error < Release ，SDK会输出高于或等于所设置级别的日志。例如，设置日志级别为 Info ，则优先级高于或等于 Info 级别（如：Warning、Error、Release）的日志将被输出，小于该级别的将不会被输出。

参数
参数描述
logLevel日志等级，详见 HMRLoggerLevel
返回
  • YES：成功。
  • NO：失败。

setLogger:

+ (void)setLogger:(HMRLogCallback _Nullable)logger;

接入 SDK 的业务方可以通过该方法设置对应的 logger，那么 SDK 则会将日志的输出和打印交给业务来处理，业务需要保证日志的上报等，用于后期出现问题时可以查到具体的信息。

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

uploadLogsManually:

+ (BOOL)uploadLogsManually:(NSString *)remark;

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

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

sendP2PMessage:toUser:options:completionHandler:

+ (void)sendP2PMessage:(HMRBaseMessage *)message
                toUser:(HMRUser *)user
               options:(HMRP2PMessageOptions *_Nullable)options
     completionHandler:(HMRCompletionHandler _Nullable)completionHandler;

发送点对点消息（P2P）。

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

参数
参数描述
message目前仅支持 HMRTextMessage，且注意需使用该类提供的消息构造接口直接构建消息对象
user该条消息的接收者，详见 HMRUser
options发送消息所需要的配置信息，目前可配置该消息是否支持离线功能，详见 HMRP2PMessageOptions ，业务可通过设置参数 options 的 isOffline 字段 ，控制该次发送的消息是否开启离线功能，该功能默认关闭。
completionHandler结果回调（HMRCompletionHandler）：0-成功，其他-失败，详见 错误码

注意事项

  • 登录 Hummer 系统即可调用该接口，操作者和接收者均无任何是否在通道内/房间内限制。
  • 单个用户调用频率限制：180次/3秒。
  • 每个接收端最多保存 200 条离线消息，最长保存七天。当保存的离线消息超出限制时，最新消息将覆盖最老消息。

fetchUserOnlineStatus:completionHandler:

+ (void)fetchUserOnlineStatus:(NSSet<HMRUser *> *)users
            completionHandler:(nullable void (^)(NSSet<HMRUserOnlineStatus *> *onlineUsers, NSError *error))completionHandler;

查询用户在线状态。

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

参数
参数描述
users目标用户ID列表，不能超过200 个，详见 HMRUser
completionHandler结果回调（HMRCompletionHandler）：0-成功，并携带用户在线状态（HMRUserOnlineStatus）、其他-失败，详见 错误码

注意事项

  • 单个用户调用频率限制：10次/5s。
  • 单次最多查询200个用户的在线状态。

addStateObserver:

+ (void)addStateObserver:(id<HMRHummerStateObserver>)observer;

添加 SDK 状态变更监听器

参数
参数描述
observer待添加监听器，详见 HMRHummerStateObserver

removeStateObserver:

+ (void)removeStateObserver:(id<HMRHummerStateObserver>)observer;

移除 SDK 状态变更监听器

参数
参数描述
observer待移除监听器, 详见 HMRHummerStateObserver

addChannelStateObserver:

+ (void)addChannelStateObserver:(id<HMRChannelStateObserver>)observer;

废弃

注意事项

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

添加 连接 状态变更监听器

参数
参数描述
observer待添加监听器, 详见 HMRChannelStateObserver

removeChannelStateObserver:

+ (void)removeChannelStateObserver:(id<HMRChannelStateObserver>)observer;

废弃

注意事项

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

移除 连接 状态变更监听器

参数
参数描述
observer待移除监听器, 详见 HMRHummerObserver

addHummerObserver:

+ (void)addHummerObserver:(id<HMRHummerObserver>)observer;

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

参数
参数描述
observerHMRHummerObserver 监听器

removeHummerObserver:

+ (void)removeHummerObserver:(id<HMRHummerObserver>)observer;

移除 HMRHummerObserver 监听器，移除后将不再监听 Hummer 类接口的相关事件。

参数
参数描述
observerHMRHummerObserver 监听器

sdkVersion

+ (NSString *)sdkVersion;

获取 SDK 版本信息。

返回
  • SDK版本信息

HMRChatRoomService

instance

+ (instancetype)instance;

创建 HMRChatRoomService 实例并初始化。

返回
  • 返回 HMRChatRoomService对象

setRegion

@property (nonatomic, strong) NSString *region;

设置聊天室区域

注意事项

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

createChatRoom:completionHandler:

- (void)createChatRoom:(HMRChatRoomInfo *)chatRoomInfo
     completionHandler:(HMRChatRoomCompletionHandler)completionHandler;

创建聊天室

注意事项

  • 由于聊天室模块的所需的聊天室必须要通过创建才能使用，故需要对应的创建聊天室接口。
  • 在创建聊天室完成后，服务器会返回对应的聊天室标识，用于后续在使用聊天室时的标识。
  • 同时在创建聊天室时需要提供对应的聊天室信息，如名称、描述、公告以及扩展信息等。
  • 默认容量上限：
    一个AppId创建聊天室个数:100w个
    单个聊天室对应人数:10w个
  • 单个用户调用频率限制:10次/5s
  • 聊天室基本属性AppExtra最大长度:8k
参数
参数描述
chatRoomInfo聊天室信息对象，包含名称、描述、公告以及扩展信息 ，详见 HMRChatRoomInfo
completionHandler创建完成后的回调，其中创建成功后会携带对应的 聊天室标识 返回给业务，用于后面聊天室操作中使用；同时在创建失败后，回调中也携带了对应的失败原因，详见 HMRChatRoomCompletionHandler

dismissChatRoom:completionHandler:

- (void)dismissChatRoom:(HMRChatRoom *)chatRoom
      completionHandler:(HMRCompletionHandler)completionHandler;

解散聊天室

注意事项

  • 销毁时需要提供对应的聊天室标识用于服务器识别对应的聊天室，并正常销毁。
  • 销毁需要HMROwnerRole权限
  • 单个用户调用频率限制:10次/5s
参数
参数描述
chatRoom聊天室标识符，详见 HMRChatRoom
completionHandler销毁完成后的回调，业务可以根据对应的销毁结果做不同的业务逻辑处理，销毁失败时也会携带对应的失败原因，详见 HMRCompletionHandler

joinChatRoom:extraProps:completionHandler:

- (void)joinChatRoom:(HMRChatRoom *)chatRoom
          extraProps:(NSDictionary<NSString *, NSString *> * _Nullable)extraProps
   completionHandler:(HMRCompletionHandler)completionHandler;

加入聊天室

注意事项

  • 对应聊天室操作都需要进入聊天室之后才能正常的操作，如发公屏、发信令以及接受信令都要进入聊天室之后才能正常处理。
  • 加入聊天室会涉及多端互踢的逻辑，相关互踢逻辑请咨询后台配置。
  • 单个用户调用频率限制:10次/5s
参数
参数描述
chatRoom聊天室标识符，详见 HMRChatRoom
extraProps扩展字段，用于业务扩展，SDK 只负责透传
completionHandler加入聊天室完成后的回调，业务可以根据对应的加入结果做不同的业务处理，加入失败时也会携带对应的错误原因，详见 HMRCompletionHandler

leaveChatRoom:completionHandler:

- (void)leaveChatRoom:(HMRChatRoom *)chatRoom
    completionHandler:(HMRCompletionHandler)completion;

退出聊天室

注意事项

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

参数
参数描述
chatRoom聊天室标识符，详见 HMRChatRoom
completionHandler离开聊天室完成后的回调，业务可以根据对应的离开结果做不同的业务处理，离开失败时也会携带对应的错误原因

kickMember:fromChatRoom:extraInfo:completionHandler:

- (void)kickMember:(HMRUser *)member
      fromChatRoom:(HMRChatRoom *)chatRoom
         extraInfo:(NSDictionary<NSString *, NSString *> *)extraInfo
 completionHandler:(HMRCompletionHandler)completionHandler;

将用户踢出聊天室

说明

  • 该接口从 v2.15.0 开始废弃，相关功能请使用 kickUser 代替
参数
参数描述
member踢出的聊天室成员，详见 HMRUser
chatRoom聊天室标识符，详见 HMRChatRoom
extraInfo踢人的额外信息，目前支持的Key主要是两个：
一个是 HMRKickReasonExtraKey, 用于携带踢人原因的 Key， 其 Key 对应的 Value 只需填写对应的踢人原因的字符串即可；
另一个是 HMRKickTimeExtraKey 用于携带限制时长的 Key(单位:秒)， 其 Key 对应的 Value 只需要填写踢人限制时长的秒数转换成字符串即可, 这些字段都是透传字段，服务器不做处理
completionHandler踢出完成的回调，业务可以根据对应的踢出结果做不同的业务处理，踢出失败后也会携带对应的错误原因，详见 HMRCompletionHandler

注意事项

  • 踢出用户需要对应的角色(HMRAdminRole 和 HMROwnerRole) 才可以踢出对应的用户，并且 HMRAdminRole 不可以踢出 HMRAdminRole 和 HMROwnerRole, 而 HMROwnerRole 可以踢出聊天室内所有用户。
  • 并且踢出用户以及被踢出的用户都需要在聊天室内可以操作。
  • 踢出成功后，SDK 后台并不会限制该用户无法进入，但是 SDK 会透传给业务服务器，由业务服务器做决定是否允许进入聊天室。
  • 单个用户调用频率限制:10次/5s

kickUser:fromChatRoom:extraInfo:options:completionHandler:

- (void)kickUser:(HMRUser *)user
    fromChatRoom:(HMRChatRoom *)chatRoom
       extraInfo:(NSDictionary<NSString *, NSString *> * _Nullable)extraInfo
         options:(HMRChatRoomKickUserOptions * _Nullable)options
completionHandler:(HMRCompletionHandler)completionHandler;

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

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

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

addRole:forMember:chatRoom:completionHandler:

- (void)addRole:(NSString *)role
      forMember:(HMRUser *)member
       chatRoom:(HMRChatRoom *)chatRoom
completionHandler:(HMRCompletionHandler)completionHandler;

添加聊天室权限角色

说明

  • 该接口从 v2.15.0 开始已废弃，有相关需求请改用 setUserRole
参数
参数描述
role角色类型，目前只能填写 HMRAdminRole
member被添加角色的聊天室成员，详见 HMRUser
chatRoom聊天室标识符，详见 HMRChatRoom
completionHandler结果回调 HMRCompletionHandler ：0-成功，其他-失败，详见 错误码

注意事项

  • 聊天室的 HMROwnerRole 可以给对应的用户添加 HMRAdminRole 的角色，但是 HMRAdminRole 没办法给普通用户添加 HMRAdminRole 的角色。
  • 单个用户调用频率限制:10次/5s

setUserRole:forUser:chatRoom:options:completionHandler:

- (void)setUserRole:(NSString *)role
            forUser:(HMRUser *)user
           chatRoom:(HMRChatRoom *)chatRoom
            options:(HMRChatRoomRoleOptions * _Nullable)options
  completionHandler:(HMRCompletionHandler)completionHandler

设置聊天室用户角色。

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

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

removeRole:forMember:chatRoom:completionHandler:

- (void)removeRole:(NSString *)role
         forMember:(HMRUser *)member
          chatRoom:(HMRChatRoom *)chatRoom
 completionHandler:(HMRCompletionHandler)completionHandler;

移除聊天室权限角色

说明

  • 该接口从 v2.15.0 开始已废弃，有相关需求请改用 deleteUserRole
参数
参数描述
role角色类型, 目前只能填写 HMRAdminRole
member被移除角色的聊天室成员，详见 HMRUser
chatRoom聊天室标识符，详见 HMRChatRoom
completionHandler结果回调（HMRCompletionHandler）：0-成功，其他-失败，详见 错误码

注意事项

  • 聊天室的 HMROwnerRole 才可以移除对应的 HMRAdminRole 角色，但是 HMRAdminRole 没办法给 HMRAdminRole 移除角色。
  • 单个用户调用频率限制:10次/5s

deleteUserRole:chatRoom:options:completionHandler:

- (void)deleteUserRole:(HMRUser *)user
              chatRoom:(HMRChatRoom *)chatRoom
               options:(HMRChatRoomRoleOptions * _Nullable)options
     completionHandler:(HMRCompletionHandler)completionHandler;

删除用户的角色。

调用成功会触发用户角色被删通知 didUserRoleDeleted。

参数
参数描述
user被移除角色的用户，详见 HMRUser
chatRoom聊天室标识符，详见 HMRChatRoom
options预留字段，详见HMRChatRoomRoleOptions
completionHandler结果回调（HMRCompletionHandler）：0-成功，其他-失败，详见 错误码
注意事项
  • 只有 Owner 有权限删除指定用户的角色。
  • 单个用户调用频率限制：10次/5s。
  • 操作者和被操作者都可以不在房间内。

fetchMembers:offset:num:completionHandler:

- (void)fetchMembers:(HMRChatRoom *)chatRoom
              offset:(NSUInteger)offset
                 num:(NSUInteger)num
   completionHandler:(HMRFetchMembersCompletionHandler)completionHandler;

获取聊天室在线用户列表。

参数
参数描述
chatRoom聊天室标识符，详见 HMRChatRoom
offset第几页 (第一页从0开始)
num设置每页的返回成员数（建议不超过200）
completionHandler获取完成后的回调，业务可以根据对应的获取的结果来做不同的业务处理，在获取成功的后可以通过成功后的 成员列表 来进行业务处理

注意事项

  • 由于一些场景下，一个聊天室的内的用户可能有十几万，故聊天室 SDK 提供了对应的按需分页获取用户的结果。同时也会按照一定的默认规则来进行排序对应的用户列表。
  • 获取用户列表的接口，可以在不进入聊天室时也可以获取。
  • 单个用户调用频率限制:10次/5s

fetchRoleMembers:onlineOnly:completionHandler:

- (void)fetchRoleMembers:(HMRChatRoom *)chatRoom
              onlineOnly:(BOOL)onlineOnly
       completionHandler:(HMRFetchRoleMemberCompletionHandler)completionHandler;

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

说明

参数
参数描述
chatRoom聊天室标识符，详见 HMRChatRoom
onlineOnly是否只获取在线的成员:
YES:只获取在线的有角色的成员列表;
NO:获取所有带有角色的成员列表
completionHandler结果回调（HMRCompletionHandler）：0-成功，并返回角色成员列表、其他-失败，详见 错误码

注意事项

  • 获取可以根据需要拉取对应的角色列表，业务可以根据对应的角色列表在界面上展示不同的UI界面以及赋予对应角色权限。
  • 获取角色列表无需进入聊天室后获取，进入聊天室前即可获取。
  • 单个用户调用频率限制:10次/5s

fetchRoomUsersByRole:chatRoom:completionHandler:

- (void)fetchRoomUsersByRole:(NSString * _Nullable)role
                    chatRoom:(HMRChatRoom *)chatRoom
           completionHandler:(HMRFetchRoleMemberCompletionHandler)completionHandler;

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

参数
参数描述
role角色, null 表示查询所有当前在房间内的所有带角色的用户列表; owner 和 admin 分别查询对应角色的用户列表
chatRoom聊天室标识符，详见 HMRChatRoom
completionHandler结果回调，详见 HMRFetchRoleMemberCompletionHandler
注意事项
  • 单个用户调用频率限制：10次/5s
  • 返回的只是创建者 owner、管理员 admin 角色列表，不支持返回普通用户列表。

fetchUserRole:chatRoom:completionHandler:

- (void)fetchUserRole:(HMRUser *)user
             chatRoom:(HMRChatRoom *)chatRoom
    completionHandler:(HMRChatRoomFetchUserRoleCompletionHandler)completionHandler;

查询用户在目标聊天室的角色信息。

参数
参数描述
user指定查询的聊天室用户，详见 HMRUser
chatRoom聊天室标识符，详见 HMRChatRoom
completionHandler结果回调，详见 HMRChatRoomFetchUserRoleCompletionHandler
注意事项

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

fetchBasicInfo:completionHandler:

- (void)fetchBasicInfo:(HMRChatRoom *)chatRoom
     completionHandler:(HMRChatRoomInfoCompletionHandler)completionHandler;

获取聊天室基本属性信息

说明

参数
参数描述
chatRoom聊天室标识符，详见 HMRChatRoom
completionHandler获取完成后的回调，详见 HMRChatRoomInfoCompletionHandler
业务可以根据对应的获取结果做不同的业务逻辑处理，在获取成功后可以从对应的参数中获取到对应的 聊天室信息

注意事项

  • 获取聊天室信息可以获取到对应聊天室的名称、描述、公告以及对应的扩展字段信息。
  • 获取聊天室信息无需进入聊天室也可以获取。
  • 单个用户调用频率限制:10次/5s

fetchRoomBasicAttributes:byKeys:completionHandler:

- (void)fetchRoomBasicAttributes:(HMRChatRoom *)chatRoom
                          byKeys:(NSSet<NSString *> * _Nullable)attributesKeys
               completionHandler:(HMRFetchRoomBasicAttributesCompletionHandler)completionHandler;

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

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

fetchChatRoomInfo:completionHandler:

- (void)fetchChatRoomInfo:(HMRChatRoom *)chatRoom
        completionHandler:(HMRCommonCompletionHandler)completionHandler;

获取聊天室全部属性信息

说明

参数
参数描述
chatRoom聊天室标识符，详见 HMRChatRoom
completionHandler获取完成后的回调，详见 HMRCommonCompletionHandler
业务可以根据对应的获取结果做不同的业务逻辑处理，在获取成功后可以从对应的参数中获取到对应的 聊天室信息

fetchMemberCount:completionHandler:

- (void)fetchMemberCount:(HMRChatRoom *)chatRoom
       completionHandler:(void (^)(uint32_t totalCount, NSError * _Nullable error))completionHandler;

获取聊天室人数

参数
参数描述
chatRoom聊天室标识符，详见 HMRChatRoom
completionHandler获取完成后的回调

changeBasicInfo:forChatRoom:completionHandler:

- (void)changeBasicInfo:(NSDictionary<NSNumber *, NSString *> *)propInfo
            forChatRoom:(HMRChatRoom *)chatRoom
      completionHandler:(HMRCompletionHandler)completionHandler;

变更聊天室基本属性信息。

说明

参数
参数描述
propInfo修改的属性值，其中key值参见枚举详见：HMRChatRoomBasicInfoType
chatRoom聊天室标识符，详见 HMRChatRoom
completionHandler改完成后的回调，业务可以根据对应的修改结果做不同的业务处理，详见 HMRCompletionHandler

注意事项

  • 可以修改一个或多个属性，只需要在参数中指定需要修改的聊天室信息的键值对即可。
  • 需要 HMRAdminRole 或者 HMROwnerRole 的角色。
  • 单个用户调用频率限制:10次/5s
  • 聊天室基本属性AppExtra最大长度:8k

updateRoomBasicAttributes:forChatRoom:options:completionHandler:

- (void)updateRoomBasicAttributes:(NSDictionary<NSString *, NSString *> *)attributes
                      forChatRoom:(HMRChatRoom *)chatRoom
                          options:(HMRChatRoomBasicAttributeOptions * _Nullable)options
                completionHandler:(HMRCompletionHandler)completionHandler;

修改聊天室基础属性。

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

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

addOrUpdateChatRoomInfo:forChatRoom:completionHandler:

- (void)addOrUpdateChatRoomInfo:(NSDictionary<NSString *, NSString *> *)propInfo
                    forChatRoom:(HMRChatRoom *)chatRoom
              completionHandler:(HMRCompletionHandler)completionHandler;

添加或更新聊天室信息。

说明

注意事项

  • 属性信息存在则更新；不存在则添加
  • 属性最大支持属性个数：32个
  • 属性key长度： 32字节
  • 属性的最大值： 8k
参数
参数描述
propInfo修改的属性值，可自定义
chatRoom聊天室标识符，详见 HMRChatRoom
completionHandler改完成后的回调，业务可以根据对应的修改结果做不同的业务处理，详见 HMRCompletionHandler

setRoomExtraAttributes:forChatRoom:options:completionHandler:

- (void)setRoomExtraAttributes:(NSDictionary <NSString *, NSString *> *)attributes
                   forChatRoom:(HMRChatRoom *)chatRoom
                       options:(HMRChatRoomAttributeOptions *_Nullable )options
             completionHandler:(HMRCompletionHandler)completionHandler;

设置房间扩展属性。

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

参数
参数描述
attributes扩展属性，由 key-value组成
key：单个属性 Key 最大32字节，不能为空
value：单个属性value最大8KB，可以为空
chatRoom房间标识符，详见 HMRChatRoom
options预留参数，详见 HMRChatRoomAttributeOptions
completionHandler结果回调（HMRCompletionHandler）：0-成功，其他-失败，详见 错误码

注意事项

  • 单个房间最多支持32个扩展属性。
  • 仅 Owner 和 Admin 用户有权限设置房间扩展属性，且操作者需要在该房间内。
  • 单个用户调用频率限制：10次/5s。

updateRoomExtraAttributes:forChatRoom:options:completionHandler:

- (void)updateRoomExtraAttributes:(NSDictionary <NSString *, NSString *> *)attributes
                   forChatRoom:(HMRChatRoom *)chatRoom
                       options:(HMRChatRoomAttributeOptions *_Nullable )options
             completionHandler:(HMRCompletionHandler)completionHandler;

更新房间扩展属性。

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

参数
参数描述
attributes扩展属性，由 key-value组成
key：单个属性 Key 最大32字节，不能为空
value：单个属性value最大8KB，可以为空
chatRoom房间标识符，详见 HMRChatRoom
options预留参数，详见 HMRChatRoomAttributeOptions
completionHandler结果回调（HMRCompletionHandler）：0-成功，其他-失败，详见 错误码

注意事项

  • 单个房间最多支持32个扩展属性。
  • 仅 Owner 和 Admin 用户有权限更新房间扩展属性，且操作者需要在该房间内。
  • 单个用户调用频率限制：10次/5s。

deleteRoomExtraAttributes:forChatRoom:options:completionHandler:

- (void)deleteRoomExtraAttributes:(NSSet<NSString *> *)keys
                      forChatRoom:(HMRChatRoom *)chatRoom
                          options:(HMRChatRoomAttributeOptions *_Nullable )options
                completionHandler:(HMRCompletionHandler)completionHandler;

删除指定房间扩展属性。

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

参数
参数描述
keys要删除的属性 key 集合，不能为空，单个 Key 最大为32字节
chatRoom聊天室标识符，详见 HMRChatRoom
options预留参数，详见 HMRChatRoomAttributeOptions
completionHandler结果回调（HMRCompletionHandler）：0-成功，其他-失败，详见 错误码

注意事项

  • 仅 Owner 和 Admin 用户有权限执行该操作。
  • 操作者需要在该房间内。

clearRoomExtraAttributes:options:completionHandler:

- (void)clearRoomExtraAttributes:(HMRChatRoom *)chatRoom
                         options:(HMRChatRoomAttributeOptions *_Nullable )options
               completionHandler:(HMRCompletionHandler)completionHandler;

清空房间扩展属性。

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

参数
参数描述
chatRoom聊天室标识符，详见 HMRChatRoom
options预留参数 HMRChatRoomAttributeOptions
completionHandler结果回调（HMRCompletionHandler）：0-成功，其他-失败，详见 错误码

注意事项

  • 仅 Owner 和 Admin 用户有权限执行该操作。
  • 操作者需要在该房间内。

fetchRoomExtraAttributes:byKeys:completionHandler:

- (void)fetchRoomExtraAttributes:(HMRChatRoom *)chatRoom
                          byKeys:(NSSet <NSString *> *_Nullable )attributesKeys
               completionHandler:(HMRFetchRoomExtraAttributesCompletionHandler)completionHandler;

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

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

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

注意事项

  • keys 默认为空，即表示查询全量属性
  • 每个属性 Key 最大32字节
  • 无角色限制，任何用户均可以执行查询房间扩展属性操作
  • 无在聊天室内限制，任何用户均可以执行查询房间扩展属性操作
  • HMRFetchRoomExtraAttributesCompletionHandler 会返回查询操作结果，详情见HMRFetchRoomExtraAttributesResult

fetchHistoryMessages:byFetchingParams:completionHandler:

- (void)fetchHistoryMessages:(HMRChatRoom *)chatRoom
            byFetchingParams:(HMRMessageFetchingParams *)fetchingParams
           completionHandler:(HMRFetchHistoryMessagesCompletionHandler)completionHandler

获取聊天室公屏历史消息。

注意事项

  • 历史消息存储时间限制一个月。
  • 无进入聊天室限制，无权限角色限制，所有用户均可调用该接口。
  • 单次查询结果最大支持100条，最少1条。
  • 单个用户调用频率限制：10次/5s。
参数
参数描述
chatRoom聊天室标识符，详见 HMRChatRoom
fetchingParams消息查询条件，详见 HMRMessageFetchingParams
completionHandler结果回调：0-成功，其他-详见错误码 HMRErrorCode，业务可以根据对应的获取结果做不同的业务处理，详见 HMRFetchHistoryMessagesCompletionHandler

muteMember:inChatRoom:reason:completionHandler:

- (void)muteMember:(HMRUser *)member
        inChatRoom:(HMRChatRoom *)chatRoom
            reason:(NSString *)reason
 completionHandler:(HMRCompletionHandler)completionHandler;

禁言聊天室内的用户

注意事项

  • 业务可以根据对应的需要禁言某个用户，目前后台默认的禁言时间为三天，到期自动解禁。
  • 禁言需要 HMRAdminRole 或者 HMROwnerRole 的角色：
    HMROwnerRole:可以禁言聊天室内的所有人包括 HMRAdminRole
    HMRAdminRole:只可以禁言普通用户。
  • 禁言的用户需要在聊天室内
  • 单个用户调用频率限制:10次/5s
参数
参数描述
member需要禁言的成员，详见 HMRUser
chatRoom成员所在的聊天室，详见 HMRChatRoom
reason禁言的原因
completionHandler禁言完成后的回调，业务可以根据对应禁言结果做不同的业务处理，详见 HMRCompletionHandler

unmuteMember:inChatRoom:reason:completionHandler:

- (void)unmuteMember:(HMRUser *)member
          inChatRoom:(HMRChatRoom *)chatRoom
              reason:(NSString *)reason
   completionHandler:(HMRCompletionHandler)completionHandler;

解禁聊天室内的用户

注意事项

  • 解禁的用户需要在聊天室内
  • 解除禁言需要 HMRAdminRole 或者 HMROwnerRole 的角色， HMROwnerRole 可以解禁聊天室内的所有人包括 HMRAdminRole, 而 HMRAdminRole 则只可以解禁普通用户。
  • 单个用户调用频率限制:10次/5s
参数
参数描述
member需要解除禁言的成员，详见 HMRUser
chatRoom成员所在的聊天室，详见 HMRChatRoom
reason接触禁言的原因
completionHandler解除禁言完成后的回调，业务可以根据对应解除禁言结果做不同的业务处理，详见 HMRCompletionHandler

fetchMutedUsers:completionHandler:

- (void)fetchMutedUsers:(HMRChatRoom *)chatRoom
      completionHandler:(HMRFetchMembersCompletionHandler)completionHandler;

获取聊天室内的禁言列表

注意事项

  • 获取的禁言列表里面的有些用户可能不存在聊天室内
  • 单个用户调用频率限制:10次/5s
参数
参数描述
chatRoom需要获取禁言列表的聊天室，详见 HMRChatRoom
completionHandler获取完成后的回调，业务可以根据对应的获取结果做不同的业务处理，在获取成功时，会同时返回对应的禁言成员的数组，详见 HMRFetchMembersCompletionHandler

isUserMuted:inChatRoom:completionHandler:

- (void)isUserMuted:(HMRUser *)user
         inChatRoom:(HMRChatRoom *)chatRoom
  completionHandler:(HMRBOOLCompletionHandler)completionHandler;

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

注意事项

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

参数
参数描述
user需要判别的用户，详见 HMRUser
chatRoom需要判别的聊天室，详见 HMRChatRoom
completionHandler判断完成后的回调，详见 HMRBOOLCompletionHandler，业务可以根据对应判断结果来做不同的业务处理：
YES：时则表示该用户被禁言了
NO：表示该用户未被禁言

setUserInfo:inChatRoom:completionHandler:

- (void)setUserInfo:(NSDictionary<NSString *, NSString *> *)infos
         inChatRoom:(HMRChatRoom *)chatRoom
   ompletionHandler:(HMRCompletionHandler)completionHandler;

设置自己的用户信息。

注意事项

  • 容量上限：
    设置用户属性，最大支持属性个数：32个
    单个用户属性的最大值:8k
  • 单个用户调用频率限制:10次/5s
参数
参数描述
infos用户信息键值对
chatRoom成员所在的聊天室，详见 HMRChatRoom
completionHandler设置信息返回的回调，可以根据错误码进行处理，详见 HMRCompletionHandler

deleteUserInfo:byKeys:completionHandler:

- (void)deleteUserInfo:(HMRChatRoom *)chatRoom
                byKeys:(NSSet<NSString *> *)keys
     completionHandler:(HMRCompletionHandler)completionHandler;

删除自己的用户信息

注意事项

  • 容量上限：
    用户属性，最大支持属性个数：32个
    单个用户属性的最大值:8k
  • 单个用户调用频率限制:10次/5s
参数
参数描述
chatRoom成员所在的聊天室，详见 HMRChatRoom
keys待删除信息的key
completionHandler设置信息返回的回调，可以根据错误码进行处理，详见 HMRCompletionHandler

addOrUpdateUserInfo:inChatRoom:completionHandler:

- (void)addOrUpdateUserInfo:(NSDictionary<NSString *, NSString *> *)infos
                 inChatRoom:(HMRChatRoom *)chatRoom
          completionHandler:(HMRCompletionHandler)completionHandler;

添加或更新指定用户信息

注意事项

  • 属性信息存在则更新；不存在则添加；
  • 属性最大支持属性个数：32个
  • 属性的最大值： 8k
参数
参数描述
infos属性信息
chatRoom成员所在的聊天室，详见 HMRChatRoom
completionHandler设置信息返回的回调，可以根据错误码进行处理，详见 HMRCompletionHandler

fetchUserInfo:inChatRoom:completionHandler:

- (void)fetchUserInfo:(HMRUser *)user
           inChatRoom:(HMRChatRoom *)chatRoom
    completionHandler:(HMRCommonCompletionHandler)completionHandler;

获取指定用户的用户信息

参数
参数描述
user目标用户, 详见 HMRUser
chatRoom成员所在的聊天室，详见 HMRChatRoom
completionHandler设置信息返回的回调，可以根据错误码进行处理，详见 HMRCommonCompletionHandler

batchFetchUserInfos:inChatRoom:completionHandler:

- (void)batchFetchUserInfos:(NSSet<HMRUser *> *)users
                 inChatRoom:(HMRChatRoom *)chatRoom
          completionHandler:(HMRChatRoomUserInfoListCompletionHandler)completionHandler;

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

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

fetchOnlineUserInfoList:completionHandler:

- (void)fetchOnlineUserInfoList:(HMRChatRoom *)chatRoom
              completionHandler:(HMRChatRoomUserInfoListCompletionHandler)completionHandler;

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

注意事项

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

参数
参数描述
chatRoom待查询聊天室，详见 HMRChatRoom
completionHandler完成后的回调，业务可以根据对应判断结果来做不同的业务处理 在获取成功后会返回对应的 用户-用户角色信息 的键值对，详见 HMRChatRoomUserInfoListCompletionHandler

addChatRoomObserver:

- (void)addChatRoomObserver:(id<HMRChatRoomObserver>)observer;

添加聊天室回调监听器

参数
参数描述
observer监听器对象, 详见 HMRChatRoomObserver

removeChatRoomObserver:

- (void)removeChatRoomObserver:(id<HMRChatRoomObserver>)observer;

移除聊天室回调监听器

参数
参数描述
observer监听器对象, 详见 HMRChatRoomObserver

addMemberObserver:

- (void)addMemberObserver:(id<HMRChatRoomMemberObserver>)observer;

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

参数
参数描述
observer监听器对象. 详见 HMRChatRoomMemberObserver

removeMemberObserver:

- (void)removeMemberObserver:(id<HMRChatRoomMemberObserver>)observer;

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

参数
参数描述
observer监听器对象, 详见 HMRChatRoomMemberObserver

HMRChannelService

instance

+ (instancetype)instance;

创建 HMRChannelService 实例并初始化。

返回
  • 返回 HMRChannelService 实例

joinChannel:options:completionHandler:

- (void)joinChannel:(HMRChannelId *)channelId
            options:(nullable HMRChannelJoiningOptions *)options
  completionHandler:(nullable HMRCompletionHandler)completionHandler;

加入消息频道 Channel，该接口用于加入一条底层消息频道，消息频道由用户调用该接口时直接指定，Hummer 系统后台直接创建，加入消息频道后的用户可发送频道内广播消息

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

注意事项

  • 单个用户同时最多支持加入20 个通道。
  • 对应 Channel 操作都需要进入 Channel 之后才能正常的操作，如发送通道内广播消息以及接收通道内广播都要进入Channel 之后才能正常处理。

leaveChannel:completionHandler:

- (void)leaveChannel:(HMRChannelId *)channelId
  completionHandler:(nullable HMRCompletionHandler)completionHandler;

退出消息通道 （Channel）。

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

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

sendP2CMessage:inChannel:options:completionHandler:

- (void)sendP2CMessage:(HMRBaseMessage *)message
             inChannel:(HMRChannelId *)channelId
               options:(nullable HMRP2CMessageOptions *)options
     completionHandler:(nullable HMRCompletionHandler)completionHandler;

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

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

参数
参数描述
message消息对象，目前仅支持 HMRTextMessage，且注意需使用该类提供的消息构造接口直接构建消息对象
channelId消息通道ID ，由 [A,Z]、[a,z]、[0,9]、-、_ 组成，最大长度为 64 字节，详见 HMRChannelId
options预留参数，可不填，详见 HMRP2CMessageOptions
completionHandler结果回调（HMRCompletionHandler）：0-成功，其他-失败，详见 错误码

注意事项

  • 单个用户调用频率限制：90 次/3秒。
  • 仅已加入通道的用户，才能往该通道发送广播消息。
  • 离开通道后，将不能继续接收通道内的广播消息。

HMRChatService

instance

+ (instancetype)instance;

创建 HMRChatService 实例并初始化。

返回
  • 返回 HMRChatService 对象

sendMessage:completionHandler:

- (void)sendMessage:(HMRMessage *)chatMessage
  completionHandler:(nullable HMRCompletionHandler)completionHandler;

发送消息，支持发送 公屏消息（只支持文本消息）、单播、广播。

说明：

  • 业务可以通过自己构造消息体，并且填写对应的消息内容将该消息发送出去。
  • 该接口也可以在消息发送失败的情况下进行重发消息。
  • 单个用户调用频率限制：
    发送公屏消息：10次/5s
    发送自定义单播消息：50次/5s
    发送自定义广播消息：50次/5s
  • 单条消息最大长度：32K
参数
参数描述
chatMessage需要发送的消息，详见 HMRMessage
completionHandler发送完成的处理Block，其中如果 error 为 nil 的话，则表示发送成功。 如果 error 不为 nil 则表示发送失败，详见 HMRCompletionHandler

addMessageObserver:forTarget:

- (void)addMessageObserver:(id<HMRMessageObserver>)observer forTarget:(id<HMRIdentifiable> _Nullable)target;

添加一个消息收发监听器

参数
参数描述
observer欲增加的listener对象，详见 HMRMessageObserver
target欲监听消息收发的消息对象，详见 HMRIdentifiable

removeMessageObserver:forTarget:

- (void)removeMessageObserver:(id<HMRMessageObserver>)observer forTarget:(id<HMRIdentifiable> _Nullable)target;

移除一个消息收发监听器

参数
参数描述
observer欲移除的listener对象，详见 HMRMessageObserver
target欲取消监听消息收发的消息对象，详见 HMRIdentifiable

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

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

反馈

TOP