跨应用通信

概述

跨应用通信是指允许同一开发者账号下的不同应用能互相通信，以满足开发者对于不同 appKey 下应用通信的需求。

跨应用接口与非跨应用接口区别主要在于：跨应用接口增加了appkey作为参数。只要接口中需要传appkey作为参数的，均可以支持跨应用通信，详细接口说明请前往极光IM iOS API docs。这里仅列举一些常用的跨应用接口和实现。

跨应用用户管理

获取用户信息

通过指定appKey可以实现获取跨应用用户信息。

  1. /*!
  2.  * @abstract 批量获取用户信息
  3.  *
  4.  * @param usernameArray 用户名列表。NSArray 里的数据类型为 NSString
  5.  * @param userAppKey 用户所在 AppKey
  6.  * @param handler 结果回调。正常返回时 resultObject 的类型为 NSArray，数组里的数据类型为 JMSGUser
  7.  *
  8.  * @discussion 这是一个批量接口。
  9.  */
  10. + (void)userInfoArrayWithUsernameArray:(NSArray JMSG_GENERIC(__kindof NSString *)*)usernameArray
  11.                                 appKey:( NSString *JMSG_NULLABLE)userAppKey
  12.                      completionHandler:(JMSGCompletionHandler)handler;

免打扰设置

  1. /*!
  2.  * @abstract 设置用户免打扰（支持跨应用设置）
  3.  *
  4.  * @param isNoDisturb 是否全局免打扰 YES:是 NO: 否
  5.  * @param handler 结果回调。回调参数： error 为 nil, 表示设置成功
  6.  *
  7.  * @discussion 针对单个用户设置免打扰，这个接口支持跨应用设置免打扰
  8.  */
  9. - (void)setIsNoDisturb:(BOOL)isNoDisturb handler:(JMSGCompletionHandler)handler;

黑名单设置

添加
  1. /*!
  2.  * @abstract 跨应用添加黑名单
  3.  * @param usernameArray 作用对象的username数组
  4.  * @param userAppKey 应用的appKey
  5.  * @param handler 结果回调。回调参数：error 为 nil, 表示设置成功
  6.  *
  7.  * @discussion 可以一次添加多个用户
  8.  */
  9. + (void)addUsersToBlacklist:(NSArray JMSG_GENERIC(__kindof NSString *)*)usernameArray
  10.                      appKey:(NSString *)userAppKey
  11.           completionHandler:(JMSGCompletionHandler)handler;
删除
  1. /*!
  2.  * @abstract 跨应用删除黑名单
  3.  * @param usernameArray 作用对象的username数组
  4.  * @param userAppKey 应用的appKey
  5.  * @param handler 结果回调。回调参数：error 为 nil, 表示设置成功
  6.  *
  7.  * @discussion 可以一次删除多个黑名单用户
  8.  */
  9. + (void)delUsersFromBlacklist:(NSArray JMSG_GENERIC(__kindof NSString *)*)usernameArray
  10.                        appKey:(NSString *)userAppKey
  11.             completionHandler:(JMSGCompletionHandler)handler;

跨应用群组管理

实现跨应用群聊的关键在于群组中加入跨应用的群成员，而创建会话和发送消息的流程和普通的群聊实现方式一致。这里只列举部分常用的跨应用接口

群成员管理

添加
  1. /*!
  2.  * @abstract 添加群组成员
  3.  *
  4.  * @param usernameArray 用户名数组。数组里的成员类型是 NSString
  5.  * @param userAppKey    用户的 AppKey，这批添加的成员必须在同一个 AppKey 下的用户
  6.  * @param reason        邀请原因，可选
  7.  *
  8.  * @param handler 结果回调。正常返回时 resultObject 为 nil.
  9.  */
  10. - (void)addMembersWithUsernameArray:(NSArray JMSG_GENERIC(__kindof NSString *) *)usernameArray
  11.                              appKey:(NSString *JMSG_NULLABLE)userAppKey
  12.                              reason:(NSString *JMSG_NULLABLE)reason
  13.                   completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;
删除
  1. /*!
  2.  * @abstract 删除群组跨应用成员
  3.  *
  4.  * @param usernameArray 用户名数据. 数组里的成员类型是 NSString
  5.  * @param handler 结果回调。正常返回时 resultObject 为 nil.
  6.  */
  7. - (void)removeMembersWithUsernameArray:(NSArray JMSG_GENERIC(__kindof NSString *) *)usernameArray
  8.                                 appKey:(NSString *)userAppKey
  9.                      completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

管理员管理

添加
  1. /*!
  2.  * @abstract 添加管理员
  3.  *
  4.  * @param username 用户名
  5.  * @param appkey   用户 AppKey，不填则默认为本应用 AppKey
  6.  * @param handler 结果回调。error 为 nil 表示成功.
  7.  *
  8.  * @discussion 注意：非 VIP 应用最多设置 15 个管理员，不包括群主本身
  9.  */
  10. - (void)addGroupAdminWithUsernames:(NSArray <__kindof NSString *>*)usernames
  11.                             appKey:(NSString *JMSG_NULLABLE)appkey
  12.                  completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;
删除
  1. /*!
  2.  * @abstract 删除管理员
  3.  *
  4.  * @param username 用户名
  5.  * @param appkey   用户 AppKey，不填则默认为本应用 AppKey
  6.  * @param handler 结果回调。error 为 nil 表示成功.
  7.  */
  8. - (void)deleteGroupAdminWithUsernames:(NSArray <__kindof NSString *>*)usernames
  9.                                appKey:(NSString *JMSG_NULLABLE)appkey
  10.                     completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

黑名单管理

添加
  1. /*!
  2.  * @abstract 添加群黑名单
  3.  *
  4.  * @param usernames 用户名列表
  5.  * @param appkey   用户 appKey，usernames 中的所有用户必须在同一个 AppKey 下，不填则默认为本应用 appKey
  6.  * @param handler 结果回调。error 为 nil 表示成功.
  7.  *
  8.  * @discussion 黑名单上限100个，超出将无法设置成功，被拉入黑名单用户会被主动踢出群组，且无法再次加入.
  9.  * @since 3.8.0
  10.  */
  11. - (void)addGroupBlacklistWithUsernames:(NSArray <__kindof NSString *>*)usernames
  12.                                 appKey:(NSString *JMSG_NULLABLE)appKey
  13.                                handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;
删除
  1. /*!
  2.  * @abstract 删除群黑名单
  3.  *
  4.  * @param usernames 用户名列表
  5.  * @param appkey   用户 appKey，usernames 中的所有用户必须在同一个 AppKey 下，不填则默认为本应用 appKey
  6.  * @param handler 结果回调。error 为 nil 表示成功.
  7.  *
  8.  * @since 3.8.0
  9.  */
  10. - (void)deleteGroupBlacklistWithUsernames:(NSArray <__kindof NSString *>*)usernames
  11.                                    appKey:(NSString *JMSG_NULLABLE)appKey
  12.                                   handler:(JMSGCompletionHandler JMSG_NULLABLE)handler;

跨应用消息管理

发送跨应用单聊文本消息
  1. /*!
  2.  * @abstract 发送跨应用单聊文本消息
  3.  *
  4.  * @param text 文本内容
  5.  * @param username 单聊对象 username
  6.  *
  7.  * @discussion 快捷方法，不需要先创建消息而直接发送。
  8.  */
  9. + (void)sendSingleTextMessage:(NSString *)text
  10.                        toUser:(NSString *)username
  11.                        appKey:(NSString *)userAppKey;
发送跨应用单聊图片消息
  1. /*!
  2.  * @abstract 发送跨应用单聊图片消息
  3.  *
  4.  * @param imageData 图片数据
  5.  * @param username 单聊对象 username
  6.  *
  7.  * @discussion 快捷方法，不需要先创建消息而直接发送。
  8.  */
  9. + (void)sendSingleImageMessage:(NSData *)imageData
  10.                         toUser:(NSString *)username
  11.                         appKey:(NSString *)userAppKey;
发送跨应用单聊语音消息
  1. /*!
  2.  * @abstract 发送跨应用单聊语音消息
  3.  *
  4.  * @param voiceData 语音数据
  5.  * @param duration 语音时长
  6.  * @param username 单聊对象 username
  7.  *
  8.  * @discussion 快捷方法，不需要先创建消息而直接发送。
  9.  */
  10. + (void)sendSingleVoiceMessage:(NSData *)voiceData
  11.                  voiceDuration:(NSNumber *)duration
  12.                         toUser:(NSString *)username
  13.                         appKey:(NSString *)userAppKey;
发送跨应用单聊文件消息
  1. /*!
  2.  * @abstract 发送跨应用单聊文件消息
  3.  *
  4.  * @param fileData 文件数据数据
  5.  * @param fileName 文件名
  6.  * @param username 单聊对象 username
  7.  *
  8.  * @discussion 快捷方法，不需要先创建消息而直接发送。
  9.  */
  10. + (void)sendSingleFileMessage:(NSData *)fileData
  11.                      fileName:(NSString *)fileName
  12.                        toUser:(NSString *)username
  13.                        appKey:(NSString *)userAppKey;
发送跨应用单聊位置消息
  1. /*!
  2.  * @abstract 发送跨应用单聊地理位置消息
  3.  * @param latitude 纬度
  4.  * @param longitude 经度
  5.  * @param scale 缩放比例
  6.  * @param address 详细地址
  7.  * @param username 单聊对象
  8.  * @param userAppKey 单聊对象的appKey
  9.  * @discussion 快捷方法，不需要先创建消息而直接发送。
  10.  */
  11. + (void)sendSingleLocationMessage:(NSNumber *)latitude
  12.                         longitude:(NSNumber *)longitude
  13.                             scale:(NSNumber *)scale
  14.                           address:(NSString *)address
  15.                            toUser:(NSString *)username
  16.                            appKey:(NSString *)userAppKey;

跨应用会话管理

创建会话时指定对方用户所属 appKey，即可建立起一个和跨应用用户的会话。

获取跨应用单聊会话
  1. /*!
  2.  * @abstract 获取跨应用单聊会话
  3.  *
  4.  * @param username 单聊对象的username
  5.  * @param userAppKey 单聊对象的appkey
  6.  *
  7.  * @discussion 如果会话还不存在，则返回 nil
  8.  *
  9.  */
  10. + (JMSGConversation * JMSG_NULLABLE)singleConversationWithUsername:(NSString *)username
  12.                                                       appKey:(NSString *)userAppKey;
创建跨应用单聊会话
  1. /*!
  2.  * @abstract 创建跨应用单聊会话
  3.  *
  4.  * @param username 单聊对象的username
  5.  * @param userAppKey 单聊对象的appkey
  6.  * @param handler 结果回调。正常返回时 resultObject 类型为 JMSGConversation。
  7.  *
  8.  * @discussion 如果会话已经存在，则直接返回。如果不存在则创建。
  9.  */
  10. + (void)createSingleConversationWithUsername:(NSString *)username
  11.                                       appKey:(NSString *)userAppKey
  12.                            completionHandler:(JMSGCompletionHandler JMSG_NULLABLE)handler;
删除跨应用单聊会话
  1. /*!
  2. * @abstract 删除跨应用单聊会话
  3. *
  4. * @param username 单聊用户名
  5. * @param userAppKey 单聊用户的appkey
  6. *
  7. * @discussion 除了删除会话本身，还会删除该会话下所有的聊天消息。
  8. */
  9. + (BOOL)deleteSingleConversationWithUsername:(NSString *)username
  10.                                       appKey:(NSString *)userAppKey;