网易云信圈组 UIKit（QChat UIKit）是基于 NetEase Instant Messaging SDK（以下简称 NIM SDK）中的圈组模块开发的一款圈组 UI 组件库。本文介绍如何集成圈组 UIKit 到您的即时通讯项目中。

前提条件

在开始集成圈组 UIKit 前，请确保：

• 已在云信控制台创建应用，获取 App Key。
• 已注册云信 IM 账号，获取 accid 和 token。
• 已获取示例项目。
• 已准备如下开发环境/工具：
  • iOS 10.0 及以上版本
  • Xcode 14

实现流程

步骤1：按需导入组件

1. 根据业务需要，在 “Podfile” 文件中，以添加依赖的形式添加相应的圈组 UIKit 组件。同时，你也可以引入 IM UIKit 的组件库（比如需要通讯录功能和会话列表功能，可添加 NEContactUIKit 和 NEConversationUIKit）各组件相互独立，添加或删除均不影响项目编译。

   导入 UI 组件时，需要指定相同版本的基础 Kit 库引入，否则可能导致后续出现报错。具体可参见下文的常见问题排查。

   swift# Uncomment the next line to define a global platform for your project
   platform :ios, '11.0'
   
   # 请使用您的真实项目名称替换 your project name
   target 'your project name' do
   # Comment the next line if you don't want to use dynamic frameworks
   use_frameworks!
   
   # 圈组组件
   pod 'NEQChatUIKit', '9.5.3' 
   # 通讯录组件（可选）       
   pod 'NEContactUIKit', '9.6.5'   
   # 会话列表组件（可选）    
   pod 'NEConversationUIKit', '9.6.5'  
   # 会话（聊天）组件（可选）
   pod 'NEChatUIKit', '9.6.5'  
   # 群相关设置组件（可选）        
   pod 'NETeamUIKit', '9.6.5'          
   
   # 基础 Kit 库
   pod 'NECoreKit', '9.6.5'
   pod 'NECoreIMKit', '9.6.5'
   pod 'NECoreQChatKit', '9.6.5'
   pod 'NEQChatKit', '9.5.3'
   pod 'NECommonKit', '9.6.4'
   pod 'NECommonUIKit', '9.6.5'
   
   # 扩展库-地理位置组件
   pod 'NEMapKit', '9.6.5'         
   
   # 扩展库-呼叫组件
   pod 'NIMSDK_LITE','9.14.0'
   pod 'NERtcCallKit/NOS_Special', '2.2.0'
   pod 'NERtcCallUIKit/NOS_Special', '2.2.0'
   
   # 扩展库，依次为 RTC 音视频基础组件、RTC 音视频神经网络组件（使用背景虚化功能需要集成）、RTC 音视频背景分割组件（使用背景虚化功能需要集成）
   pod 'NERtcSDK/RtcBasic', '5.5.2'        
   pod 'NERtcSDK/Nenn'                    
   pod 'NERtcSDK/Segment'   
   end
   

   • 各 UI 组件相互独立，添加或删除均不影响项目编译。
   • 示例代码中的 9.5.3 为版本号，仅用于示例。建议使用最新版本。
   • 暂不支持 bitcode。

2. 配置完 “Podfile” 文件后执行pod install命令导入组件。

步骤2：初始化

1. 在项目中引入需要的组件。

   示例代码：

   Swift

   import NECoreKit
   import NECoreIMKit
   import NECoreQChatKit
   import NEQChatUIKit
   import NERtcCallUIKit
   ...
   

   Objective-C

   #import <NECoreKit/NECoreKit-Swift.h>
   #import <NECoreIMKit/NECoreIMKit-Swift.h>
   #import <NECoreQChatKit/NECoreQChatKit-Swift.h>
   #import <NEQChatKit/NEQChatKit-Swift.h>
   #import <NEQChatUIKit/NEQChatUIKit-Swift.h>
   #import <NERtcCallUIKit/NERtcCallUIKit.h>
   ...
   

2. 在应用启动后，调用 setupCoreKitQChat 方法进行初始化。

   option 参数	是否必传	说明
   appKey	是	云信控制台获取到的 App Key
   apnsCername	否	APNs 推送证书名，如不需要实现离线推送可不配置
   pkCername	否	PushKit 推送证书名，如不需要实现离线推送可不配置

   示例代码：

   Swift

   let option = NIMSDKOption()
   option.appKey = "your app key"
   option.apnsCername = "云信控制台配置的 APNS 推送证书名称"
   option.pkCername = "云信控制台配置的 PushKit 推送证书名称"
   QChatKitClient.instance.setupCoreKitQChat(option)
   let _ = NEAtMessageManager.instance
   

   Objective-C

   NIMSDKOption *option = [NIMSDKOption optionWithAppKey:AppKey];
   option.apnsCername = @"";
   option.pkCername = @"";
   [[QChatKitClient instance] setupCoreKitQChat:option];
   NEAtMessageManager * _ = [NEAtMessageManager instance];
   

步骤3：登录

在完成初始化后，调用 loginQChat 方法登录 QChat，该方法会自动完成 IM 的登录。

示例代码：

    QChatKitClient.instance.loginQChat(accid, token) { error in
        if let err = error {
            print(" login error : ", err)
        }else {
            //在登录成功回调中初始化路由以及配置各个模块首页
            /*
             weakSelf?.setupTabbar()
             */
        }
    }

[[QChatKitClient instance] loginQChat:@"accid" :@"token" :^(NSError * _Nullable error) {
    if (error != nil) {
        NSLog(@" login error : %@", [error description]);
    } else {
        //在登录成功回调中初始化路由以及配置各个模块首页
        /*
        [weakSelf setupTabbar];
        */
    }
}];

步骤4：界面搭建

以搭建圈组 home 页面为例，更多页面请参见界面集成详情。

示例代码：

swiftfunc qChatExample(){
    let qChatVC = QChatHomeViewController()
    qChatVC.delegate = self
}

- (void)qChatExample {
    QChatHomeViewController *qChatVC = [[QChatHomeViewController alloc] init];
    qChatVC.delegate = self;
}

界面效果参考如下：

后续步骤

为保障通信安全，如果您在调试环境中的使用的是云信控制台生成的测试用 IM 账号 和 token，请确保在后续的正式生产环境中，将其替换为通过 IM 服务端 API 生成的正式 IM 账号（accid）和 token。

相关参考

界面集成详情

圈组 UIKit 中提供的常用业务场景界面及相关集成说明如下：

常见问题排查

pod 冲突报错

• 问题原因

  如果执行步骤1导入组件时，只导入了圈组 UIKit 的 UI 组件，在特殊情况下可能出现库版本不一致导致的报错（UI 组件版本与其内部依赖的基础 kit 库的版本不一致）。

  例如导入的圈组 UIKit 的 UI 组件版本为 v9.5.3，但导入的基础 Kit 库版本为 v9.3.2。这会导致基础库用到日志库（alog)和 UI 组件用到的 alog 不一致，进而导致 pod 冲突报错。

• 处理建议：

  导入 UI 组件时，同时也指定推荐版本的基础 Kit 库。

  以导入 v9.5.3 的 QChat UI 组件为例，推荐的基础 Kit 库版本为：

  #基础kit库
  pod 'NECommonUIKit', '9.6.5'
  pod 'NECommonKit', '9.6.4'
  pod 'NECoreQChatKit', '9.6.5'
  pod 'NECoreKit', '9.6.3'