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

Size: px

Start display at page:

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

盎璃幸
5 years ago
Views:

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 obtaintextmessagewithcontent:@ " 消息内容 "]; // 通过 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

V5 智能客服 Android 客户端 SDK 接口 (Ver0.7)

V5 智能客服 Android 客户端 SDK 接口 (Ver0.7) V5 智能客服 Android 客户端 SDK 接口目录 V5 智能客服 Android 客户端 SDK 接口... 1 1 术语... 1 2 功能说明... 1 3 业务流程... 1 3.1 业务结构... 1 3.2 交互流程... 2 3.3 SDK 工作流程... 3 4 前期准备... 3 4.1 开发环境准备...