接入说明
版本说明
本节说明 SDK 版本适用范围、升级路径和版本选择方式,帮助开发者在接入前确认应使用的版本。
注意:本接入文档默认适用于 10.9.2 之后(含 10.9.2)的版本。10.9.2 以前版本请参考本文最后的旧版接入说明。
新客户接入
- 如果您需要使用iOS原生七鱼客服的功能,使用以下版本:QY_iOS_SDK GitHub地址
- 如果您需要通过uniapp的方式接入SDK,您需要使用插件:uniapp插件下载地址
版本升级
- 如果您使用的SDK是QY_iOS_SDK GitHub地址,您正常升级即可。
- 如果您使用的是QY_NIM_iOS_SDK GitHub地址,此次更新的目标版本如果>=10.9.2,您需要做以下改动:
- 在 Podfile 文件中
pod 'QY_NIM_iOS_SDK', '~> x.x.x'
修过为
pod 'QY_iOS_SDK', '~> x.x.x'修改完成后,重新执行pod install命令
- 工程中头文件引入做如下修改:
1、七鱼客服模块
#import <QYSDK_ReName/***.h>
//修改为:
#import <QYSDK/***.h>
2、视频客服模块
#import <QYVideoService_ReName/***.h>
//修改为:
#import <QYVideoService/***.h>
3、IM模块
#import <NIMSDK2/NIMSDK.h>
//修改为:
#import <QYKFNIMSDK/QYKFNIMSDK.h>- 工程中查找出和七鱼业务逻辑有关的NIMSDK类的调用,将NIMSDK替换为QYKFNIMSDK
导入 SDK
本节说明如何将 SDK 集成到项目中,包括依赖引入、手动集成和自动集成等接入方式。
手动集成
QYSDK 在 V5.10.0 版本后已修改为动态库,集成方式相对之前静态库有所改变,若要集成动态库,只需要做以下工作:
- 下载 zip 文件并解压,说明如下:
- QYKFNIMSDK.xcframework 动态库:IM 即时通讯、信令、聊天室的功能集;
- QYKFNIMNOS.xcframework 动态库:IM通讯必须依赖库
- QYSDK.xcframework(老版本是QYSDK.framework) 动态库:七鱼客服功能
- QYVideoService.xcframework 动态库:七鱼客服视频客服模块
- Resources 文件夹:内含资源集合 bundle 文件。
- QYResource.bundle :素材资源
- QYCustomResource.bundle :自定义资源,用于替换 QYResource.bundle 内的同名素材
- QYLanguage.bundle :多语言资源文件
- QYVideoResource.bundle :视频客服模块必须的资源
- 将 QYKFNIMSDK.xcframework、QYKFNIMNOS.xcframework、QYSDK.xcframework 文件夹拖入工程,确保文件 copy 至工程而非引用,并确保 General —> Frameworks, Libraries, and Embedded Content ( >=Xcode11 ) 选项中包含导入的库,同时 Embed 选择 Embed & Sign 即可。
- 如果您需要视频客服模块,需要额外将QYVideoService.xcframework拖入工程,确保文件 copy 至工程而非引用,并确保 General —> Frameworks, Libraries, and Embedded Content ( >=Xcode11 ) 选项中包含导入的库,同时 Embed 选择 Embed & Sign 即可。
- 将 Resources 文件夹中所需的 bundle 资源文件拖入主工程,确保 mainBundle 可以访问到。
注意:如果您不需要视频客服的功能,请不要集成 QYVideoService.xcframework 和 QYVideoResource.bundle,否则将增加不必要的包体积。
自动集成
QYSDK 动态库地址:CocoaPods地址,GitHub地址。集成步骤如下:
- 在 Podfile 文件中加入:
#国内版本
pod 'QY_iOS_SDK', '~> x.x.x'
#国外版本
pod 'QY_iOS_SDK/Abroad', '~> x.x.x'
#视频客服版本
pod 'QY_iOS_SDK/Video', '~> x.x.x'"x.x.x" 代表版本号,例如需要集成 10.9.x 系列的最新版本,可加入如下代码:
#国内版本
pod 'QY_iOS_SDK','10.9.x'
#海外版
pod 'QY_iOS_SDK/Abroad','10.9.x'
#视频客服版
pod 'QY_iOS_SDK/Video','10.9.x'- Terminal cd到podfile所在路径下,然后执行 pod install 即可完整集成动态库版本。
初始化与打开客服
本节说明 SDK 初始化、基础配置以及打开客服会话界面的流程。
初始化SDK
在使用 SDK 任何方法之前,都应该先调用初始化方法,推荐在application: didFinishLaunchingWithOptions:方法中调用。正常业务情况下,初始化方法有且只应调用一次,请勿重复注册。
注册方法原型
@interface QYSDK : NSObject
/**
* 注册SDK
*
* @param option 注册选项
*/
- (void)registerWithOption:(QYSDKOption *)option;
/**
* 注册SDK
*
* @param option 注册选项
* @param completion 完成回调 回调结果为失败,仍然可以打开客服页面,但后台样式设置的效果不生效
* 首次安装,未授权网络权限,会导致初始化失败,可以在回调中调用requestStyleConfig方法再次请求数据
*/
- (void)registerWithOption:(QYSDKOption *)option completion:(QYResultCompletionBlock)completion;
@end以上两个方法都可以使用,建议在didFinishLaunchingWithOptions中调用。带回调的初始化方法即使失败,仍然可以打开客服页面,但是后台样式的数据请求失败,不生效。
选项参数列表
QYSDKOption 提供如下属性:
| 属性 | 类型 | 必须填写 | 说明 |
|---|---|---|---|
| appKey | NSString | 是 | 企业的 AppKey |
| appName | NSString | 是 | App名称,即七鱼管理后台添加App时填写的App名称 |
| pkCerName | NSString | 否 | PushKit推送证书名,暂不支持,无需填写 |
| isFusion | BOOL | 否 | 是否为融合SDK,默认值:NO |
| templateId | long | 否 | 后台样式模板id,具体值请从web侧后台配置的模板中读取 |
调用示例
推荐在 App 启动时进行初始化操作:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {...//推荐在程序启动的时候初始化 SDK
NSString *appKey = @"your app key";
QYSDKOption *option = [QYSDKOption optionWithAppKey:appKey];
option.appName = @"your App name";[[QYSDK sharedSDK] registerWithOption:option];...}- AppKey 可在 管理端-应用-在线系统-设置-在线接入-APP-2.App Key 找到,请确保填写完整及正确,无空格,否则可能导致功能异常。
- AppName 对应管理端添加 App 时填写的 App名称。如需使用访客分流等功能,请及时在管理端添加 App,并填写正确的 bundleID 用于区分不同 App;如需使用推送功能,请选择相应环境上传对应推送证书,请自行确保证书有效性。
- 一般在application: didFinishLaunchingWithOptions:方法中调用初始化方法,如需在其他地方调用,请确保时机在启动客服功能前,且应预留一段初始化时间;尽量保证在整个软件运行期间仅调用一次。
集成聊天组件
通过 QYSDK.sessionViewController 可获取 QYSessionViewController 聊天界面控制器实例:
[[QYSDK sharedSDK] sessionViewController];- 获取界面实例后,必须嵌入至导航栏控制器UINavigationController中,便可获得完整聊天窗口及所有功能。
- QYSessionViewController会使用到导航栏navigationItem的标题文字属性title、标题视图属性titleView、右侧按钮属性rightBarButtonItems,若使用自定义导航栏,请确保以上属性能正常设置,否则会影响部分功能。
- 每次调用[QYSDK sharedSDK]单例的sessionViewController方法,都会新建一个聊天页面,请确保QYSessionViewController实例同一时刻全局唯一,且退出后该界面实例能够正常释放,尽量避免循环引用导致的内存泄漏,否则会引发一系列不可预知问题。
如果调用代码所在的视图控制器在UINavigationController中,可 push 进入聊天界面:
QYSource *source = [[QYSource alloc] init];
source.title = @"七鱼客服";
source.urlString = @"[https://qiyukf.com/](https://qiyukf.com/)";
QYSessionViewController *sessionViewController = [[QYSDK sharedSDK] sessionViewController];
sessionViewController.sessionTitle = @"七鱼客服";
sessionViewController.source = source;
sessionViewController.hidesBottomBarWhenPushed = YES;[self.navigationController pushViewController:sessionViewController animated:YES];如果调用代码所在的视图控制器不在UINavigationController中,可 present 进入聊天界面:
QYSource *source = [[QYSource alloc] init];
source.title = @"七鱼客服";
source.urlString = @"[https://qiyukf.com/](https://qiyukf.com/)";
QYSessionViewController *sessionViewController = [[QYSDK sharedSDK] sessionViewController];
sessionViewController.sessionTitle = @"七鱼客服";
sessionViewController.source = source;
UINavigationController *nav = [[UINavigationController alloc] initWithRootViewController:sessionViewController];[self presentViewController:nav animated:YES completion:nil];一般来说,present 方式需要在左上角加返回按钮:
UIBarButtonItem *leftItem = [[UIBarButtonItem alloc] initWithTitle:@"返回" style:UIBarButtonItemStylePlain target:self action:@selector(onBack:)];
sessionViewController.navigationItem.leftBarButtonItem = leftItem;onBack:的样例:
- (void)onBack:(id)sender {[self dismissViewControllerAnimated:YES completion:nil];}请根据情况选择合适的方式进入聊天界面。
视频客服集成
本节说明视频客服能力的接入方式、依赖配置和进入视频会话时需要关注的参数。
视频客服模块是基于QYSDK和QYKFNIMSDK的。要使用视频客服,必须要先集成这两个QYKFNIMSDK.xcframework和QYSDK.xcframework,这两个SDK的集成方法此处不再赘述,请参考上文。
手动集成
下载 zip 文件并解压,内含QYVideoService.xcframework,Resources文件夹中包含QYVideoResource.bundle资源包。
- 集成 QYVideoService.xcframework :将 QYVideoService.xcframework 文件夹拖入工程,确保文件 copy 至工程而非引用,并确保 General —> Frameworks, Libraries, and Embedded Content ( >=Xcode11 ) 选项中包含导入的库,同时 Embed 选择 Embed & Sign 即可。
- 集成 QYSDK.framework :将 Resources 文件夹中所需的 QYVideoResource.bundle 资源文件拖入主工程,确保 mainBundle 可以访问到。
自动集成
- 将 Podfile 文件中的pod 'QY_iOS_SDK', '~> x.x.x'修改为:
pod 'QY_iOS_SDK/Video', '~> x.x.x'- "x.x.x" 代表版本号
- Terminal cd 到 podfile所在路径下,然后执行 pod install 即可完整集成动态库版本。
自动集成常见问题
使用 CocoaPods 过程中可能遇见的问题:
- 无法用 CocoaPods 下载到最新的 SDK
- 运行 pod repo update 更新本地 CocoaPods 仓库;
- 检查网络环境,确保可以访问并下载 GitHub 相关内容。
- 使用 CocoaPods 下载静态库版本 SDK 后编译报错
可使用 Homebrew 安装 Git LFS:
brew install git-lfs- 启动 Git LFS 服务:
git lfs install- 安装后请重新 pod update,若仍报错,尝试清理缓存:pod cache clean --all 。
集成视频客服组件
如果您的APP需要使用视频客服功能,请在视频客服的入口对QYSessionViewController控制器做如下配置:
sessionViewController.isVideoServer = YES;如果您的APP不仅需要视频客服功能,还需要使用屏幕共享的功能,请在视频客服的入口对QYSessionViewController控制器做如下配置:
sessionViewController.isScreenShare = YES;然后您需要进行App Groups的相关配置,相关设置可以参考文档(opens new window)
注意:appGroup、主工程扩展程序appGroup、主工程target勾选的appGroup三者需要保持统一。
权限与 HTTPS
本节说明 SDK 运行所需权限、隐私合规配置以及 HTTPS 或网络访问相关要求。
权限设置
在 Info.plist 中加入以下内容:
<key>NSPhotoLibraryUsageDescription</key>
<string>需要读取相册权限</string>
<key>NSCameraUsageDescription</key>
<string>需要相机权限</string>
<key>NSMicrophoneUsageDescription</key>
<string>需要麦克风权限</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>需要写入相册权限</string>如果不加,会引发 crash。请注意,iOS11 新增写入相册数据权限 NSPhotoLibraryAddUsageDescription。
https相关
V3.1.3 版本开始,SDK 已全面支持 https,但是聊天消息中可能存在链接,点击链接会用 WKWebView 打开,链接地址有可能是 http 的,为了能够正常打开,需要增加配置项。在 Info.plist 中加入以下内容:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
<key>NSAllowsArbitraryLoadsInWebContent</key>
<true/>
</dict>加了这些配置项,在 iOS9 下,系统仅读取 NSAllowsArbitraryLoads,会放开所有 http 请求;在 iOS10 及以上系统,设置了 NSAllowsArbitraryLoadsInWebContent,就会忽略 NSAllowsArbitraryLoads,效果是只允许 WKWebView 中使用 http。SDK 消息流链接默认使用 WKWebView 打开,可通过截获链接点击事件使用自定义网页视图。
构建配置与常见问题
本节说明编译、构建、混淆、架构兼容等工程配置问题及常见处理方式。
模拟器架构问题
由于库包含模拟器版本,会导致打包失败,故需要在打包前将模拟器版本剥去,具体方法如下:
- 创建 strip_archs.sh 脚本,并放在工程目录中,如 Resources 文件夹里;
- 在 Build Phases 设置项中点击左上角 + 号,选择 New Run Script Phase,工程在编译过程中会自动 run script;
- 在 script 中添加代码,执行 strip_archs.sh 脚本:
/bin/sh "${SRCROOT}/QYSDKDemo/Resources/strip_archs.sh"- 将如下内容复制至脚本中:
#!/bin/sh
# Strip invalid architectures
strip_invalid_archs() {
binary="$1"
echo "current binary ${binary}"
# Get architectures for current file
archs="$(lipo -info "$binary" | rev | cut -d ':' -f1 | rev)"
stripped=""
for arch in $archs; do
if ! [[ "${ARCHS}" == *"$arch"* ]]; then
if [ -f "$binary" ]; then
# Strip non-valid architectures in-place
lipo -remove "$arch" -output "$binary" "$binary" || exit 1
stripped="$stripped $arch"
fi
fi
done
if [[ "$stripped" ]]; then
echo "Stripped $binary of architectures:$stripped"
fi
}
# Your app path
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
# Attention: If you change framework path (not in mainBundle), please reset FRAMEWORKS_PATH with correct path
FRAMEWORKS_PATH="${APP_PATH}/Frameworks"
# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"
strip_invalid_archs "$FRAMEWORK_EXECUTABLE_PATH"
done注意:脚本中的FRAMEWORK_PATH应设置正确目录。
海外版本与环境切换
本节说明国内版、海外版以及环境切换相关配置,帮助开发者选择正确的服务环境。
切换AppKey
10.16.0版本开始,SDK支持切换国内、海外环境。如果您的APP,海外渠道、国内渠道需要使用同一份SDK,同时需要使用不同的AppKey,可以按如下步骤设置:
- 手动或pod集成海外版本
#海外版
pod 'QY_iOS_SDK/Abroad','10.16.0'- 在SDK初始化之前,增加下面的配置
//海外版AppKey,则isMix = NO;国内版AppKey,则isMix = YES;
[QYServerConfig sharedInstance].isMix = YES;日志与排障
本节说明日志开关、日志读取和常见排障入口,便于定位接入和运行问题。
读取日志
为方便追踪问题,七鱼 iOS SDK 会记录一些关键信息日志在本地文件,可通过调用QYSDK.h的如下接口获取日志文件路径:
/**
* 获取七鱼日志文件路径
*
* @return 日志文件路径
*/
- (NSString *)qiyuLogPath; 其他说明
本节收纳不属于单一功能模块但会影响接入体验的补充说明。
类库说明
SDK 主要提供以下类/协议/方法:
| 类/协议 | 描述 | 说明 |
|---|---|---|
| QYHeaders | 头文件集合 | 集合了非平台企业客服功能头文件 |
| QYSDK | SDK 主入口 | 提供初始化/注册/注销/界面及配置对象获取等方法 |
| QYSessionViewController | 聊天界面控制器 | 聊天主界面,同时提供各类参数设置及部分功能接口 |
| QYCustomUIConfig | UI 配置类 | 样式相关设置 |
| QYCustomActionConfig | 事件配置类 | 事件相关设置 |
| QYConversationManager | 会话管理类 | 负责获取会话列表及消息未读数并监听变化 |
| QYSource | 会话来源类 | 会话来源信息,包含标题、链接及自定义信息 |
| QYUserInfo | 用户信息类 | 用户信息,包含ID及详细信息 |
| QYStaffInfo | 客服信息类 | 人工客服信息,可替换人工客服部分信息 |
| QYMessageInfo | 消息类 | 包含消息类型、时间及文本信息 |
| QYSessionInfo | 会话详情类 | 会话列表中会话详情,包含会话状态、未读数等信息 |
| QYCommodityInfo | 商品信息类 | 包含商品标题、描述等信息 |
| QYPushMessage | 推送消息类 | 包含消息类型、头像等信息 |
| QYAction | 通用事件类 | 定义部分通用事件回调,例如请求客服相关事件 |
| QYEvaluation | 评价数据类 | 定义满意度评价数据、选项数据及结果 |
| QYWorkOrderListViewController | 工单列表页面控制器 | 传入工单模板 ID 即可查询访客提交工单历史记录,并提供催单功能 |
| QYServerSetting | 服务器配置类 | 服务器地址设置 |
自定义消息相关:
| 类/协议 | 描述 | 说明 |
|---|---|---|
| QYCustomSDK | 自定义消息头文件集合 | 集合了自定义消息功能头文件 |
| QYCustomSessionViewController | 聊天界面控制器分类 | 提供自定义消息专用属性及接口 |
| QYCustomMessageProtocol | 自定义消息协议 | 事件委托/视图点击协议 |
| QYCustomMessage | 自定义消息基类 | 承载消息数据,可继承并扩展 |
| QYCustomModel | 数据源基类 | 消息列表数据源,可继承并扩展 |
| QYCustomContentView | 消息视图基类 | 消息对应视图,可继承并扩展 |
| QYCustomEvent | 消息事件类 | 消息内点击事件 |
| QYCustomCommodityInfo | 自定义商品信息类 | 自定义商品卡片消息,透传服务端数据 |
平台企业相关:
| 类/协议 | 描述 | 说明 |
|---|---|---|
| QYPOPSDK | 平台企业头文件集合 | 集合了平台企业相关功能头文件 |
| QYPOPSessionViewController | 聊天界面控制器分类 | 提供平台企业专用属性及接口 |
| QYPOPConversationManager | 会话管理类分类 | 提供平台企业会话管理专用接口及协议 |
| QYPOPMessageInfo | 消息类分类 | 提供平台企业专用属性及接口 |
| QYPOPSessionInfo | 会话详情类分类 | 提供平台企业专用属性及接口 |
其它说明
- 为方便集成和后续更新,请使用 V10.9.2以上动态库版本。
- 为保证 SDK 在 iOS13 上效果,请使用 V10.9.2 以上版本;SDK 已针对暗黑模式下的部分显示问题、推送 DeviceToken 解析方式、页面 modalPresentationStyle 做了更新和适配。
- SDK 支持 Bitcode。
- 若您使用的版本为 V10.9.2 及以上,请注意导入多语言资源文件 QYLanguage.bundle,并保证 mainBundle 可访问;否则可能出现部分文案显示为 key 的问题。
- 为方便开发者可同时在真机和模拟器上调试和使用,我们将 arm64、x86_64 平台的 SDK 合并为一个 fat file ,导致整个 SDK 比较大。但实际编译后大约只会增加 App 一个架构的大小。
常见问题
本节汇总开发者接入和使用过程中常见问题,并给出对应处理建议。
这篇文档有帮助吗?