七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入

接入说明

版本说明

本节说明 SDK 版本适用范围、升级路径和版本选择方式,帮助开发者在接入前确认应使用的版本。

注意:本接入文档默认适用于 10.9.2 之后(含 10.9.2)的版本。10.9.2 以前版本请参考本文最后的旧版接入说明。

新客户接入

  1. 如果您需要使用iOS原生七鱼客服的功能,使用以下版本:QY_iOS_SDK GitHub地址
  2. 如果您需要通过uniapp的方式接入SDK,您需要使用插件:uniapp插件下载地址

版本升级

  1. 如果您使用的SDK是QY_iOS_SDK GitHub地址,您正常升级即可。
  2. 如果您使用的是QY_NIM_iOS_SDK GitHub地址,此次更新的目标版本如果>=10.9.2,您需要做以下改动:
  3. 在 Podfile 文件中
pod 'QY_NIM_iOS_SDK', '~> x.x.x'
修过为
pod 'QY_iOS_SDK', '~> x.x.x'

修改完成后,重新执行pod install命令

  1. 工程中头文件引入做如下修改:
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>
  1. 工程中查找出和七鱼业务逻辑有关的NIMSDK类的调用,将NIMSDK替换为QYKFNIMSDK

导入 SDK

本节说明如何将 SDK 集成到项目中,包括依赖引入、手动集成和自动集成等接入方式。

QYSDK 提供两种集成方式:既可以通过 CocoaPods 自动集成,也可以手动下载 SDK并集成至您的项目中。

手动集成

QYSDK 在 V5.10.0 版本后已修改为动态库,集成方式相对之前静态库有所改变,若要集成动态库,只需要做以下工作:

  1. 下载 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 :视频客服模块必须的资源
  2. 将 QYKFNIMSDK.xcframework、QYKFNIMNOS.xcframework、QYSDK.xcframework 文件夹拖入工程,确保文件 copy 至工程而非引用,并确保 General —> Frameworks, Libraries, and Embedded Content ( >=Xcode11 ) 选项中包含导入的库,同时 Embed 选择 Embed & Sign 即可。
  3. 如果您需要视频客服模块,需要额外将QYVideoService.xcframework拖入工程,确保文件 copy 至工程而非引用,并确保 General —> Frameworks, Libraries, and Embedded Content ( >=Xcode11 ) 选项中包含导入的库,同时 Embed 选择 Embed & Sign 即可。
  4. 将 Resources 文件夹中所需的 bundle 资源文件拖入主工程,确保 mainBundle 可以访问到。

注意:如果您不需要视频客服的功能,请不要集成 QYVideoService.xcframework 和 QYVideoResource.bundle,否则将增加不必要的包体积。

自动集成

QYSDK 动态库地址:CocoaPods地址,GitHub地址。集成步骤如下:

  1. 在 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'
  1. 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 提供如下属性:

属性类型必须填写说明
appKeyNSString是企业的 AppKey
appNameNSString是App名称,即七鱼管理后台添加App时填写的App名称
pkCerNameNSString否PushKit推送证书名,暂不支持,无需填写
isFusionBOOL否是否为融合SDK,默认值:NO
templateIdlong否后台样式模板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];...}
  1. AppKey 可在 管理端-应用-在线系统-设置-在线接入-APP-2.App Key 找到,请确保填写完整及正确,无空格,否则可能导致功能异常。
  2. AppName 对应管理端添加 App 时填写的 App名称。如需使用访客分流等功能,请及时在管理端添加 App,并填写正确的 bundleID 用于区分不同 App;如需使用推送功能,请选择相应环境上传对应推送证书,请自行确保证书有效性。
  3. 一般在application: didFinishLaunchingWithOptions:方法中调用初始化方法,如需在其他地方调用,请确保时机在启动客服功能前,且应预留一段初始化时间;尽量保证在整个软件运行期间仅调用一次。

集成聊天组件

通过 QYSDK.sessionViewController 可获取 QYSessionViewController 聊天界面控制器实例:

[[QYSDK sharedSDK] sessionViewController];
  1. 获取界面实例后,必须嵌入至导航栏控制器UINavigationController中,便可获得完整聊天窗口及所有功能。
  2. QYSessionViewController会使用到导航栏navigationItem的标题文字属性title、标题视图属性titleView、右侧按钮属性rightBarButtonItems,若使用自定义导航栏,请确保以上属性能正常设置,否则会影响部分功能。
  3. 每次调用[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资源包。

  1. 集成 QYVideoService.xcframework :将 QYVideoService.xcframework 文件夹拖入工程,确保文件 copy 至工程而非引用,并确保 General —> Frameworks, Libraries, and Embedded Content ( >=Xcode11 ) 选项中包含导入的库,同时 Embed 选择 Embed & Sign 即可。
  2. 集成 QYSDK.framework :将 Resources 文件夹中所需的 QYVideoResource.bundle 资源文件拖入主工程,确保 mainBundle 可以访问到。

自动集成

  1. 将 Podfile 文件中的pod 'QY_iOS_SDK', '~> x.x.x'修改为:
pod 'QY_iOS_SDK/Video', '~> x.x.x'
  • "x.x.x" 代表版本号
  1. 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 打开,可通过截获链接点击事件使用自定义网页视图。

构建配置与常见问题

本节说明编译、构建、混淆、架构兼容等工程配置问题及常见处理方式。

模拟器架构问题

由于库包含模拟器版本,会导致打包失败,故需要在打包前将模拟器版本剥去,具体方法如下:

  1. 创建 strip_archs.sh 脚本,并放在工程目录中,如 Resources 文件夹里;
  2. 在 Build Phases 设置项中点击左上角 + 号,选择 New Run Script Phase,工程在编译过程中会自动 run script;
  3. 在 script 中添加代码,执行 strip_archs.sh 脚本:
/bin/sh "${SRCROOT}/QYSDKDemo/Resources/strip_archs.sh"
  1. 将如下内容复制至脚本中:
#!/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,可以按如下步骤设置:

  1. 手动或pod集成海外版本
#海外版
pod 'QY_iOS_SDK/Abroad','10.16.0'
  1. 在SDK初始化之前,增加下面的配置
//海外版AppKey,则isMix = NO;国内版AppKey,则isMix = YES;
[QYServerConfig sharedInstance].isMix = YES;

AppKey和isMix参数,可以通过服务端动态控制,海外版对应isMix = NO,国内版对应isMix = YES。

注意:只有同时使用国内AppKey和海外AppKey的场景需要设置isMix = YES,其他情况都应该设置isMix = NO或者不设置。

日志与排障

本节说明日志开关、日志读取和常见排障入口,便于定位接入和运行问题。

读取日志

为方便追踪问题,七鱼 iOS SDK 会记录一些关键信息日志在本地文件,可通过调用QYSDK.h的如下接口获取日志文件路径:

/**
 *  获取七鱼日志文件路径
 *
 *  @return 日志文件路径
 */
- (NSString *)qiyuLogPath; 

其他说明

本节收纳不属于单一功能模块但会影响接入体验的补充说明。

类库说明

SDK 主要提供以下类/协议/方法:

类/协议描述说明
QYHeaders头文件集合集合了非平台企业客服功能头文件
QYSDKSDK 主入口提供初始化/注册/注销/界面及配置对象获取等方法
QYSessionViewController聊天界面控制器聊天主界面,同时提供各类参数设置及部分功能接口
QYCustomUIConfigUI 配置类样式相关设置
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 一个架构的大小。

常见问题

本节汇总开发者接入和使用过程中常见问题,并给出对应处理建议。

这篇文档有帮助吗?

目录