金易联iOS SDK 集成文档

2019-05-30  本文已影响0人  jasondevios

一、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 <FinChatSDK/FinChatSDK.h>
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 文件的内容如下，字段必须一一对应

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<array>
    <dict>
        <key>themeType</key>
        <integer>2</integer>
        <key>themeName</key>
        <string>热情红</string>
        <key>themeValue</key>
        <dict>
            <key>Bubble_Receive</key>
            <dict>
                <key>receiveBubbleBorderColor</key>
                <string>#CFCFCF</string>
                <key>receiveBubbleColor</key>
                <string>#FFFFFF</string>
            </dict>
            <key>Bubble_Sender</key>
            <dict>
                <key>senderBubbleBorderColor</key>
                <string>#FFD5D3</string>
                <key>senderBubbleColor</key>
                <string>#FFF1F1</string>
            </dict>
            <key>ButtonColor</key>
            <dict>
                <key>buttonDisableColor</key>
                <string>#F3CCCE</string>
                <key>buttonHighlightedColor</key>
                <string>#9F0008</string>
                <key>buttonNormalColor</key>
                <string>#C7000B</string>
            </dict>
            <key>Nav_Color</key>
            <dict>
                <key>navBackgroundColor</key>
                <string>#FAFAFA</string>
                <key>navBarItemDisableColor</key>
                <string>#F0A4A8</string>
                <key>navBarItemHighlightedColor</key>
                <string>#9F0008</string>
                <key>navBarItemNormalColor</key>
                <string>#C7000B</string>
                <key>navTitleColor</key>
                <string>#333333</string>
                <key>navLineColor</key>
                <string>#B0B0B0</string>
            </dict>
            <key>StatusBarStyle</key>
            <dict>
                <key>statusBarStyle</key>
                <string>0</string>
            </dict>
            <key>SwitchColor</key>
            <dict>
                <key>switchDisableOffColor</key>
                <string>#FFFFFF</string>
                <key>switchDisableOnColor</key>
                <string>#F3CCCE</string>
                <key>switchOffColor</key>
                <string>#FFFFFF</string>
                <key>switchOnColor</key>
                <string>#C7000B</string>
            </dict>
            <key>Theme</key>
            <dict>
                <key>themeDisableColor</key>
                <string>#F3CCCE</string>
                <key>themeHighlightedColor</key>
                <string>#9F0008</string>
                <key>themeNormalColor</key>
                <string>#C7000B</string>
            </dict>
        </dict>
    </dict>
</array>
</plist>
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: 我的 开关设置信息

更多的信息请访问我们官网的开发者手册.

上一篇下一篇

猜你喜欢

热点阅读