iOS IM SDK 基础功能

概述

JMessage iOS IM SDK的基础功能。了解极光 IM 的详细信息,请参考文档:JMessage 产品简介

字符串规范

此处定义JMessage产品里字段属性与规范,用于校验与规范化。

参数字符说明长度限制
app_key由 JPush Web Portal 生成的 24位字符串。字母或者数字,不区分大小写
username以字母或者数字开头。支持字母、数字、下划线、英文点、减号、 @。Byte(4~128)
password不限Byte(4~128)
group_name不支持的字符:“\n” “\r”Byte(0~64)
nickname不支持的字符:“\n” “\r”Byte(0~64)
note_name不支持的字符:“\n” “\r”Byte(0~64)
other其他未明确指定的 String 类型字段,都按照这个处理。 支持字符:全部Byte(0~250)

SDK 初始化

  • setupJMessage: 方法,需要在应用初始化时调用
  • SDK 初始化时,可设置是否启用消息记录漫游
    打开消息漫游之后,用户多个设备之间登录时,SDK会自动将历史消息同步到本地,同步完成之后SDK会触发代理方法onSyncRoamingMessageConversation:通知上层刷新,具体方法见消息同步
  1. /*!
  2. * @abstract 初始化 JMessage SDK
  3. *
  4. * @param launchOptions AppDelegate启动函数的参数launchingOption(用于推送服务)
  5. * @param appKey appKey(应用Key值,通过jiguang官网可以获取)
  6. * @param channel 应用的渠道名称
  7. * @param isProduction 是否为生产模式
  8. * @param category iOS8新增通知快捷按钮参数
  9. * @param isRoaming 是否启用消息漫游,默认关闭
  10. *
  11. * @discussion 此方法必须被调用, 以初始化 JMessage SDK
  12. *
  13. * 如果未调用此方法, 本 SDK 的所有功能将不可用.
  14. */
  15. + (void)setupJMessage:(NSDictionary *)launchOptions
  16. appKey:(NSString *)appKey
  17. channel:(NSString *)channel
  18. apsForProduction:(BOOL)isProduction
  19. category:(NSSet *)category
  20. messageRoaming:(BOOL)isRoaming;

监听代理

JMessage SDK 采用 Delegate 的机制给 App 发通知,而不是采用 iOS 平台通用的通知方式。

添加代理

可以在 App 的任何类里,调用以下方法来监听事件通知。

  1. [JMessage addDelegate:self withConversation:nil]

为了上述这行有效,则需要在当前类的头文件里声明实现 JMessageDelegate 协议。

以下示例在 AppDelegate 里加监听:

  1. @interface AppDelegate : UIResponder <UIApplicationDelegate,JMessageDelegate>

另外,需要实现你需要监听的事件的方法。比如监听数据库升级:

  1. - (void)onDBMigrateStart {
  2. NSLog(@"onDBmigrateStart in appdelegate");
  3. _isDBMigrating = YES;
  4. }

注意: 由于 JMessage SDK 会在 setup 时检测数据库升级,如果有需要就发出通知。所以建议在 AppDelegate 里调用 setupJMessage 之前就添加监听。

移除代理

为了避免内存损耗和不必要的监听,在上层不需要监听时,可以调用一下接口移除监听:

  1. +(void)removeDelegate: withConversation:

更多监听代理的使用可以查看 事件管理

注册

直接通过 usernamepassword 来注册 im 账号

  1. /*!
  2. * @abstract 新用户注册
  3. *
  4. * @param username 用户名. 长度 4~128 位.
  5. * 支持的字符: 字母,数字,下划线,英文减号,英文点,@邮件符号. 首字母只允许是字母或者数字.
  6. * @param password 用户密码. 长度 4~128 位.
  7. * @param handler 结果回调. 返回正常时 resultObject 为 nil.
  8. */
  9. + (void)registerWithUsername:(NSString *)username
  10. password:(NSString *)password
  11. completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

也可以在注册用户时,携带用户其他信息字段一起注册,可携带字段请查看 JMSGUserInfo

  1. /*!
  2. * @abstract 新用户注册(支持携带用户信息字段)
  3. *
  4. * @param username 用户名. 长度 4~128 位.
  5. * 支持的字符: 字母,数字,下划线,英文减号,英文点,@邮件符号. 首字母只允许是字母或者数字.
  6. * @param password 用户密码. 长度 4~128 位.
  7. * @param userInfo 用户信息类,注册时携带用户信息字段,除用户头像字段
  8. * @param handler 结果回调. 返回正常时 resultObject 为 nil.
  9. *
  10. * @discussion 注意: 注册时不支持上传头像,其他信息全部支持
  11. */
  12. + (void)registerWithUsername:(NSString *)username
  13. password:(NSString *)password
  14. userInfo:(JMSGUserInfo *JMSG_NULLABLE)userInfo
  15. completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

登录

  1. /*!
  2. * @abstract 用户登录
  3. *
  4. * @param username 登录用户名. 规则与注册接口相同.
  5. * @param password 登录密码. 规则与注册接口相同.
  6. * @param handler 结果回调
  7. *
  8. * - resultObject 简单封装的user对象
  9. * - error 错误信息
  10. *
  11. * 注意:上层不要直接使用 resultObject 对象做操作, 因为 resultOjbect 只是一个简单封装的user对象.
  12. */
  13. + (void)loginWithUsername:(NSString *)username
  14. password:(NSString *)password
  15. completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

退出登录

如果上层不主动调用 logout 接口,原则上是一直处于登录的。

  1. /*!
  2. * @abstract 当前用户退出登录
  3. *
  4. * @param handler 结果回调。正常返回时 resultObject 也是 nil。
  5. *
  6. */
  7. + (void)logout:(JMSGCompletionHandler JMSG_NULLABLE)handler;

通知管理

注册远程推送

  1. /*!
  2. * @abstract 注册远程推送
  3. * @param types 通知类型
  4. * @param categories 类别组
  5. * @discussion 此方法必须被调用,如果有集成JPush或其他远程推送注册方法,请不要再调用此方法
  6. *
  7. */
  8. + (void)registerForRemoteNotificationTypes:(NSUInteger)types
  9. categories:(NSSet *)categories;

注册DeviceToken

  1. /*!
  2. * @abstract 注册DeviceToken
  3. * @param deviceToken 从注册推送回调中拿到的DeviceToken
  4. * @discussion 此方法必须被调用
  5. *
  6. */
  7. + (void)registerDeviceToken:(NSData *)deviceToken;

设置角标(到服务器)

  1. /*!
  2. * @abstract 设置角标(到服务器)
  3. *
  4. * @param value 新的值. 会覆盖服务器上保存的值(这个用户)
  5. *
  6. * @discussion 本接口不会改变应用本地的角标值.
  7. * 本地仍须调用 UIApplication:setApplicationIconBadgeNumber 函数来设置角标.
  8. *
  9. * 该功能解决的问题是, 服务器端推送 APNs 时, 并不知道客户端原来已经存在的角标是多少, 指定一个固定的数字不太合理.
  10. *
  11. * APNS 服务器端角标功能提供:
  12. *
  13. * - 通过本 API 把当前客户端(当前这个用户的) 的实际 badge 设置到服务器端保存起来;
  14. * - 调用服务器端 API 发 APNs 时(通常这个调用是批量针对大量用户),
  15. * 使用 "+1" 的语义, 来表达需要基于目标用户实际的 badge 值(保存的) +1 来下发通知时带上新的 badge 值;
  16. */
  17. + (BOOL)setBadge:(NSInteger)value;

重置角标(到服务器)

  1. /*!
  2. * @abstract 重置角标(为0)
  3. *
  4. * @discussion 相当于 [setBadge:0] 的效果.
  5. * 参考 [JMessage setBadge:] 说明来理解其作用.
  6. */
  7. + (void)resetBadge;

自定义通知栏展示逻辑

上层开发者可以对通知栏进行一些定制,如:控制离线消息的存储、自定义通知栏内容等,具体的功能可以想象查看 JMSGOptionalContent 类里面的说明。在 发送消息 - 附带可控参数 模块会具体说明实现。

登录设备记录

登录时可以获取到设备的登录记录。

  1. /*!
  2. * @abstract 用户登录,返回登录设备信息
  3. *
  4. * @param username 登录用户名. 规则与注册接口相同.
  5. * @param password 登录密码. 规则与注册接口相同.
  6. * @param devicesInfo 登录设备回调,返回数据为 NSArray<JMSGDeviceInfo>
  7. * @param handler 结果回调
  8. *
  9. * - resultObject 简单封装的user对象,上层不要直接使用 resultObject 对象做操作, 因为它只是一个简单封装的user对象
  10. * - error 错误信息
  11. *
  12. * @discussion 回调中 devices 返回的是设备信息,具体属性请查看 JMSGDeviceInfo 类
  13. */
  14. + (void)loginWithUsername:(NSString *)username
  15. password:(NSString *)password
  16. devicesInfo:(nullable void(^)(NSArray <__kindof JMSGDeviceInfo *>*devices))devicesInfo
  17. completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;
DeviceInfo
属性类型说明
platformTypeJMSGPlatformType获取设备所属平台类型
isLoginBOOL判断设备当前是否处于登陆状态, YES:登陆,NO:登出
onlineUInt32获取设备在线状态,0不在线,1在线
mtimeNSNumber 获取设备最近一次登陆时间,单位-秒
flagNSInteger 默认为0,1表示该设备被当前登录设备踢出

多端同时在线

SDK从3.3.0版本开始支持多端同时在线,具体规则见多端在线说明