3、FinChat SDK iOS 集成文档
-
1. FinChat SDK 简介
FinoChat SDK 为用户开发 IM 相关的应用提供的一套完善的开发框架。包括以下几个部分:
- SDK_Core: 为核心的消息协议实现,完成与服务器之间的信息交换。
- SDK: 是基于核心协议实现的完整的 IM 功能,实现了不同类型消息的收发、会话管理、群组、好友、聊天室等功能。
- HttpEngine: H5资源加速服务组件
- ConvoUI: 会话型UI交互组件
- FinoChatClient: 是 SDK 的入口,主要完成初始化等功能,也是获取其他模块的入口。
- AccountApi: 负责账户管理相关功能,包括登入、登出等。
- ContacApi: 负责好友的添加删除,黑名单的管理。
- GroupApi: 负责群组的管理,创建、删除群组,管理群组成员等功能。
- ChatRoomApi: 负责聊天室的管理。
- UIApi: 是一组 IM 相关的 UI 控件,旨在帮助开发者快速集成FinoChat SDK。
- ChatUI: 消息聊天界面UI
- ConversationUI: 会话列表UI
- MineUI: “我”的信息UI
- ContactUI: 通讯录UI
2. 集成前的准备工作
注册凡泰开发者账号
首先,去凡泰官网 (https://www.finogeeks.com/) 注册开发者账号,并登录到凡泰Git (https://git.finogeeks.com/) 中。
如果,您仅仅想试用一下,那也可以使用Demo (https://git.finogeeks.com/finchat/finchat-ios-demo) 来体验。
FinChat SDK目前是通过cocopods的形式集成,所以客户需要先注册凡泰开发者账号。
然后,相关对接人会给该账号配置仓库权限,客户将FinChatSDK对应的source添加到podfile中,添加FinChat 依赖即可。申请appKey
另外,FinChat SDK在初始化时,需要配置appKey,该appKey是与bundleId以及客户的后台服务器关联的,所以需要客户提供bundleId和服务器地址,然后再生成appKey。
3. 集成FinChat SDK
目前FinChat SDK 仅提供了Cocoapods的方式集成。 首先,在Podfile中配置资源仓库地址:
source 'https://git.finogeeks.com/cocoapods/finogeeks' source 'https://github.com/CocoaPods/Specs.git'
然后,添加依赖:
pod 'FinChat-Mixins'
如果对Cocoapods不太熟悉的话,可以在项目根目录下创建一个Podfile文件,然后将如下内容拷贝到Podfile中。
platform :ios, "9.0" source 'https://git.finogeeks.com/cocoapods/finogeeks' source 'https://github.com/CocoaPods/Specs.git' inhibit_all_warnings! def podFrameWork pod 'FinChat-Mixins' end target "FinChat" do podFrameWork end post_install do |installer| installer.pods_project.targets.each do |target| target.build_configurations.each do |config| config.build_settings['ENABLE_STRICT_OBJC_MSGSEND'] = 'NO' config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'NO' end end end
注意:这里target 后面的 FinChat是你的工程target名字,你需要将其修改为你的工程的target名字。
4. 安装FinChat SDK
在 Mac 电脑 终端里,进入到podfile 所在的目录,然后执行如下命令:
pod install
安装完成后,使用xxxx.xcworkspace重新打开工程。
5. 修改工程配置
1、Xcode 10以上的版本,需要修改File->Workspace Settings->Build System为:【Legacy Build System】。
1、在Project->Build Settings->Bitcode 设置为【NO】。6. FinChat SDK 在iOS端的使用
6.1 SDK初始化
SDK初始化的实例:
// 初始化需要的配置参数,后面会详细介绍各种配置参数 NSDictionary *configDict = [self configDict]; FinoChatConfig *config = [[FinoChatConfig alloc] initWithDict:configDict]; FinoChatOptions *options = [FinoChatOptions optionsWithConfig:config]; NSError *error = nil; // SDK的初始化 BOOL isInit = [[FinoChatClient sharedInstance] fino_initSDK:options error:&error];
如果appKey等信息配置正确,且在合法时间内,初始化都是极快的。
关于各种配置项以及其含义,可以去iOS开关配置查看。
6.2 主题设置
目前FinChatSDK 内部内嵌了三种主题样式:凡泰蓝、喜庆红、深蓝,如果使用这三种主题样式的话,可以使用如下API来设置。
// 设置主题色 [FINThemeManager setThemeType:FINThemeType_Blue];
如果,您需要自定义主题样式的话,需要使用我们提供的主题模板(theme.plist),然后将其中颜色修改为您需要的颜色即可。
使用自定义的主题,可以这样来设置:
NSString *path = [[NSBundle mainBundle] pathForResource:@"theme" ofType:@"plist"]; [FINThemeManager setThemeTypeWithThemeFilePath:path];
在新版本上修改另一种主题时,可以在设置主题之前移除旧主题:
[FINThemeManager removeCurrentThemeType];
关于主题各个项的含义和控制范围,可以去主题配置查看。
6.3 FinChatSDK 功能使用
判断当前是否已登录
BOOL isLogin = [[FinoChatClient sharedInstance].finoAccountManager isLogin]
当app启动时,可以根据该api来判断是跳转到登录页还是跳转到主页。
- 会话列表页创建
UIViewController *messageVC = [[FinoChatClient sharedInstance].finoChatUIManager conversationViewController];
- 通讯录列表页创建
UIViewController *contactVC = [[FinoChatClient sharedInstance].finoChatUIManager addressBookControllerWithContactsDelegate:nil contactsDataSource:nil];
- 工作页创建
UIViewController *workVC = [[FinoChatClient sharedInstance].finoChatUIManager workViewController];
- 我的页面创建
UIViewController *mineVC = [[FinoChatClient sharedInstance].finoChatUIManager mineViewControllerWithList:list callback:^(NSString *cellMark) { NSLog(@"你点击了%@", cellMark); }];
注意:FinChat SDK中的部分接口需要在登录条件下才可调用,所以api内部会校验appKey的有效性,以及当前是否已登录,如果未登录则会返回nil。
- 登录功能
登录其实是有多种方式,比如使用账号和密码登录。
[[FinoChatClient sharedInstance].finoAccountManager login:userName password:password success:^(NSDictionary* ret) { } failure:^(NSError *error) { }];
使用token登录
[[FinoChatClient sharedInstance].finoAccountManager loginWithToken:token success:^(NSDictionary *result) { } failure:^(NSError *error) { }];
- 使用手机号和验证码登录
[[FinoChatClient sharedInstance].finoAccountManager loginWithMobile:mobile verification:code success:^(NSDictionary *result) { } failure:^(NSError *error) { }];