一、iOS SDK 介绍
FinoChat SDK 为用户开发 IM 相关的应用提供的一套完善的开发框架。包括以下几个部分：
image
* 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
二、SDK获取方式和集成
1.注册账号
登录凡泰极客官网,点击右上角登录,选注册，填入注册信息。
image.png
2.获取SDK
进入凡泰极客开源社区，登录步骤1注册的账号，就能看到所有的开源的SDK以及SDK的版本号。
image.png
注：
为了更好的服务开发者，我们会给每个开发者指定一个仓库，用于后续的SDK交付工作，该类型的仓库是私有仓库，对于不是该指定团队的开发者，是没有权限查看的，要想获取私有仓库的开发者权限，请联系我们。
3.SDK的版本下载说明
我们的SDK在持续的更新中，每月甚至是每两周都会更新一个新版本的SDK，为了更好的维护SDK的版本，我们所有的SDK都是通过cocopods指定版本号进行交付,开发者可以通过cocopods下载SDK。cocopods下载的Podfile文件示例如下
platform :ios, "9.0"
source 'https://git.finogeeks.com/cocoapods/finogeeks'
source 'https://git.finogeeks.com/cocoapods/FinPods'
source 'https://github.com/CocoaPods/Specs.git'
inhibit_all_warnings!
target "FINSwanCocopods" do
pod 'FinChat-Mixins'
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
注：
3.1. 如果是开发者的指定私有仓库，请将
source 'https://git.finogeeks.com/cocoapods/finogeeks'
源修改为
source 'https://git.finogeeks.com/cocoapods/私有仓库名称'.
3.2. 如果是指定的版本号，请加上版本号，例如:
pod 'FinChat-Mixins','3.9.602'
4.申请SDK的AppKey
每个项目的AppKey是唯一的，与项目的唯一标示绑定，具体的获取方式请咨询对接的商务或者联系我们。
5.SDK的framework说明
FinChat.framework : SDK核心组件
MatrixSDK.framework : SDK核心组件
fincore.framework : SDK核心组件
FinChatSDK.framework : 核心SDK,提供定制化接口以及SDK的初始化类
Realm.framework : 数据存储服务
FinApplet.framework : 小程序组件
FINWebRTC.framework : 音视频会议核心组件
JitsiMeet.framework : 音视频核心框架
6.SDK集成
6.1 创建一个新的工程,我们将其命名为FINSwanDemo。创建完成后如图所示：
image.png
6.2 创建Podfile文件，文件的存放位置在项目的根目录，与 FINSwanDemo.xcodeproj 同一级。
Podfile 文件内容如下
platform :ios, "9.0"
source 'https://git.finogeeks.com/cocoapods/finogeeks'
source 'https://git.finogeeks.com/cocoapods/FinPods'
source 'https://github.com/CocoaPods/Specs.git'
inhibit_all_warnings!
target "FINSwanCocopods" do
pod 'FinChat-Mixins'
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
6.3 打开终端，cd到FINSwanDemo文件目录，执行 pod install 。（注：如果没有安装cocopods，请先安装:参考链接).
image.png
注：请确保本地的SDK是最新的版本，如果不确定，请先更新
pod update
pod install
6.4 pod update 成功之后，文件的目录结构如下，我们打开 FINSwanDemo.xcworkspace进行开发。
。
6.5 由于目前SDK暂时不支持bitcode，所以需要关闭bitcode。
在Project->Build Settings->Bitcode 设置为【NO】。
image.png
6.6 Xcode 10以上的版本，需要设置File->Workspace Settings->Build System为：【Legacy Build System】。
到目前为止,SDK的集成工作已经完成了,下面开始讲解SDK的使用。
7 SDK的初始化
7.1 导入SDK头文件
#import
7.2 构造SDK配置对象
// 1.设置信息app的运行环境和信息
NSDictionary *appConfig = @{
@"apiURL":@"https://mini.finogeeks.club",//app的 服务器地址
@"finochatApiPrefix":@"/api/v1", //app 服务器的版本号
@"appType":@"STAFF", //app 的类型 目前有 STAFF(员工端) 和 RETAIL(客户端)两种
@"appId":[NSBundle mainBundle].bundleIdentifier,//项目的唯一标示
@"appKey":@"请填写您申请的appKey" , //App 授权码
@"pushGatewayURL":@"http://push-service.platform:5000/_matrix/push/v1/notify", //app APNS推送服务地址
@"pusherAppIdProd":[NSBundle mainBundle].bundleIdentifier, //app APNS生产环境的推送appId 即BundleId
@"pusherAppIdDev":[NSBundle mainBundle].bundleIdentifier, //app APNS开发环境的推送appId 即BundleId
@"settings":@{ //功能的配置信息
@"urlSchemaPrefix":@"urlSchema", //app的 urlSchema（用于app的分享和）
@"encryptedPassword":@(NO), //app 是否开启加密登录
},
};
// 2.构造配置信息对象
FinoChatConfig *config = [[FinoChatConfig alloc] initWithDict:nil];
FinoChatOptions *options = [FinoChatOptions optionsWithConfig:config];
options.isAPNSRegistered = YES;
7.3 初始化SDK
NSError *error = nil;
[[FinoChatClient sharedInstance] fino_initSDK:options error:&error];
if (!error) {
NSLog(@"FinChatSDK 初始化成功");
}
到目前为止,SDK的集成工作已经完成了,下面开始讲解SDK的API接口的的使用。
8. SDK UI组件的调用
SDK提供了一系列的接口供开发者调用，所有开放的API接口以及注释可以查看 FinoChatClient 这个类，详情请点击，下面我们举个例子来说明接口的调用，其他的以此类推，所有的API接口必须在登录成功后才能访问。
8.1 账户登陆API (目前提供账号密码、手机号验证码以及token三种登录方式)
//1 账户密码登录
[[FinoChatClient sharedInstance].finoAccountManager login:@"staff1" password:@"123456" success:^(NSDictionary *result) {
} failure:^(NSError *error) {
}];
//2 token登录
[[FinoChatClient sharedInstance].finoAccountManager loginWithToken:@"token" success:^(NSDictionary *result) {
} failure:^(NSError *error) {
}];
//3 账号密码登录
[[FinoChatClient sharedInstance].finoAccountManager loginWithMobile:@"138xxxxxxxx" verification:@"1234" success:^(NSDictionary *result) {
} failure:^(NSError *error) {
}];
//退出当前账号
[[FinoChatClient sharedInstance].finoAccountManager logout];
8.2 退出账户和删除用户数据
//1.异步退出当前账号
[[FINServiceFactory sharedInstance].accountManager logoutRemoveAccountCompleteBlock:^{
}];
//2.删除缓存的用户信息
[[FINServiceFactory sharedInstance].accountManager deleteAllCacheData];
8.3 获取会话列表（消息列表）
UIViewController *conversation = [[FinoChatClient sharedInstance].finoChatUIManager conversationViewControllerWithDelegate:nil];
// 获取未读消息的数量
NSInteger messageCount = [[[FinoChatClient sharedInstance] finoChatRoomManager] missedNotificationsCount];
8.4 根据聊天房间id 打开聊天房间
NSString *roomId = @"xxxx";//聊天房间的id
UIViewController *chatRoomController = [[FinoChatClient sharedInstance].finoChatUIManager chatViewControllerWithRoomId:roomId];
8.5 获取金易联SDK工作界面
UIViewController *workController = [[FinoChatClient sharedInstance].finoSwanUIManager swanOrderListViewController];
8.6 获取金易联SDK个人信息界面
UIViewController *mimeController = [[FinoChatClient sharedInstance].finoSwanUIManager swanMineViewController];
8.7 根据员工id 获取员工信息
NSString *staffId = @"xxx";//员工id
UIViewController *mimeController = [[FinoChatClient sharedInstance].finoSwanUIManager swanStaffInfoWithStaffId:staffId completeBlock:^(NSError *error, NSDictionary *responseObj) {
}];
8.8 主题色获取和设置
app的UI层面的颜色均可通过主题的配置，主题设配置信息如下
8.8.1 通过字典进行配置
NSMutableDictionary *themeConfig = [[NSMutableDictionary alloc] init];
//主题色
NSMutableDictionary *theme = [[NSMutableDictionary alloc] init];
[theme setValue:@"#4285F4" forKey:@"themeNormalColor"]; //普通状态下的主题色
[theme setValue:@"#2E6FDA" forKey:@"themeHighlightedColor"];//高亮状态下的主题色
[theme setValue:@"#CED2D6" forKey:@"themeDisableColor"];//不可选状态下的主题色
[themeConfig setObject:theme forKey:@"Theme"];
//Nav_Color 导航栏颜色
NSMutableDictionary *nav_Color = [[NSMutableDictionary alloc] init];
[nav_Color setValue:@"#FAFAFA" forKey:@"navBackgroundColor"];//导航栏背景颜色
[nav_Color setValue:@"#333333" forKey:@"navTitleColor"];//导航栏标题颜色
[nav_Color setValue:@"#4285F4" forKey:@"navBarItemNormalColor"];//导航栏item的普通状态颜色
[nav_Color setValue:@"#2E6FDA" forKey:@"navBarItemHighlightedColor"];//导航栏item的高亮状态颜色
[nav_Color setValue:@"#CED2D6" forKey:@"navBarItemDisableColor"];//导航栏item的不可点击状态颜色
[nav_Color setValue:@"#FAFAFA" forKey:@"navLineColor"];//导航栏分割线的颜色
[themeConfig setObject:nav_Color forKey:@"Nav_Color"];
//Bubble_Sender
NSMutableDictionary *bubble_Sender = [[NSMutableDictionary alloc] init];
[bubble_Sender setValue:@"#AAC9FD" forKey:@"senderBubbleColor"];//发送方消息气泡背景的颜色
[bubble_Sender setValue:@"#7D9DD1" forKey:@"senderBubbleBorderColor"];//发送方消息气泡描边的颜色
[themeConfig setObject:bubble_Sender forKey:@"Bubble_Sender"];
//Bubble_Receive
NSMutableDictionary *bubble_Receive = [[NSMutableDictionary alloc] init];
[bubble_Receive setValue:@"#FFFFFF" forKey:@"receiveBubbleColor"];//接受方消息气泡背景的颜色
[bubble_Receive setValue:@"#CFCFCF" forKey:@"receiveBubbleBorderColor"];//接受方消息气泡描边的颜色
[themeConfig setObject:bubble_Receive forKey:@"Bubble_Receive"];
//ButtonColor
NSMutableDictionary *buttonColor = [[NSMutableDictionary alloc] init];
[buttonColor setValue:@"#4285F4" forKey:@"buttonNormalColor"];//普通状态下的按钮颜色
[buttonColor setValue:@"#2E6FDA" forKey:@"buttonHighlightedColor"];//高亮状态下的按钮颜色
[buttonColor setValue:@"#CED2D6" forKey:@"buttonDisableColor"];//不可点击状态下的按钮颜色
[themeConfig setObject:buttonColor forKey:@"ButtonColor"];
//SwitchColor
NSMutableDictionary *switchColor = [[NSMutableDictionary alloc] init];
[switchColor setValue:@"#FFFFFF" forKey:@"switchOffColor"];//开关关闭的颜色
[switchColor setValue:@"#4285F4" forKey:@"switchOnColor"];//开关开启的颜色
[switchColor setValue:@"#FFFFFF" forKey:@"switchDisableOffColor"];//开关不可用时开关开启的颜色
[switchColor setValue:@"#B3C4F8" forKey:@"switchDisableOnColor"];//开关不可用时开关关闭的颜色
[themeConfig setObject:switchColor forKey:@"SwitchColor"];
//StatusBarStyle
NSMutableDictionary *statusBarStyle = [[NSMutableDictionary alloc] init];
[statusBarStyle setValue:@"0" forKey:@"statusBarStyle"];//状态栏的颜色 （黑0 白1）
[themeConfig setObject:statusBarStyle forKey:@"StatusBarStyle"];
//设置主题色
[FINThemeManager addThemeTypeThemeConfigr:themeConfig themeName:@"自定义颜色" themeType:99];
[FINThemeManager setThemeType:99];
8.8.2 通过plist文件进行配置
[FINThemeManager setThemeType:3];
NSString *path = [[NSBundle mainBundle] pathForResource:@"theme" ofType:@"plist"];
[FINThemeManager setThemeTypeWithThemeFilePath:path];
theme.plist 文件的内容如下，字段必须一一对应
themeType
2
themeName
热情红
themeValue
Bubble_Receive
receiveBubbleBorderColor
#CFCFCF
receiveBubbleColor
#FFFFFF
Bubble_Sender
senderBubbleBorderColor
#FFD5D3
senderBubbleColor
#FFF1F1
ButtonColor
buttonDisableColor
#F3CCCE
buttonHighlightedColor
#9F0008
buttonNormalColor
#C7000B
Nav_Color
navBackgroundColor
#FAFAFA
navBarItemDisableColor
#F0A4A8
navBarItemHighlightedColor
#9F0008
navBarItemNormalColor
#C7000B
navTitleColor
#333333
navLineColor
#B0B0B0
StatusBarStyle
statusBarStyle
0
SwitchColor
switchDisableOffColor
#FFFFFF
switchDisableOnColor
#F3CCCE
switchOffColor
#FFFFFF
switchOnColor
#C7000B
Theme
themeDisableColor
#F3CCCE
themeHighlightedColor
#9F0008
themeNormalColor
#C7000B
image.png
8.9 分享的配置
注册微信分享
//1.注册微信分享
NSString *wxId = @"xxxx";
[[FinoChatClient sharedInstance].finoThirdPShareManager registerWXShare:@{
@"wxId": wxId
}];
//2. 设置分享信息的代理
[FINSettingsInfo manager].delegate = self;
//3.实现代理方法返回分享信息
/**
获取分享信息
@return 返回分享的配置信息
*/
- (FINShareInfo *)shareParameterWithShareActionType:(FINSwanShareActionType)shareActionType appletName:(NSString *)appletName
{
FINShareInfo *shareInfo = [[FINShareInfo alloc] init];
shareInfo.webpageUrl = @"https://www.finogeeks.com/#/";
shareInfo.postersTips = @"扫描二维码 来小程序加我";
//凡泰金易联
shareInfo.appletId = @"xxxx";
shareInfo.appletImage = [UIImage imageNamed:@"gws_wechat_cover_im"];
shareInfo.title = shareInfo.desc = @"财富管理营销服务解决方案";
shareInfo.finSwanAppletType = kFinSwanAppletType_SWAN_IM;
shareInfo.appletType = 0;
shareInfo.appletName = @"凡泰金易联";
return shareInfo;
}
注：更多的接口和API请访问 FinoChatSDK 文档.
9.其他
为了更好的服务开发者，SDK还提供了一系列的开关配置供开发者定制SDK，所有的开关配置以及说明在FINSettingsInfo类中。开关的配置需要在SDK初始化的时候配置完成，即在步骤7.2中设置，例如：需要实现以下三个开关
1.开启自动添加好友功能。（现象：个人详情界面添加好友按钮隐藏）
2.显示截屏反馈功能。（现象：截屏的时候回显示报错弹窗）
3.开启主题设置。（现象：个人中心 - 设置中-多一个主题设置的选项）
4.关闭音视频和音视频会议功能。（现象：聊天房间内 键盘的+会隐藏语音聊天和视频聊天入口）。
5.关闭创建群聊功能。（现象：会话列表会右上角会隐藏发起群聊入口）
5.关闭修改用户名。（现象：用户的姓名不能被修改）
那么配置文件可以修改如下
NSDictionary *appConfig = @{
@"apiURL":@"https://mini.finogeeks.club",//app的 服务器地址
@"finochatApiPrefix":@"/api/v1",//app 服务器的版本号
@"appType":@"STAFF", //app 的类型 目前有 STAFF(员工端) 和 RETAIL(客户端)两种
@"appId":[NSBundle mainBundle].bundleIdentifier,//项目的唯一标示
@"appKey":@"请填写您申请的appKey",//App 授权码
@"pushGatewayURL":@"http://push-service.platform:5000/_matrix/push/v1/notify", //app APNS推送服务地址
@"pusherAppIdProd":[NSBundle mainBundle].bundleIdentifier, //app APNS生产环境的推送appId 即BundleId
@"pusherAppIdDev":[NSBundle mainBundle].bundleIdentifier, //app APNS开发环境的推送appId 即BundleId
@"settings":@{ //功能的配置信息
@"urlSchemaPrefix":@"urlSchema", //app的 urlSchema（用于app的分享和）
@"encryptedPassword":@(NO), //app 是否开启加密登录
@"conversation":@{ //会话列表的配置
@"isShowGroupChat":@(YES),//是否显示创建群聊
},
@"chat":@{
@"isVideoChat":@(NO),//是否显示音视频聊天
@"isVideoConference":@(NO),//是否显示音视频会议
},
@"swan":@{ //金易联的配置
@"showThemeSetting":@(YES),//是否显示主题设置
},
@"addressBook":@{ //通讯录的配置
@"autoAddFriend":@(YES),//是否开启自动添加好友
},
@"mine":@{ //个人信息的配置
@"disableEditName":@(YES),//是否不允许允许修改用户名
},
},
};
更多的配置信息请查看
FINSwanSettingsInfo : 金易联 开关设置信息
FINChatMessageSettingsInfo : 聊天房间内 开关设置信息
FINConvosationSettingsInfo : 会话列表 开关设置信息
FINAddressBookSettingsInfo : 通讯录 开关设置信息
FINMineSettingsInfo: 我的 开关设置信息