全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网

访客名片接入规范

更新时间:2017-11-13 17:52:15

概述

本规范旨在指导技术开发人员,针对云客服租户的个性化客户信息如何接入到平台中的说明。

名词解释

名称 说明
访客名片 云客服中的热线在线工作台中,用于展示弹屏客户信息的区域;默认提供的是平台自带的CRM访客名片,同时也支持嵌入各租户的个性化信息
接入组件 租户通过提供嵌入页面或接口请求,直接将页面或请求返回数据展示在云客服平台的访客名片中
聊天窗 在线服务的入口,客户发送信息、查收坐席回复信息的页面
AES对称性加密 采用AES128位密钥进行对称性加密算法,在云客服对接用户访客名片时,作为加密查询用户参数的加密方式。采用对称性加密的原因为RSA加密算法加密信息长度有限,最长不可超过111字节,由于查询用户信息参数过长,故采用AES对称性加密算法。
RSA非对称性加密 采用RSA2048非对称性加密算法,云客服保存私钥(采用国家信息安全局认可密码机进行密钥保管),用户系统保存公钥,在每次信息传递时,采用RSA算法对随机生成的AES非对称性加密算法的密钥进行加密。

接入模式

目前云客服平台支持三种接入模式:a、页面嵌入:提供页面URL通过iframe嵌入到云客服平台中的指定区域;b、接口调用:提供数据接口,将返回的数据展示在云客服平台中的指定区域;c、环境信息:只针对在线渠道提供环境信息的接入,通过URL将参数列表中所需的环境信息传入,云客服平台解析后展示; 页面嵌入和接口调用,云客服平台会保存返回的userId,用于获取该客户的历史服务情况;环境信息,云客服平台不会保存客户userId,客户信息使用的是平台自带的客户信息模块。 image002.png 其中,6、7需要接入方根据规范完成,其余由云客服平台完成; image 其中,1、2、6、7需要接入方根据规范完成,其余由云客服平台完成;与热线工作台访客名片接入相比,在线工作台多了一个环境信息展示的逻辑。若实际接入场景中不需要展示环境信息,则环境信息相关参数可以不传递。

埋点数据获取

热线埋点数据获取

目前热线传入参数为来电号码,接入方无需处理。

在线埋点数据获取

在线渠道的参数传入,通过聊天窗来承载。各租户的业务应用层,通过使用云客服平台聊天窗提供的URL,将在线服务入口埋入业务所需页面,识别所需参数也通过在该URL后带入加密参数进行数据的传递。

在线埋点数据参数列表

参数编码 参数名称 参数说明
extInfo 业务扩展信息 业务个性化信息,由埋点接入端写入,例如:”extInfo”:{“key1”:”val1”,” “key2”:”val2” },其中”key1”、” key2”均由接入方自己指定,云客服平台不关心其中的内容,只会透传给接入方系统
userId 用户id 如果接入方设置了该参数,在线服务即可通过该参数识别出访客的身份,展示其历史来访记录,并可支持优先给其分配上次服务过该userId的客服(需额外配置一下会话连接策略)
uname 用户名称 用于在在线工作台的环境信息中展示,可不传;不传则不展示
browser 浏览器 用于在在线工作台的环境信息中展示,可不传;不传则不展示
network 网络 用于在在线工作台的环境信息中展示,可不传;不传则不展示
appVersion 应用端版本 用于在在线工作台的环境信息中展示,可不传;不传则不展示
os 操作系统 用于在在线工作台的环境信息中展示,可不传;不传则不展示
device 设备 用于在在线工作台的环境信息中展示,可不传;不传则不展示
resolution 分辨率 用于在在线工作台的环境信息中展示,可不传;不传则不展示
timestamp 时间戳 当前时间的UNIX时间戳,增加该字段可以控制埋点链接的有效时间,提升安全性。在线工作台配置管理中可增加一个配置编码为ENTRY_URL_EXPIRE_TIME的配置项(单位:秒),当云客服系统接收到请求的时间减去该字段的值得到的时间跨度超过了配置的有效时间,则认为该加密链接已失效,云客服系统将拒绝此次访问。

加密说明

埋点封装的请求有如下两个参数:

  • cinfo:加密后的JSON串
  • key: RSA私钥加密后的AES密钥

步骤:调用jar包中的CustomerInfoCryptoUtil.encryptByPublicKey(String text, PublicKey publicKey)进行加密:

  1. text:待加密文本
  2. publicKey:还原好的公钥对象
  3. 返回Map<String, String>:
  4. map.get("text") 获得加密后的文本
  5. map.get("key") 获得对应RSA加密后的AES密钥

代码示例

  1. public class Test {
  2. //注意:该公钥仅供demo示范使用,用户公钥请联系开发同学获取。
  3. private static String pub_key = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp5khaVZIP+x+n+ari3c1dcYRuNG7BUL0VVt1X2+KDcOpTHtfdHUQIzrHdbikZSyaCKyHLbAuLsU24gulCKmMGtjFGS6OiavUFFikVnVnOyEzcnhSPBiJNdlUo5TNYOVN1SUCutJUxvibQ1za6IcnHf4okgPTgcrXVHyG5ntCbE9ippKLe7q0z0TUIkRxesbKZiQPBDOgBukJUiFMk95zqCdESCe6kCSp2GdIojyVAelU11JIcAm/4OjCCFMz6Jcnse7rdScxRsoMHU89tDmXG9mo3PhUXyfQJzyESlotKek99eHPkSr7EW/SBj3xMc+ysrBZd+4tFOZJIRIlFf/eSQIDAQAB";
  4. //还原出RSA公钥对象
  5. private static PublicKey getPubKey() throws Exception {
  6. X509EncodedKeySpec keySpec = new X509EncodedKeySpec(Base64Util.decode(pub_key));
  7. KeyFactory keyFactory;
  8. keyFactory = KeyFactory.getInstance("RSA");
  9. PublicKey key = keyFactory.generatePublic(keySpec);
  10. return key;
  11. }
  12. public static void main(String[] args) throws Exception {
  13. JSONObject json = new JSONObject();
  14. json.put("asid", "123456");
  15. json.put("disconSymbol", "CUSTOMER");
  16. json.put("tel", "13675840350");
  17. json.put("tntInstId", "ZPLKH1CN");
  18. json.put("isHold", "1");
  19. PublicKey publicKey = getPubKey();
  20. Map<String, String> map = CustomerInfoCryptoUtil.encryptByPublicKey(json.toString(), publicKey);
  21. String uri = "?key=" + map.get("key") + "&cinfo=" + map.get("text");
  22. }
  23. }

数据格式示例

  1. {
  2. "extInfo": {" uid " : "11111"," customerInfo ": "11111" },
  3. "userId":"12345",
  4. "uname":"张三",
  5. "browser":"chrome",
  6. "network":"4G",
  7. "appVersion":"1.0.0",
  8. "os":"iOS",
  9. "device":"iphone6 plus",
  10. "resolution":"1920*1280",
  11. "timestamp":当前时间的UNIX时间戳
  12. }

做为环境信息展示样例如下,页面嵌入或接口调用根据具体业务属性字段展示:

image

数据加密传递

将上述数据结构加密后拼接到对应访客聊天窗url中:https://cschat-ccs.aliyun.com/pcportal.htm?tntInstId=********&scene=********&cinfo=【密文】&key=【RSA加密后的AES密钥】

访客名片接入

云客服配置

在云客服平台组件配置页面,配置访客名片对应的URL,接入方式有两种,页面嵌入和接口调用。

image

访客名片参数列表

参数编码 参数名称 参数说明
extInfo 业务扩展信息 业务个性化信息,由埋点接入端写入,云客服平台透传给第三方接入组件示例:”extInfo”:{“uid”:”123245”,” customerInfo”:”5” },其中”uid”、”customerInfo”的key值,接入组件可自行定义
agentId 座席工号 客服座席的工号
sourceType 展示类型 online 在线、hotline热线 页面嵌入时需要根据此参数判断展示类型,在线为纵向展示,热线为横向展示
userId 用户id 首次调用,该字段为空 接口对接的模式中,若首次调用接口时未定位到访客信息,平台会默认提供该字段为查询条件,展示在页面中,并将坐席重新输入的信息做为查询条件再次传递给接入组件;在查看历史服务记录时,云客服平台会传递用户ID给第三方接入组件,展示页面或获取返回数据
cardId 卡号 接口对接的模式中,若首次调用接口时未定位到访客信息,平台会默认提供该字段为查询条件,展示在页面中,并将坐席重新输入的信息做为查询条件再次传递给接入组件;页面嵌入模式可不传递此字段
tel 电话号码 接口对接的模式中,若首次调用接口时未定位到访客信息,平台会默认提供该字段为查询条件,展示在页面中,并将坐席重新输入的信息做为查询条件再次传递给接入组件;页面嵌入模式中,做为客户电话号码传递(客户呼入为主叫号码,坐席呼出为被叫号码)
contactId 服务记录ID 供接入方处理个性化业务与服务记录之间的关联关系(手动创建的热线服务记录,无法将服务记录ID传递给访客名片接入组件) 例如:业务自有工单需要与云客服平台服务记录做关联的场景中
timestamp 时间戳 当前时间的UNIX时间戳

参数使用说明

上述参数列表中的参数,会按照下图的逻辑进行传递,需要接入组件根据如下规则进行解析。

image

SDK下载

fccsplatform-common-crypto-1.0.0.20161108.zip

解密说明

传递给接入组件请求的有如下两个参数:

  • params:加密后的请求JSON串
  • key: RSA私钥加密后的AES密钥

步骤:接入组件收到请求后具体解密步骤:1.从http请求中获取对应参数,分别是params,key2.将用户公钥还原成PublicKey类型3.调用CustomerInfoCryptoUtil.decryptByPublicKey(params, key, publicKey)方法进行解密。

代码示例

  1. public class Test {
  2. //注意:该公钥仅供demo示范使用,用户公钥请 提工单到云客服产品。
  3. private static String pub_key = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp5khaVZIP+x+n+ari3c1dcYRuNG7BUL0VVt1X2+KDcOpTHtfdHUQIzrHdbikZSyaCKyHLbAuLsU24gulCKmMGtjFGS6OiavUFFikVnVnOyEzcnhSPBiJNdlUo5TNYOVN1SUCutJUxvibQ1za6IcnHf4okgPTgcrXVHyG5ntCbE9ippKLe7q0z0TUIkRxesbKZiQPBDOgBukJUiFMk95zqCdESCe6kCSp2GdIojyVAelU11JIcAm/4OjCCFMz6Jcnse7rdScxRsoMHU89tDmXG9mo3PhUXyfQJzyESlotKek99eHPkSr7EW/SBj3xMc+ysrBZd+4tFOZJIRIlFf/eSQIDAQAB";
  4. //还原出RSA公钥对象
  5. private static PublicKey getPubKey() throws Exception {
  6. X509EncodedKeySpec keySpec = new X509EncodedKeySpec(Base64Util.decode(pub_key));
  7. KeyFactory keyFactory;
  8. keyFactory = KeyFactory.getInstance("RSA");
  9. PublicKey key = keyFactory.generatePublic(keySpec);
  10. return key;
  11. }
  12. public static void main(String[] args) throws Exception {
  13. String params = request.getParameter("params");
  14. String key = request.getParameter("key");
  15. PublicKey publicKey = getPubKey();
  16. String cinfo = CustomerInfoCryptoUtil.decryptByPublicKey(params, key, publicKey);
  17. JSONObject dataJsonObject = JSON.parseObject(cinfo);
  18. //加验时间戳
  19. Date requestDate = new Date(dataJsonObject.getLong("timestamp"));
  20. Date now = new Date();
  21. //...
  22. //TODO 业务处理
  23. }
  24. }

数据格式示例

  1. {
  2. "userId":"13" //客户ID
  3. extInfo”: {“key : value”,} //业务自定义参数
  4. sourceType”: "online" //展示类型
  5. "tel":"13888888888" //客户电话号码
  6. "cardId":"123123123" //客户证件号码
  7. ...
  8. "timestamp":"1421293902131" //时间戳
  9. }

接入模式:页面嵌入

页面展示

热线工作台在软电话与类目选择中间增加嵌入页面区域,展示嵌入页面;在线工作台在右下角展示嵌入页面。 由于两种布局和展示方式的不同,所以需要嵌入页面做展示样式上的区分,支持横向和纵向两种布局。 注:嵌入页面需要支持https认证安全 image image

数据加密传递

云客服平台将相关参数拼成get请求,传递给嵌入页面(提供的URL),并加密传递。示例:https://***(客户访客名片域名).com/iframe.htm? params =【密文】&key=【RSA加密后的AES密钥】&iframeKey=【区分服务记录TAB页面ID】

页面脚本

  1. <!-- 引用容器 js -->
  2. <script src="https://os.alipayobjects.com/rmsportal/TioCsVbJfsmWnVRFWifG.js"></script>

调用:

  1. <script>
  2. // 窗口加载完毕之后
  3. window.onload = function () {
  4. document.querySelector('#params').innerHTML = location.href;
  5. // 通用方法
  6. // 更改页面高度
  7. document.getElementById('updateHeight').onclick = function () {
  8. csbridge.updateHeight(
  9. document.getElementById('heightValue').value
  10. );
  11. }
  12. // 热线功能
  13. // 更改页面标题
  14. csbridge.modifyTabTitle('你好');
  15. document.getElementById('close').onclick = function () {
  16. // 关闭当前 Tab
  17. csbridge.closeCurrentTab();
  18. };
  19. document.getElementById('outcall').onclick = function () {
  20. // 外呼,参数为号码
  21. csbridge.outcall('13805782852');
  22. };
  23. document.getElementById('canclose').onclick = function () {
  24. // 设置当前 Tab 可否手动关闭
  25. csbridge.canClose(false);
  26. }
  27. document.getElementById('workRoundUp').onclick = function () {
  28. // 软电话结束善后
  29. csbridge.workRoundUp();
  30. }
  31. // 在线功能
  32. document.getElementById('userId').onclick = function () {
  33. csbridge.updateUserInfo({userId: '13516779247', userType: 'CC'})
  34. }
  35. };
  36. </script>

测试页面

可以在云客服配置这个页面 https://os.alipayobjects.com/rmsportal/qqkzrZwBzLSTQqIsJrTD.html 来测试。

接入模式:接口对接

  1. 1.接入方提供的web接口的服务端必须支持跨域,因为请求是从云客服网站发出的,如果web接口的服务端不支持跨域,会被浏览器拦截。跨域解决方案可自行搜索CORS获取;
  2. 2.接入方提供的web接口协议必须是https
  3. 3.接入方提供的web接口响应头中的Content-Type必须为application/json; charset=utf-8

页面展示

热线、在线工作台在接口对接的模式下,访客信息的展示都在有下角,与平台自带客户信息位置相同。imageimage

页面展示

云客服平台会将通过渠道获取的数据,封装到一个JSON串中,并加密传递。示例:https://***(客户接口地址).com/data.json? params =【密文】&key=【RSA加密后的AES密钥】

返回数据格式说明

json返回的数据中,userId为必填字段,云客服会以此数据作为客户的唯一标识,并保存在云客服平台中。该字段不用再schema中做字段信息的描述。示例:

  1. {
  2. "message": "查询成功",
  3. "success": true,
  4. "result": {
  5. "telePhone": "11111111111",
  6. "customerName": "招商银行苏州分行",
  7. "username": "test",
  8. "email": "wangqy1@hundsun.com",
  9. "userId": "0CE0540B-E351-4B83-B47F-72A2E8D2479E",
  10. "customerNo": "77777",
  11. "account": "77777",
  12. "mobile": "",
  13. "schema": {
  14. "properties": {
  15. "customerName": {
  16. "name": "客户名",
  17. "type": "text"
  18. },
  19. "account": {
  20. "name": "客户帐号",
  21. "type": "text"
  22. },
  23. "username": {
  24. "name": "联系人",
  25. "type": "text"
  26. },
  27. "telePhone": {
  28. "name": "电话",
  29. "type": "text"
  30. },
  31. "email": {
  32. "name": "邮箱",
  33. "type": "text"
  34. }
  35. }
  36. }
  37. }
  38. }

关键字段说明如下:success: 接口请求状态是否成功:成功true,失败false;message: 接口消息,自定义,会在云客服平台展示;result: 业务数据和格式,字段的展示顺序根据schema中的描述顺序进行展示;

本文导读目录