V5 智能客服 ios 客户端 SDK 接口 (Ver0.2)

V5 智能客服 ios 客户端 SDK 接口 (Ver0.2)

V5 智能客服 ios 客户端 SDK 接口 目录 V5 智能客服 ios 客户端 SDK 接口... 1 1 术语... 1 2 功能说明... 1 3 业务流程... 1 业务结构... 1 交互流程... 2 SDK 工作流程... 3 4 前期准备... 3 开发环境准备... 3 SDK 导入... 4 4.2.1 SDK 文件夹导入... 4 4.2.2 引入依赖库... 4 Info.plist 配置... 4 关于离线消息推送... 5 5 使用 SDK 提供的 UI 快速集成... 5 初始化 SDK... 5 用户信息和参数设置... 6 启动会话界面... 6 生命周期处理... 8 为消息添加自定义参数... 9 6 使用 SDK 接口开发... 10 初始化 SDK... 10 用户信息和参数设置... 10 开启消息服务... 10 消息代理... 10 消息接口调用... 11 生命周期处理... 12 查询会话消息... 12 7 其他事项... 13 深圳市智客网络科技有限公司 www.v5kf.com 1

V5 智能客服 ios 客户端 SDK 接口 版本更新... 13 异常及枚举说明... 13 深圳市智客网络科技有限公司 www.v5kf.com 2

1 术语 应用账号 :V5KF 网站后台 AppSDK 应用配置中的应用账号 站点编号 :V5KF 网站的账号对应的站点编号 ( 可以在 V5KF 官网后台查看或向客服获取 ) Demo 工程 : 使用智能客服系统 SDK 客户端开发的接口使用示例工程 会话界面 : 针对使用本 SDK 的 ios APP 而言, 表示进行对话的一个 UIViewController devicetoken: 推送平台用于标识设备的唯一 ID, 长度为 64 字节以内的字符串 用户 ID(uid): 标识 APP 所登录的用户的唯一 ID, 长度为 64 字节以内的字符串 坐席 : 使用 V5 智能客服系统的客服人员 2 功能说明 V5 智能客服系统客户端可集成到 web APP 等第三方平台提供客户在线咨询服务, 实时接收客户的反馈 支持发送文本 位置 图片以及表情等消息, 并可显示图文 打开链接 本文档介绍 V5 智能客服系统客户端 SDK 的 ios 版本的集成和使用 本 SDK 兼容 ios 7.0 以上, 并为开发者提供 Demo 工程, 可以参照 Demo, 使用 SDK 提供的 UI 快速集成到你的项目中 ; 对 UI 有较高定制需求的开发者可根据 SDK 接口进行开发, 自行开发界面 3 业务流程 业务结构 V5 客户端授权 认 证服务 V5 智能云服务 客户端 图 3-1 应用结构 深圳市智客网络科技有限公司 www.v5kf.com 1

V5 智能云服务 V5 智能云服务, 是连接座席和访客的桥梁 并通过云智能机器人, 提供替代 协助座席进行优质客服的服务 V5 客户端授权 认证服务分发访客接入 V5 智能云服务的凭据服务器 交互流程 客户端首先向 V5 客户端授权 认证服务发送认证信息 (HTTP POST 请求方式 ), 以获取连接 V5 智能云服务的授权信息 ; 用认证成功返回的授权信息向 V5 智能云服务建立会话连接 ; 开启会话, 进行即时消息对话 客户端 V5 网页客户 授权 认证服务 V5 智能云服务 客户认证 返回会话服务器授权信息 开始会话 会话消息 图 3-2 交互流程 深圳市智客网络科技有限公司 www.v5kf.com 2

SDK 工作流程 开始 初始化 SDK 设置用户信息, 连接认证 接收离线通知 点击通知 是否认证成功 Yes 开启消息服务 No 收发即时消息 用户退出 Yes 设置离线推送? No 结束 图 3-3 SDK 工作流程 4 前期准备 开发环境准备 1. V5KF 客服系统账号没有 V5KF 账号需要前往官网注册账号 2. 获得应用账号 站点编号应用账号 站点编号作为 SDK 连接服务端的身份凭证, 可到后台 App SDK 的应用配置界面获取 3. 填写对应平台的推送服务器地址为了使您的 APP 在集成本 SDK 后具有离线消息推送, 建议填写您的推送服务器地 深圳市智客网络科技有限公司 www.v5kf.com 3

址, 同时也支持第三方推送平台, 需要按照本文档规定填写您的 device_token 和绑定的用户 ID 4. 下载 SDK 您可以到 V5KF 官网下载智能客服 SDK, 包含了开发包和带 UI 界面的 Demo 示例工程 5. 环境要求在您集成智能客服 SDK 前环境要求如下 : 支持的最低版本 ios 7.0 支持 ARC 的 Xcode 编译器, 建议使用最新版本 SDK 导入 4.2.1 SDK 文件夹导入 把 V5Client 文件夹拷贝到新创建的工程路径下面, 然后在工程目录结构中, 右键选择 Add Files to 工程名 或者将这个文件夹拖入 XCode 工程目录结构中 4.2.2 引入依赖库 libsqlite3.tbd libicucore.tbd Fundation.framework AudioToolbox.framework Security.framewwork CFNetwork.framework Info.plist 配置 由于 ios 9 的新特性默认使用 ATS, 所有网络请求都需要在安全的连接下 ( 当前 App Store 尚未强制使用 ios 9 这一新特性 ), 所以一些不兼容的服务需要进行额外的配置, 本 SDK 使用到了腾讯地图和图片服务的 webservice 接口, 需在 Info.plist 添加下述配置 : <key>nsapptransportsecurity</key> <dict> <key>nsexceptiondomains</key> <dict> <key>image.myqcloud.com</key> <dict> <key>nsincludessubdomains</key> <true/> 深圳市智客网络科技有限公司 www.v5kf.com 4

<key>nsexceptionallowsinsecurehttploads</key> <true/> </dict> <key>v5kf.com</key> <dict> <key>nsincludessubdomains</key> <true/> <key>nsexceptionallowsinsecurehttploads</key> <true/> </dict> <key>api.map.qq.com</key> <dict> <key>nstemporaryexceptionrequiresforwardsecrecy</key> <false/> </dict> </dict> </dict> 或者简单粗暴点, 直接关闭 ATS, 允许任意站点的 HTTP 连接 : <key>nsapptransportsecurity</key> <dict> <key>nsallowsarbitraryloads</key> <true/> </dict> 关于这一特性的详细说明和解决方案可参考 : https://github.com/chenyilong/ios9adaptationtips 关于离线消息推送 客户离线后消息将通过 APNs 推送到客户端设备, 建议使用第三方推送平台, 需要在代码中填写您 ios 设备上获取的 devicetoken, 并在 V5 后台配置推送平台的信息, 否则离线后接收不到消息 ( 注 : 当前版本尚未验证 APNs 推送功能, 暂不可用, 后续添加 ) 5 使用 SDK 提供的 UI 快速集成 初始化 SDK 将 SDK 文件添加到工程后, 在 AppDelegate 中 import V5ClientAgent.h 文件, 然后在 application: willfinishlaunchingwithoptions: 函数中初始化 SDK 示例如下: - (BOOL)application:(UIApplication )application didfinishlaunchingwithoptions:(nsdictionary )launchoptions { // Override point for customization after application launch. 深圳市智客网络科技有限公司 www.v5kf.com 5

// 初始化 SDK [V5ClientAgent initwithsiteid:@"10000" account:@"v5kf" exceptiondelegate:nil]; } return YES; 其中 siteid 和 account 分别是从 V5 后台可以获取到的站点编号和应用账号 用户信息和参数设置 使用 SDK 提供的 UI 集成, 需要在启动会话界面之前进行用户信息和参数配置 配置项如下 : // 需要 #import "V5ClientAgent.h" // 获得 V5ClientAgent 配置项 V5Config config = [V5ClientAgent shareclient].config; // 设置用户信息 config.nickname = @" 张三 -ios"; config.gender = 1; // 性别 :0- 未知 1- 男 2- 女 //config.avatar = @" 头像 URL"; config.uid = @"uid-for-test-123456"; // 识别用户的标识 // 用户信息单次设置即生效, 更新用户信息或者切换用户时需调用 shouldupdateuserinfo //[config shouldupdateuserinfo]; 启动会话界面 通过简单地添加一个在线咨询按钮即可使用智能客服客户端功能, 在按钮点击事件处理中加入启动会话界面的代码 : V5ChatViewController chatviewcontroller = [V5ClientAgent createchatviewcontroller]; // 不显示底部栏 ( 有底部栏的需加此配置 ) chatviewcontroller.hidesbottombarwhenpushed = YES; //chatviewcontroller.delegate = self; // 页面的代理, 可实现更多自定义需求 //chatviewcontroller.devicetoken = @" 设备的 devicetoken"; // 也可在 config 设置 devicetoken // 允许并设置来消息铃声 SystemSoundID //chatviewcontroller.allowsound = YES; //chatviewcontroller.soundid = 1007; // 设置标题, 默认 V5 客服 //chatviewcontroller.title = @"V5 客服 "; // 设置返回按钮标题, 默认为前一页面标题 //UIBarButtonItem mybackitem = [[UIBarButtonItem alloc] init]; 深圳市智客网络科技有限公司 www.v5kf.com 6

//mybackitem.title = @" 返回 "; //self.navigationitem.backbarbuttonitem = mybackitem; // 启动会话界面, 使用导航模式推出视图 ( 上面为会话界面配置选项, 注释的配置非必须 ) [self.navigationcontroller pushviewcontroller:(uiviewcontroller )chatviewcontroller animated:yes]; 此外, 页面的代理包含的方法如下, 有相应需求的可使用, 非必须 : @protocol V5ChatViewDelegate <NSObject> @optional 即将打开会话视图 - (void)clientviewwillappear; 会话视图打开后 - (void)clientviewdidappear; 即将关闭会话视图 - (void)clientviewwilldisappear; 关闭会话视图后 - (void)clientviewdiddisappear; 用户点击链接, 包括普通 URL(HTML 超链接 ) 图文链接 电话号码 @param url 链接地址 - (void)userclicklink:(nsstring )url linktype:(kv5linktype)linktype; 用户点击位置消息 @param lat 纬度 @param lng 经度 - (void)userclicklocationwithlatitude:(double)lat longitude:(double)lng; 深圳市智客网络科技有限公司 www.v5kf.com 7

用户点击图片消息 @param image 图片 @param url 图片链接 - (void)userclickimagewithimage:(uiimage )image picurl:(nsstring )url; 用户在会话视图中收到消息 @param message 消息对象 - (void)clientdidreceivemessage:(v5message )message; 用户将要发送消息 @param message 将要发送的消息 ( 开发者可修改替换发送内容, 消息类型和方向不可修改 ) @return 修改处理过的消息 - (V5Message )userwillsendmessage:(v5message )message; @end 注 : 点击事件有默认执行动作, 代理设置后会把默认动作覆盖转而执行代理方法内的动作 生命周期处理 在建立连接后收到 onconnect 时需要发送上线消息 : [[V5ClientAgent shareclient] shouldclientonline]; 在用户离开会话界面后, 不需要使用客服对话时, 发送下线消息 : [[V5ClientAgent shareclient] shouldclientoffline]; 在使用 UI 集成的 SDK 中, 不用手动调用上述代码, 需要在 AppDelegate 中添加下面代码 : 深圳市智客网络科技有限公司 www.v5kf.com 8

- (void)applicationdidenterbackground:(uiapplication )application { // 退出到后台时, 告诉 SDK 用户离线 [[V5ClientAgent shareclient] onapplicationdidenterbackground]; } - (void)applicationwillenterforeground:(uiapplication )application { // 移到前台时时, 告诉 SDK 用户在线并连接 [[V5ClientAgent shareclient] onapplicationwillenterforeground]; } 此外, 不使用客服功能时建议关闭会话连接以节省资源, 建议在开启会话界面的前一个界面的 viewdidappear: 方法中调用关闭客服的方法 : - (void)viewdidappear:(bool)animated { // 前一 viewcontroller 中 // 不使用客服功能时退出消息客户端 [[V5ClientAgent shareclient] stopclient]; } 为消息添加自定义参数 用户即将发送的消息可以通过 V5ChatViewDelegate 协议中实现方法 - (V5Message )userwillsendmessage:(v5message )message 获取到即将发送的消息, 并为消息加上自定义参数, 例如 : - (V5Message )userwillsendmessage:(v5message )message { if (userviewsomething) { // 用户浏览某商品的标识 message.customcontent = @{@" 用户等级 ": @"VIP", @" 用户积分 ": @"300", @" 商品名称 ": @" 牛仔裤 ", @" 商品价格 ": @" 168.00"}; userviewsomething = NO; // 标识置为 NO, 单条消息有效 } return message; } 深圳市智客网络科技有限公司 www.v5kf.com 9

6 使用 SDK 接口开发 初始化 SDK SDK 初始化参考 5.1 用户信息和参数设置 参考 5.2 开启消息服务 开启消息服务一般在 UIViewController 页面打开时进行, 具体接口参考如下 : // 开启服务 [[V5ClientAgent shareclient] startclientwithdelegate:self]; 其中 UIViewController 需实现协议 V5MessageDelegate, 初始化内容包括 : 1. 设置消息回调监听器 ; 2. 向 V5 认证服务进行客户端认证, 根据初始化时的站点信息和客户端生成的客户 ID 向认证服务器认证 ( 这之前可进行客户端用户信息设置, 参见 5.2), 获取会话参数 ; 3. 认证成功并返回参数后建立会话连接, 消息服务开启完成 此外, 提供关闭消息服务方法 : [[V5ClientAgent shareclient] stopclient]; // 关闭客户服务 消息代理 消息代理的声明在 V5Delegate.h 中有说明, 会话界面的 UIViewController 需要实现协议 V5MessageDelegate 实现消息接收和发送结果的回调等方法, 具体说明如下 : @protocol V5MessageDelegate <NSObject> 收到即时消息 @param message 消息对象, 元素为 V5Message 类型 - (void)receivev5message:(v5message )message; 收到即时消息 --JSON 字符串 ( 接口扩展预留 ) @param json JSON 字符串消息, 元素为 NSString 类型 深圳市智客网络科技有限公司 www.v5kf.com 10

- (void)receivejsonstring:(nsstring )json; @optional 连接建立成功 ( 其他消息接口需要在连接成功后方可调用 ) - (void)onconnect; 收到异常信息 @param status 异常类型 @param description 异常描述 - (void)receiveexceptionstatus:(kv5exceptionstatus)status desc:(nsstring )description; 发送消息结果 @param message 发送后的消息 ( 包含该消息当前发送状态 ) @param expcetion 失败原因 ( 如果为 0, 则代表发送成功 ) - (void)sendmessageresult:(v5message)message expcetion:(kv5exceptionstatus)expcetion; 获取消息记录完成的回调 @param messages 消息数组, 元素为 V5Message 类型 @param offset 起始位置 @param size 返回消息最大数量 @param finish 是否获取完全部消息 @param expcetion 异常类型 - (void)getmessagesresult:(nsarray<v5message > )messages offset:(nsinteger)offset size:(nsinteger)size finish:(bool)finish expcetion:(kv5exceptionstatus)expcetion; @end 消息接口调用 所有消息接口均在 V5ClientAgent.h 中有说明, 部分接口可参考下面的示例进行调用 深圳市智客网络科技有限公司 www.v5kf.com 11

通用的发送消息接口 : // 通过 V5MessageManager 构造消息对象 V5Message textmessage = [V5MessageManager obtaintextmessagewithcontent:@ " 消息内容 "]; // 通过 sendmessage 方法发送消息对象 [[V5ClientAgent shareclient] sendmessage:textmessage]; 此外, 也可通过下面简便方式发送文本和图片消息 : 发送文本消息 @param content 文本消息 - (V5TextMessage )sendtextmessagewithcontent:(nsstring )content; 发送本地图片 @param image 图片 - (V5ImageMessage )sendimagemessagewithimage:(uiimage )image; 发送消息结果在 V5MessageDelegate 中的方法 sendmessageresult: expcetion: 回调 生命周期处理 参考 5.4 查询会话消息 // 查询会话消息 [[V5ClientAgent shareclient] getmessageswithoffset:0 messagesize:12]; 结果通过 V5MessageDelegate 中的方法 getmessagesresult: offset: size: finish: expcetion: 回调 此外, 提供清空消息缓存的接口 : // 清空消息缓存 [[V5ClientAgent shareclient] clearmessagescache]; 深圳市智客网络科技有限公司 www.v5kf.com 12

7 其他事项 版本更新 SDK 存在新版本时, 请尽量更新到最新版本 SDK, 注意查看文档末尾的更新记录, 以根 据更新内容完成相应修改 异常及枚举说明 文件 关于具体异常信息和枚举变量已在 V5KFDefination.h 中通过注释详细说明, 具体参考该 深圳市智客网络科技有限公司 www.v5kf.com 13

更新记录 2016/01/13 文档版本 Ver0.1,SDK 版本 v1.0.1( 内测初版 ) 1. 说明 : 客服客户端 SDK ios 内测初版 2. 修改 Info.plist 的配置增加一个 http 请求的地址配置 2016/01/18 文档版本 Ver0.2,SDK 版本 v1.0.2 1. 修改 5.4 生命周期处理增加关闭客服连接示例 2. 增加 增加网络连接状态监听, 自动重连 3. 增加 V5Message 增加字典类型属性 customcontent, 支持添加自定义参数到消息, 将透明传输到坐席端, 比如可在用户提问中加入用户刚刚正查看的商品信息, 消息自定义参数仅当次传输有效, 服务端不做保存 4. 删除 去掉用户自定义信息设置( 未生效 ), 替代方式为上面的消息携带自定义参数方式 深圳市智客网络科技有限公司 www.v5kf.com 14