在线访客名片文档

1. 在线服务访客名片接入流程

接入在线服务的租户通常会有这么一个需求，就是希望客服在工作台界面能够看到来咨询问题的访客的个人信息，以便提供更好的服务。出于为客户的数据安全考虑，云客服不会获取接入方的客户信息，这就需要接入方提供一个页面或接口（即“访客名片”）来供云客服系统实时展示，而这样的一个页面或接口需要查询参数，比如类似userId这样的能确定客户身份的信息。接入方如何将这些查询参数传递给云客服，以便云客服系统在调用接入方的“访客名片”时将查询参数透传给接入方系统，这就是本文档要解决的问题。

在线服务接入访客名片的工作有两个，分别为 : 

• 访客端聊天窗数据埋点。

• 客服端工作台访客信息展示。

访客名片详细工程（Java语言） JavaDemo（PhP语言）phpdemo（C#语言）C#Demo

上述demo可以直接本地执行Application.java中的main函数。

其他开发语言目前没有代码demo，请用户参考Java语言进行开发。

注意：该文档所需公钥，需要收集租户id（提供聊天窗url），和当前文档链接，提工单给我们的同学生成。

2. 访客端聊天窗数据埋点

埋点主要是构造带有用户信息的加密链接。

2.1 在线服务埋点链接

访问 https://robot-ccs.aliyun.com/scenemng.htm#/scenemng页面，选择要构造加密信息的聊天窗 URL，以移动端的链接为例，以下就是一个标准的云客服在线服务聊天窗 URL：https://cschat-ccs.aliyun.com/index.htm?tntInstId=_0GBRgxU&scene=SCE00000023。 如果以这个埋点链接直接连入在线客户，客服在工作台端看到的只能是匿名访客。我们需要对这个链接加些参数，才能让其变为一个带实名访客信息的聊天窗链接。

2.2 需要加哪些参数？

只需要加上两个 URL 参数，即可使一个匿名链接变为实名链接：

• cinfo：将要传给访客名片的查询参数被加密后的内容。

• key：非对称加密算法加密后的对称加密密钥。

最终的聊天窗 URL 需变成这样：https://cschat-ccs.aliyun.com/index.htm?tntInstId=_0GBRgxU&scene=SCE00000023&cinfo=xxxxx&key=yyyyy可以看到，这两个参数提到最多的词就是“加密”。处于安全考虑，这些必须以密文形式传递，否则将会给恶意攻击者可趁之机。接入方对加密技术不了解也没关系，后面会有示例代码。

2.3 cinfo里是什么内容？

cinfo 里明文的内容构造示例：

{
"extInfo":{" uid ":"11111"," customerInfo ":"11111"},
"userId":"12345",
"uname":"Tom",
"browser":"chrome",
"network":"4G",
"appVersion":"1.0.0",
"os":"iOS",
"device":"iphone6 plus",
"resolution":"1920*1280",
"timestamp"：当前时间的UNIX时间戳
}

最重要的 3 个字段：extInfo、userId、timestamp。请详细阅读下表中这 3 个字段的说明。

2.4 如何生成最终的cinfo和key？

接下来将明文进行加密，以得到最终要拼接到聊天窗 URL 中的 cinfo 和 key 参数。

代码示例

publicclassTest{
//注意：该公钥仅供demo示范使用，用户公钥请参考文档第四部分，收集信息，联系开发同学获取。
privatestaticString pub_key ="MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp5khaVZIP+x+n+ari3c1dcYRuNG7BUL0VVt1X2+KDcOpTHtfdHUQIzrHdbikZSyaCKyHLbAuLsU24gulCKmMGtjFGS6OiavUFFikVnVnOyEzcnhSPBiJNdlUo5TNYOVN1SUCutJUxvibQ1za6IcnHf4okgPTgcrXVHyG5ntCbE9ippKLe7q0z0TUIkRxesbKZiQPBDOgBukJUiFMk95zqCdESCe6kCSp2GdIojyVAelU11JIcAm/4OjCCFMz6Jcnse7rdScxRsoMHU89tDmXG9mo3PhUXyfQJzyESlotKek99eHPkSr7EW/SBj3xMc+ysrBZd+4tFOZJIRIlFf/eSQID****";
//还原出RSA公钥对象
privatestaticPublicKey getPubKey()throwsException{
        X509EncodedKeySpec keySpec =new X509EncodedKeySpec(Base64Util.decode(pub_key));
KeyFactory keyFactory;
        keyFactory =KeyFactory.getInstance("RSA");
PublicKey key = keyFactory.generatePublic(keySpec);
return key;
}

publicstaticvoid main(String[] args)throwsException{
JSONObject extInfo =newJSONObject();
        extInfo.put("userId","123456");
        extInfo.put("userName","Tom");
JSONObject cinfo =newJSONObject();
        cinfo.put("userId","123456");
        cinfo.put("extInfo", extInfo);
PublicKey publicKey = getPubKey();
Map<String,String> map =CustomerInfoCryptoUtil.encryptByPublicKey(cinfo.toString(), publicKey);
String uri ="&key="+ map.get("key")+"&cinfo="+ map.get("text");
}
}

目前加密方法只支持 Java 语言，加密所需的密钥请联系云客服的技术人员获取，加密所需的工具类 jar 包可以下载导入。

2.5 生成最终的带实名访客信息的聊天窗URL

通过上一步得到了加密后的cinfo和key，将这两个参数拼接到原聊天窗 URL 中，即可得到最终的 URL（如 2.2 描述）。可以在服务配置 > 热线高级配置 > 聊天窗埋点测试进行测试。

3. 客服端工作台访客信息展示

在工作台对访客信息展示一共有两种方案：

• 页面嵌入

• 外部接口调用

这两种方案不可以同时使用， 请选择一种。

3.1 页面嵌入方案

该方案需要租户自己提供一个访客名片的展示页面, 以iframe的形式嵌入到在线工作台右侧。工作流程如下：

1. 提供访客名片页面的URL。

2. 对该页面的URL中的params进行解密（params由云客服系统构造）。

3. 页面对params的内容进行展示。

4. 利用postMessage函数方法， 回传userId和userName。

3.1.1 提供访客名片URL

编写一个简单的页面用于展示客户信息。并把URL填写到服务配置 > 热线配置 > 热线高级配置的输入框中。

3.1.2 params进行解密

客服工作台在加载租户提供的URL的时候, 会在URL中拼接三个参数：params, key, iframeKey。

https://www.example.com/customerinfo.htm?params=***&key=***&iframeKey=***

解密params方法请参考本文：第四节解密。

解密后的结果是一个JSON数据, 该数据内容的参数含义如下：

3.1.3 页面对params的内容进行展示

拿到解密后的params内容后，在iframe页面上渲染其内容信息， 展示给客服。

3.1.4 利用postMessage函数方法回传userId和userName

请将下面代码放到页面中。

function sendMessage(type, data){
constparams={};
params.type = type;
params.data = data;
params.resource ='csbridge';
params.iframeKey ='1';// 从url参数获取，示例假设值为1
    window.parent.postMessage(JSON.stringify(params),'*');
}

然后在步骤 3.1.2 的params解密后， 调用：

sendMessage('updateUserInfo',{"userId":"TESTID123456789","userName":"Tom"});

3.1.5 更新嵌入的页面高度

本小节是为了样式调整, 不是必须的. 使用方法同上一节类似。

以上是接入访客名片的所有流程。

3.2 外部接口调用

使用这种方案的时候，不需要租户提供任何前端页面， 只需要提供一个接口，云客服会通过Post的方式调用这个接口来查询访客信息。 

客户需要做的流程为：

1. 提供客户查询接口URL。

2. 对该URL收到的POST请求中，取得params和key参数并解密。

3. 通过解密后的内容，查询该访客的详细信息返回。

3.2.1 提供客户查询接口URL

提供该URL，并配置到云客服工作台的组件配置>访客名片URL。用下面的方式选择外部请求。 

3.2.2 取得params和key参数并解密

云客服会对该接口发送POST请求（跨域）。其中两个参数params和key会拼接在上一步配置的URL后面。 例如：

https://www.example.com/customerinfo.json?params=***&key=***

在取得这两个参数后，需要进行解密。

解密params方法请参考本文： 第四节解密

解密之后的内容是一个JSON字符串, 各个字段意义如下（各个字段并不一定有，可以为空）：

3.2.3 通过解密后的内容查询用户信息并返回.

解密后的内容含有用户的关键信息，通过这个信息客户自行查询到相信信息， 并按照严格的格式返回。

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

样例：

{
"message":"查询成功",//成功的消息
"success":true,//表示查询成功
"result":{//下面是自定义用户信息内容. 
"telePhone":"13*******000",
"customerName":"某银行某分行",
"userName":"test",
"email":"w***@example.com",
"userId":"0CE0540B-E351-4B83-B47F-72A2E8D2479E",//这个必须有!
"customerNo":"77777",
"account":"77777",
"mobile":"",
"schema":{//会按照schema的结构来展示用户信息
"properties":{
"customerName":{
"name":"客户名",
"type":"text"
},
"account":{
"name":"客户账号",
"type":"text"
},
"userName":{
"name":"联系人",
"type":"text"
},
"telePhone":{
"name":"电话",
"type":"text"
},
"email":{
"name":"邮箱",
"type":"text"
}
}
}
}
}

4. 解密

4.1 解密步骤

1. 从HTTPS请求URL中获取对应参数，分别是params, key。

2. 将用户公钥还原成PublicKey类型。

3. 调用CustomerInfoCryptoUtil.decryptByPublicKey（params, key, publicKey）方法进行解密。

4.2 maven依赖

<repository>
<id>central</id>
<url>http://mvn.cloud.alipay.com/nexus/content/groups/public</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>

<dependency>
<groupId>com.alipay.fc.csplatform</groupId>
<artifactId>fccsplatform-common-crypto</artifactId>
<version>1.0.0.20161108</version>
</dependency>

4.3 Java-Demo

publicclassTest{
//注意：该公钥仅供demo示范使用，用户公钥请联系技术支持获取。
privatestaticString pub_key ="MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp5khaVZIP+x+n+ari3c1dcYRuNG7BUL0VVt1X2+KDcOpTHtfdHUQIzrHdbikZSyaCKyHLbAuLsU24gulCKmMGtjFGS6OiavUFFikVnVnOyEzcnhSPBiJNdlUo5TNYOVN1SUCutJUxvibQ1za6IcnHf4okgPTgcrXVHyG5ntCbE9ippKLe7q0z0TUIkRxesbKZiQPBDOgBukJUiFMk95zqCdESCe6kCSp2GdIojyVAelU11JIcAm/4OjCCFMz6Jcnse7rdScxRsoMHU89tDmXG9mo3PhUXyfQJzyESlotKek99eHPkSr7EW/SBj3xMc+ysrBZd+4tFOZJIRIlFf/eSQID****";
//还原出RSA公钥对象
privatestaticPublicKey getPubKey()throwsException{
        X509EncodedKeySpec keySpec =new X509EncodedKeySpec(Base64Util.decode(pub_key));
KeyFactory keyFactory;
        keyFactory =KeyFactory.getInstance("RSA");
PublicKey key = keyFactory.generatePublic(keySpec);
return key;
}
publicstaticvoid main(String[] args)throwsException{
Stringparams= request.getParameter("params");
String key = request.getParameter("key");
PublicKey publicKey = getPubKey();
String cinfo =CustomerInfoCryptoUtil.decryptByPublicKey(params, key, publicKey);
JSONObject dataJsonObject = JSON.parseObject(cinfo);
//加验时间戳
Date requestDate =newDate(dataJsonObject.getLong("timestamp"));
Date now =newDate();
//...
//TODO 业务处理
}
}

5 常见问题

data must start with zero

解决方式：使用URLEncode解密params参数和key参数。

CustomerInfoCryptoUtil.decryptByPublicKey(URLEncoder.encode(params,"UTF-8"),URLEncoder.encode(key,"UTF-8"), publicKey);