CRM 对接概述
CRM 对接方式、错误码和用户认证机制。
概述
网易七鱼系统可以与企业 CRM 系统进行对接。
对接分轻量对接与接口对接两种方式。
- 轻量对接是指通过 Web / iOS / Android SDK 发起会话时,将访客的信息作为参数传递给网易七鱼系统。
- 接口对接是指企业提供一系列 HTTP/HTTPS 接口,由网易七鱼系统调用,获取访客的相关信息,并可以实现数据同步、访客身份验证等高级功能。
轻量对接的数据由企业产品客户端(或网站)将数据提交给网易七鱼系统,数据将展现在客服工作界面的当前会话和历史会话的“用户资料”标签下。接口对接的数据由企业接口提供,由网易七鱼系统客服端调用,数据将展现在客服工作界面的当前会话和历史会话的“更多信息”标签下。
轻量对接和接口对接的具体说明,请分别阅读轻量CRM对接和CRM接口对接章节。两种对接方式的对比,请阅读对接方式对比与建议章节。
文档约定
访客:指使用企业产品的用户,例如使用企业 App 产品的用户,或访问企业网站或 Web 产品的用户。
企业接口:指接口对接方式下,由企业开发并提供给网易七鱼系统的 HTTP/HTTPS 接口。
客服工作台、客服工作界面:都是指网易七鱼系统提供给客服使用的工作环境,即客服登录网易七鱼系统后使用的 Web 界面。
Web SDK:指网易七鱼系统提供的 Web 端开发工具包,供企业将网易七鱼功能嵌入到官网或 Web 产品中。主要包含一个在线获取的 JS 文件。
iOS SDK:指网易七鱼系统提供的 iOS 平台开发工具包,供企业将网易七鱼功能嵌入到 iOS 产品中。主要包含一个 .a 静态库,和一系列依赖的头文件、资源文件。
Android SDK:指网易七鱼系统提供的 Android 平台开发工具包,供企业将网易七鱼功能嵌入到 Android 产品中。主要包含多个 .jar 包,和一系列依赖的资源文件。
JSON:企业 CRM 系统与网易七鱼系统对接,数据传输时使用 JSON 格式。多数情况下数据都保存在一个数组中,数组中一个元素表示一个数据项。数据项包含的字段,有些是必选的,有些是可选的,请仔细阅读每个接口的数据定义。参考:JSON介绍 (opens new window)、JSON在线校验工具 (opens new window)。
对接方式对比与建议
轻量对接与接口对接的比较。场景、开发难度、数据隔离。
建议不同的企业、团队,用不同的对接方式。
轻量对接方式与接口对接方式,都是为了给客服在服务过程中提供丰富的访客信息,从而提高服务质量与工作效率。然而两种对接方式在使用场景与实现方式方面各有不同,以下对两种对接方式进行对比。
| 对比角度 | 轻量对接 | 接口对接 |
|---|---|---|
| 数据来源 | 发起会话时,客户端通过 SDK 提交。 | 企业提供的 HTTP 接口。 |
| 调用方式 | 客户端通过 SDK 将数据提交给网易七鱼系统服务器,客服工作台向网易七鱼服务器发起请求。 | 客服工作台直接向企业提供的 HTTP 接口发起请求。 |
| 数据存储 | 访客数据加密后保存在网易七鱼系统。 | 客服工作台前端直接发起请求,数据不经网易七鱼服务器,完全隔离。 |
| 功能 | 展现自定义访客信息:√ 展现订单类数据:× 数据与企业 CRM 同步:× 访客信息验证:× | 展现自定义访客信息:√ 展现订单类数据:√ 数据与企业 CRM 同步:√ 访客信息验证:√ |
| 展现位置 | 当前会话和历史会话的“用户资料”标签下 。 | 当前会话和历史会话的“更多信息”标签下。 |
| 开发难度 | 低。 只要客户端有访客的相关数据,就可以按约定拼出 JSON 提交。 | 中。 需要开发一套 HTTP 接口,与企业 CRM 数据库对接。若已有类似接口,则非常容易进行对接。 |
| 开发成本 | 低。 可快速实现。 无特别要求。 | 中。 需要一定的人力进行开发。 需支持跨域。 |
| 适用场景 | 产品规模较小; 产品发展初期; 团队规模较小; 技术人力紧张; 企业 CRM 尚不完善; 访客数据要求一般; 不需要订单、交易类信息。 | 产品规模中大; 产品发展成熟期; 团队规模中大; 技术人力有一定支持; 企业 CRM 较完善; 访客数据要求高; 需要订单、交易类信息。 |
Appendix I 错误码
所有对接接口rlt错误码保留值定义如下:
- 0: 接口返回正确;
- 1: 用appid和appsecret作为认证方式时,表示认证不通过;
- 2: 用appid和token作为认证方式时,表示 token 过期;
其他情况,可根据企业业务逻辑自行设定错误码,仅供显示用。
有关认证方式的说明,请参考接口认证方式章节。
所有错误码,包括保留的错误码,均可使用整形或字符串。即:
{
"rlt": 0
}{
"rlt": "0"
}两种表示方法是等价的。
当接口返回的rlt字段值不为0时,可以在返回的内容中设置一个msg字段,提供用于显示的错误信息。
七鱼用户认证机制
概述
第三方接入七鱼后,可以上报uid,用以访问或关联用户在第三方的真实业务数据。本文描述了七鱼对uid进行身份认证的方案。适用于对uid真实性要求较高的场景。
术语
- 第三方:接入七鱼的企业
- uid:第三方的用户唯一标识
认证过程
- 第三方提供一个生成随机授权码authToken的授权接口,authToken生成后需要暂存在第三方服务器端,供之后的uid校验使用;
- 申请客服或上报CRM信息请求时,先调用上面接口,获取随机授权码authToken,并将其传递给七鱼;
- 七鱼前端将获取到的authToken和uid作为参数传递到七鱼服务器端;
- 七鱼服务器收到请求后,携带authToken和uid,调用第三方认证接口进行校验;
- 第三方将收到的authToken与本地暂存的authToken进行比较,看是否一致,并返回校验结果;
- 如果authToken和uid校验失败,七鱼服务器会忽略请求,并返回失败信息到前端页面。
实施流程
- 第三方知会七鱼需开启用户认证,并协调约定开启时间;
- 第三方在约定的开启之前准备好认证接口,将线上接口地址提交给七鱼,并与七鱼做好联调工作;
- 第三方使用支持的SDK,并按下文中代码示例完成authToken的设置工作。
认证模式说明
认证模式需要联系技术支持进行修改,目前支持如下几种认证模式:
- 模式0:不做校验,直接使用上传的foreignId,允许foreignId为空
- 模式1:如果有authToken和foreignId才校验authToken是否有效,如果authToken校验失败则不允许申请会话
- 模式2:如果有foreignId,则必须同时有authToken,并且校验authToken是否有效,如果authToken校验失败则不允许申请会话
- 模式3:必须有foreignId,如果有authToken才校验authToken是否有效,如果authToken校验失败则不允许申请会话
- 模式4:必须有foreignId和authToken,并且校验authToken是否有效,如果authToken校验失败则不允许申请会话
- 模式5:没有foreignId和authToken,也去三方校验,如果校验失败则不允许申请会话
授权接口
生成随机授权码authToken的接口。该接口由第三方自己调用。
如果该接口由第三方自己调用,需要第三方自己保证生成的authToken在使用时不会过期,如定期将新生成的authToken通过七鱼SDK接口函数传递给七鱼。七鱼不关心该接口的定义规则。
如果该接口由七鱼调用,则第三方不需要关心authToken的过期问题,但接口必须遵循以下定义规范:
调用说明
- 接口由第三方提供
- 调用方式为HTTP GET请求;
- 接口认证方式与第三方平台Session认证一致
- 接口返回类型为JSON,同时进行UTF-8编码。
响应
{"code":200,"token":false}响应字段
| 字段 | 含义 |
|---|---|
| code | 响应码,200表示生成authToken成功 |
| token | 新生成的authToken值 |
认证接口
七鱼服务端收到相关请求后,会携带认证信息至第三方认证接口完成认证工作。
接口说明
- 接口由第三方提供
- 调用方式为HTTP POST请求;
- 请求Content-Type类型为:application/json;charset=utf-8;
- 接口返回类型为JSON,同时进行UTF-8编码。
接口调用鉴权
第三方采用计算checksum方式对调用方进行鉴权校验,参数包括两部分,header参数和body参数
Header参数
需要放在Http Request Header中
| 参数名 | 参数说明 |
|---|---|
| checksum | 请求参数根据checksum算法计算出来的值 |
| time | 当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的毫秒数(String) |
Body参数
需要以字节流方式接收,内容为Json字符串
| 参数名 | 含义 |
|---|---|
| uid | 用户身份信息 |
| token | 认证用authToken |
Body参数示例
{"uid":"uid-from-user-server","token":"auth-token-from-user-server"}计算checksum的java代码举例如下
public class QiyuAuthCheckSum {
private static final char[] HEX_DIGITS = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};
public static String encode(String appSecret, String nonce, String time) {
String content = appSecret + nonce + time;
try {
MessageDigest messageDigest = MessageDigest.getInstance("sha1");
messageDigest.update(content.getBytes());
return getFormattedText(messageDigest.digest());
} catch (Exception e) {
throw new RuntimeException(e);
}
}
private static String getFormattedText(byte[] bytes) {
int len = bytes.length;
StringBuilder buf = new StringBuilder(len * 2);
for (int j = 0; j < len; j++) {
buf.append(HEX_DIGITS[(bytes[j] >> 4) & 0x0f]);
buf.append(HEX_DIGITS[bytes[j] & 0x0f]);
}
return buf.toString();
}
}encode函数参数来源说明
| 参数名 | 含义 |
|---|---|
| appSecret | 登录第三方在七鱼平台账号的管理员端,在设置-基础设置-App接入页面可以查看到 |
| nonce | 将body参数对应的Json字符串参数进行md5加密后得到的值全部转小写后的值 |
| time | 取自header参数中的time参数值 |
接口响应参数示例
{"code":200,"result":true}响应字段
| 字段 | 含义 |
|---|---|
| code | 响应码 |
| result | 认证结果 |
响应码值说明
- 200,表示接口校验成功,result返回true
- 300,表示checksum计算错误,result返回false
- 400,表示token值校验失败,result返回false
后续可按需扩展。
版本支持
支持用户认证的SDK版本如下:
| 平台 | 版本 |
|---|---|
| Web-SDK | >=3.5.0 |
| iOS-SDK | >=3.5.0 |
| Android-SDK | >=3.5.0 |
示例代码
Web
WEB-SDK提供如下两种方式设置及更新Token参数:
- ysf('config') 设置 authToken 属性
- 调用 pollAuthToken 或 setAuthToken 设置 authToken 值
pollAuthToken(url, options)
接口描述
此接口使用http/https请求主动拉第三方接口更新token, 由于网络原因等异常情况会导致http请求, 一旦请求失败会执行重试机制,保证token的更新, 用户可以自定义重试次数(默认为4次)。
- 第三方自定义获取token的api的接口
- 更新防止 token 失效
请求说明
GET [http://domain/api/getAuthToken](http://domain/api/getAuthToken) // 获取token的第三方的Api接口
Content-Type : application/x-www-form-urlencoded;charset=utf-8参数说明
| interval | Number | 是 | 轮询时间间隔 |
|---|---|---|---|
| retryTime | Number | 否 | 重试次数,默认为4次 |
| data | Object | 否 | 请求参数 |
| method | String | 否 | GET |
| onsuccess | Function | 否 | 成功回调 code==200才进入此回调 |
| onerror | Function | 否 | 失败回调 |
| interval | Number | 是 | 轮询时间间隔 |
var url = 'http://domain/api/getAuthToken' // 获取token的第三方的Api接口
var options = {
interval : 300000, // 每隔多少毫秒去更新Token
data : {}, // 请求参数
retryTime : 4, // 失败重试次数
method : 'GET', // 默认 GET 请求
onsuccess : function(result){
// 可选回调, 第三方业务逻辑
},
onerror : function(json){
// 可选回调, 第三方业务逻辑
}
}
ysf('pollAuthToken', url, options);响应说明
Content-Type : application/json;charset=utf-8参数说明
| code | Number | 状态码 |
|---|---|---|
| message | String | 返回消息说明 |
| result | Object | {authToken : ''} authToken必填 |
| code | Number | 状态码 |
setAuthToken(token)
接口说明
第三方主动调用此setAuthToken接口更新用户鉴权的 token
iOS
设置 authToken
[[QYSDK sharedSDK] setAuthToken:@"auth-token-from-user-server"];设置轻量 CRM
/**
* 完成回调
*/
typedef void(^QYCompletionWithResultBlock)(BOOL isSuccess);
/**
* 设置个人信息,带authToken校验。用户帐号登录成功之后,调用此函数
*
* @param userInfo 个人信息
* @param block authToken校验结果的回调
*/
- (void)setUserInfo:(QYUserInfo *)userInfo
authTokenVerificationResultBlock:(QYCompletionWithResultBlock)block;Android
// 关联用户信息代码中增加以下字段:
YSFUserInfo userInfo = new YSFUserInfo();
userInfo.userId = "userId";
userInfo.authToken = "auth-token-from-user-server";
if (!Unicorn.setUserInfo(account, new RequestCallback<Void>() {
@Override
public void onSuccess(Void param) {
ToastUtils.show("已切换为" + userInfo.userId, Toast.LENGTH_SHORT).show();
}
@Override
public void onFailed(int code) {
if (code == 414) {
ToastUtils.show("鉴权失败");
} else {
ToastUtils.show("设置用户资料失败,请重试");
}
}
@Override
public void onException(Throwable exception) {}
})) {
ToastUtils.show("用户资料格式不对", Toast.LENGTH_SHORT).show();
}注意事项
- authToken需在申请客服动作发生时保证可用性;
- 认证过程中authToken的产生比较关键,为保证安全性,需要在访客成功登录第三方平台后才能请求授权接口获取authToken。
这篇文档有帮助吗?