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

Save this PDF as:
 WORD  PNG  TXT  JPG

Size: px
Start display at page:

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

Transcription

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

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

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

4 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 应用结构 深圳市智客网络科技有限公司 1

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

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

7 址, 同时也支持第三方推送平台, 需要按照本文档规定填写您的 device_token 和绑定的用户 ID 4. 下载 SDK 您可以到 V5KF 官网下载智能客服 SDK, 包含了开发包和带 UI 界面的 Demo 示例工程 5. 环境要求在您集成智能客服 SDK 前环境要求如下 : 支持的最低版本 ios 7.0 支持 ARC 的 Xcode 编译器, 建议使用最新版本 SDK 导入 SDK 文件夹导入 把 V5Client 文件夹拷贝到新创建的工程路径下面, 然后在工程目录结构中, 右键选择 Add Files to 工程名 或者将这个文件夹拖入 XCode 工程目录结构中 引入依赖库 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/> 深圳市智客网络科技有限公司 4

8 <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> 关于这一特性的详细说明和解决方案可参考 : 关于离线消息推送 客户离线后消息将通过 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. 深圳市智客网络科技有限公司 5

9 // 初始化 SDK [V5ClientAgent 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 // 识别用户的标识 // 用户信息单次设置即生效, 更新用户信息或者切换用户时需调用 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 客服 "; // 设置返回按钮标题, 默认为前一页面标题 //UIBarButtonItem mybackitem = [[UIBarButtonItem alloc] init]; 深圳市智客网络科技有限公司 6

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

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

12 - (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 = 商品名称 牛仔裤 商品价格 "}; userviewsomething = NO; // 标识置为 NO, 单条消息有效 } return message; } 深圳市智客网络科技有限公司 9

13 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 实现消息接收和发送结果的回调等方法, 具体说明如下 V5MessageDelegate <NSObject> message 消息对象, 元素为 V5Message 类型 - (void)receivev5message:(v5message )message; 收到即时消息 --JSON 字符串 ( 接口扩展预留 json JSON 字符串消息, 元素为 NSString 类型 深圳市智客网络科技有限公司 10

14 - (void)receivejsonstring:(nsstring 连接建立成功 ( 其他消息接口需要在连接成功后方可调用 ) - (void)onconnect; status description 异常描述 - (void)receiveexceptionstatus:(kv5exceptionstatus)status desc:(nsstring )description; message 发送后的消息 ( 包含该消息当前发送状态 expcetion 失败原因 ( 如果为 0, 则代表发送成功 ) - (void)sendmessageresult:(v5message)message expcetion:(kv5exceptionstatus)expcetion; messages 消息数组, 元素为 V5Message offset size finish expcetion 异常类型 - (void)getmessagesresult:(nsarray<v5message > )messages offset:(nsinteger)offset size:(nsinteger)size finish:(bool)finish 消息接口调用 所有消息接口均在 V5ClientAgent.h 中有说明, 部分接口可参考下面的示例进行调用 深圳市智客网络科技有限公司 11

15 通用的发送消息接口 : // 通过 V5MessageManager 构造消息对象 V5Message textmessage = [V5MessageManager " 消息内容 "]; // 通过 sendmessage 方法发送消息对象 [[V5ClientAgent shareclient] sendmessage:textmessage]; 此外, 也可通过下面简便方式发送文本和图片消息 : content 文本消息 - (V5TextMessage )sendtextmessagewithcontent:(nsstring )content; 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]; 深圳市智客网络科技有限公司 12

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

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