集成 IM UIKit - IM 即时通讯 UIKit

开发者中心

IM 即时通讯 UIKit

集成开发

集成 IM UIKit

更新时间： 2024/11/14 18:32:58

云信 IM UIKit 是基于 NIM SDK（网易云信 IM SDK）开发的一款即时通讯 UI 组件库，包括聊天、会话列表、通讯录、群管理等组件。

云信 IM UIKit 自 9.6.1 版本开始新增全新的通用版 UI 组件，原有的 UI 组件（基础版）依旧保留，您可以根据需求自行选择基础版或通用版 UI 组件。

基础版 UI

通用版 UI

本文介绍如何快速跑通 IM UIKit 的集成流程。

前提条件

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

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

注意事项

由于 IM UIKit 的初始化与登录是通过底层调用 NIM SDK 接口来实现的，因此重复调用 IM UIKit 和 NIM SDK 的初始化与登录接口会相互覆盖传入的信息（包括推送配置信息）。

所以若用户同时集成 IM UIKit 和 NIM SDK，只需要调用一次初始化与登录接口即可。

实现流程

步骤1：按需导入组件

根据业务需要，在 “Podfile” 文件中，以添加依赖的形式添加相应的 IM UIKit 组件。

例如，需要会话聊天功能，可添加 pod 'NEChatUIKit' 和 pod 'NEChatKit'。

导入 UI 组件时，需要指定相同版本的基础 Kit 库引入，否则可能导致后续出现报错。具体可参见下文的常见问题排查。
IM UIKit 底层依赖 NIM SDK。
- 若引入 UI 组件时不指定 NIM SDK 版本，那么将默认引入当前兼容的最新版本（参考更新日志）。
- 若引入 UI 组件时需要使用指定 NIM SDK 的版本，那么需要在引入时填写正确的版本号，具体请参考以下示例代码。

不指定 NIM SDK 版本

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!

# 基础 Kit 库
pod 'NECommonUIKit', '9.7.1'
pod 'NECommonKit', '9.6.6'
pod 'NECoreIMKit', '9.6.7'
pod 'NECoreKit', '9.6.6'
pod 'NEChatKit', '9.7.3'

# UI 组件，依次为通讯录组件、会话列表组件、会话（聊天）组件、群相关设置组件
pod 'NEContactUIKit', '9.7.3'
pod 'NEConversationUIKit', '9.7.3'
pod 'NEChatUIKit', '9.7.3'
pod 'NETeamUIKit', '9.7.3'     

# 扩展库-地理位置组件
pod 'NEMapKit', '9.7.3'

# 扩展库-呼叫组件
pod 'NIMSDK_LITE','9.14.2'
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

指定 NIM SDK 版本

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!

# 指定 NIM SDK 版本，以9.11.0 为例
pod 'NIMSDK_LITE','9.11.0'

# 基础 Kit 库
pod 'NECoreKit', '9.6.6'
pod 'NECoreIMKit/NOS_Special', '9.6.7'
pod 'NEChatKit/NOS_Special', '9.7.3'
pod 'NECommonKit', '9.6.6'
pod 'NECommonUIKit', '9.7.1'

# UI 组件，依次为通讯录组件、会话列表组件、会话（聊天）组件、群相关设置组件
pod 'NEContactUIKit/NOS_Special', '9.7.3'      
pod 'NEConversationUIKit/NOS_Special', '9.7.3' 
pod 'NEChatUIKit/NOS_Special', '9.7.3'         
pod 'NETeamUIKit/NOS_Special', '9.7.3'         

# 扩展库-地理位置组件
pod 'NEMapKit/NOS_Special', '9.7.3'         

# 扩展库-呼叫组件
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

（海外数据中心）不指定 NIM SDK 版本

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!

# 基础 Kit 库
pod 'NECoreKit', '9.6.6'
pod 'NECoreIMKit/FCS', '9.6.7'
pod 'NEChatKit/FCS', '9.7.3'
pod 'NECommonKit', '9.6.6'
pod 'NECommonUIKit', '9.7.1'

# UI 组件，依次为通讯录组件、会话列表组件、会话（聊天）组件、群相关设置组件
pod 'NEContactUIKit/FCS', '9.7.3'      
pod 'NEConversationUIKit/FCS', '9.7.3' 
pod 'NEChatUIKit/FCS', '9.7.3'         
pod 'NETeamUIKit/FCS', '9.7.3'         

# 扩展库-地理位置组件
pod 'NEMapKit/FCS', '9.7.3'         

# 扩展库-呼叫组件
pod 'NIMSDK_LITE/FCS','9.14.2'
pod 'NERtcCallKit/FCS_Special', '2.2.0'
pod 'NERtcCallUIKit/FCS_Special', '2.2.0'

# 扩展库，依次为 RTC 音视频基础组件、RTC 音视频神经网络组件（使用背景虚化功能需要集成）、RTC 音视频背景分割组件（使用背景虚化功能需要集成）
pod 'NERtcSDK/RtcBasic', '5.5.2'         
pod 'NERtcSDK/Nenn'                     
pod 'NERtcSDK/Segment'                  

end

（海外数据中心）指定 NIM SDK 版本

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!

# 指定 NIM SDK 版本，以9.11.0 为例
pod 'NIMSDK_LITE/FCS','9.11.0'

# 基础 Kit 库
pod 'NECoreKit', '9.6.6'
pod 'NECoreIMKit/FCS_Special', '9.6.7'
pod 'NEChatKit/FCS_Special', '9.7.3'
pod 'NECommonKit', '9.6.6'
pod 'NECommonUIKit', '9.7.1'

# UI 组件，依次为通讯录组件、会话列表组件、会话（聊天）组件、群相关设置组件
pod 'NEContactUIKit/FCS_Special', '9.7.3'      
pod 'NEConversationUIKit/FCS_Special', '9.7.3' 
pod 'NEChatUIKit/FCS_Special', '9.7.3'         
pod 'NETeamUIKit/FCS_Special', '9.7.3'         

# 扩展库-地理位置组件
pod 'NEMapKit/FCS_Special', '9.7.3'         

# 扩展库-呼叫组件
pod 'NERtcCallKit/FCS_Special', '2.2.0'
pod 'NERtcCallUIKit/FCS_Special', '2.2.0'

# 扩展库，依次为 RTC 音视频基础组件、RTC 音视频神经网络组件（使用背景虚化功能需要集成）、RTC 音视频背景分割组件（使用背景虚化功能需要集成）
pod 'NERtcSDK/RtcBasic', '5.5.2'         
pod 'NERtcSDK/Nenn'                     
pod 'NERtcSDK/Segment'                  

end

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

各 UI 组件相互独立，添加或删除均不影响项目编译。
示例代码中的 9.6.3 为版本号，仅用于示例。建议使用最新版本。如果出现类似“版本不存在”的报错，可执行pod update命令，然后双击 .xcworkspace 文件，启动项目即可。
暂不支持 bitcode。
更多组件导入信息，请参见组件导入。

步骤2：初始化

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

示例代码：

Swift

import NECoreKit
import NECoreIMKit
import NEChatKit
import NEChatUIKit
import NERtcCallUIKit
...

Objective-C

#import <NECoreKit/NECoreKit-Swift.h>
#import <NECoreIMKit/NECoreIMKit-Swift.h>
#import <NEChatKit/NEChatKit-Swift.h>
#import <NEChatUIKit/NEChatUIKit-Swift.h>
#import <NERtcCallUIKit/NERtcCallUIKit.h>
...

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

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

示例代码：

Swift

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

Objective-C

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

更多初始化说明，请参见初始化。

步骤3：登录

在完成初始化后，调用 loginIM 方法登录 IM。

示例代码：

Swift

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

Objective-C

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

调用登录的方法时，将示例代码中的 accid 和 token 分别替换为您的云信账号 ID （即 accid）和 Token。

步骤4：初始化路由

如果未在登录成功回调中初始化路由，需要单独初始化路由，才能进行后续的界面搭建。在初始化路由时可同时初始化地图 Map，初始化后，您的应用即可实现地理位置消息功能。具体请参见实现地理位置消息功能。

示例代码：

Swift

 func loadService() {
        //初始化路由
        ContactRouter.register()
        ChatRouter.register()
        TeamRouter.register()
        ConversationRouter.register()
        //注册个人设置页面，用于实现单击头像后跳转至个人设置页面功能
        Router.shared.register(MeSettingRouter) { param in
            if let nav = param["nav"] as? UINavigationController {
                let me = PersonInfoViewController()
                nav.pushViewController(me, animated: true)
            }
        }
        
        //地图map初始化
        NEMapClient.shared().setupMapClient(withAppkey: AppKey.gaodeMapAppkey)
    }

Objective-C

- (void)registerRouter {
    [ContactRouter register];
    [ChatRouter register];
    [TeamRouter register];
    [ConversationRouter register];
        //注册个人设置页面，用于实现单击头像后跳转至个人设置页面功能
    [[Router shared] register:MeSettingRouter
                      closure:^(NSDictionary<NSString *, id> *_Nonnull param) {
        NSObject *param1 = [param objectForKey:@"nav"];
        if ([param1 isKindOfClass:[UINavigationController class]]) {
        UINavigationController *nav = (UINavigationController *)param1;
        PersonInfoViewController *me =
            [[PersonInfoViewController alloc] init];

        [nav pushViewController:me animated:YES];
        }
    }];

    //地图map初始化
    [[NEMapClient shared] setupMapClientWithAppkey:@"gaodeMap Appkey"];
}

若需要注册个人设置页面，实现单击头像后跳转至个人设置页面的功能，首先需要在 XCode 中拖入相关的源码文件至您的工程。相关的源码文件包括：
- app 下的 Mine 文件
- app 下 Assets 中的 Mine 文件
示例代码中的路由跳转都跳转至基础版 UI 界面，若需要使用通用版 UI 界面，切换注册路由方法即可。例如将 ChatRouter.register() 替换为 ChatRouter.registerFun()；ContactRouter.register() 替换为 ContactRouter.registerFun() 等。

步骤5：界面搭建

基础版 UI 界面搭建

以搭建单聊群聊页面为例，示例代码如下（更多详情请参见下文的界面集成详情）：

示例代码：

Swift 示例：

swiftfunc chatExample(){
    let session = NIMSession("accid", type: .P2P)
    let p2pChatVC = P2PChatViewController(session: session)
        
    let teamSession = NIMSession("team id", type: .team)
    let groupVC = GroupChatViewController(session: teamSession, anchor: nil)
}

Objective-C 示例：

- (void)chatExample {
    NIMSession *session = [NIMSession session:@"accid" type:NIMSessionTypeP2P];
    P2PChatViewController *p2pChatVC = [[P2PChatViewController alloc] initWithSession:session];
    
    NIMSession *teamSession = [NIMSession session:@"accid" type:NIMSessionTypeTeam];
    GroupChatViewController *groupVC = [[GroupChatViewController alloc] initWithSession:teamSession anchor:nil];
}

参数说明：

参数	说明
`accid`	网易云信账号ID，可调用注册云信 IM 账号 API 创建
`type`	聊天类型，`.P2P`-单聊，`.team`-群聊

界面效果参考如下：

通用版 UI 界面搭建

以搭建单聊群聊页面为例，示例代码如下：

示例代码：

Swift 示例：

swiftfunc chatExample(){
    let session = NIMSession("accid", type: .P2P)
    let p2pChatVC = FunP2PChatViewController(session: session)
        
    let teamSession = NIMSession("team id", type: .team)
    let groupVC = FunGroupChatViewController(session: teamSession, anchor: nil)
}

Objective-C 示例：

- (void)chatExample {
    NIMSession *session = [NIMSession session:@"accid" type:NIMSessionTypeP2P];
    FunP2PChatViewController *p2pChatVC = [[FunP2PChatViewController alloc] initWithSession:session];
    
    NIMSession *teamSession = [NIMSession session:@"accid" type:NIMSessionTypeTeam];
    FunGroupChatViewController *groupVC = [[FunGroupChatViewController alloc] initWithSession:teamSession anchor:nil];
}

参数说明：

参数	说明
`accid`	网易云信账号ID，可调用注册云信 IM 账号 API 创建
`type`	聊天类型，`.P2P`-单聊，`.team`-群聊

界面效果参考如下：

后续步骤

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

页面	所属组件	描述
`ConversationController`	NEConversationUIKit	会话列表页面（创建或者跳转到该界面需要传入参数，详见集成会话列表界面）修改界面 UI 请参见自定义会话列表 UI
`ContactsViewController`	NEContactUIKit	通讯录页面（创建或者跳转到该界面需要传入参数，详见集成通讯录界面）修改界面 UI 请参见自定义通讯录 UI
`P2PChatViewController` `GroupChatViewController`	NEChatUIKit	单聊、群聊会话页面（创建或者跳转到该界面需要传入参数，详见集成会话消息界面）修改界面 UI 请参见自定义会话消息 UI
`TeamSettingViewController`	NETeamKit	群组设置页面

前提条件

注意事项

实现流程

步骤1：按需导入组件

步骤2：初始化

步骤3：登录

步骤4：初始化路由

步骤5：界面搭建

后续步骤

相关参考

界面集成详情

音视频通话

常见问题排查

pod 冲突报错

集成报错处理