开发指南

# 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)。

# 轻量CRM对接

轻量 CRM 对接是指通过 Web / iOS / Android SDK 发起会话时，可以将访客的信息作为参数传递给网易七鱼系统。

# Web SDK 调用

调用ysf('config')时，将包含用户信息的 JSON 传递给网易七鱼系统。

ysf('config', {
    "uid":"zhangsan",
    "data":JSON.stringify([
        {"key":"real_name", "value":"土豪"},
        {"key":"mobile_phone", "hidden":true, "value":"13800000000"},
        {"key":"email", "value":"13800000000@163.com"},
        {"index":0, "key":"account", "label":"账号", "value":"zhangsan" , "href":"http://example.domain/user/zhangsan"},
        {"index":1, "key":"sex", "label":"性别", "value":"先生"},
        {"index":5, "key":"reg_date", "label":"注册日期", "value":"2015-11-16"},
        {"index":6, "key":"last_login", "label":"上次登录时间", "value":"2015-12-22 15:38:54"},
        {"index":7, "key": "tags", "label": "标签", "value": "企业,vip" },
        {"index":8, "key": "leaderId", "value": "1001"}
    ])
});

注意：data字段的内容需使用JSON.stringify()进行序列化。为保持良好的兼容性，若要支持较低版本的浏览器（如IE8及更低版本）则需引入第三方JSON库，如 JSON3 (opens new window)。

# iOS SDK 调用

创建一个QYUserInfo实例，将包含用户信息的 JSON 字符串填充到QYUserInfo.data。调用setUserInfo时将此QYUserInfo实例作为参数传递给网易七鱼 SDK。

QYUserInfo *userInfo = [[QYUserInfo alloc] init];
userInfo.userId = @"uid";
userInfo.data = @"[{\"key\":\"real_name\", \"value\":\"土豪\"},"
                  "{\"key\":\"mobile_phone\", \"hidden\":true, \"value\":\"13800000000\"},"
                  "{\"key\":\"email\", \"value\":\"13800000000@163.com\"},"
                  "{\"index\":0, \"key\":\"account\", \"label\":\"账号\", \"value\":\"zhangsan\", \"href\":\"http://example.domain/user/zhangsan\"},"
                  "{\"index\":1, \"key\":\"sex\", \"label\":\"性别\", \"value\":\"先生\"},"
                  "{\"index\":5, \"key\":\"reg_date\", \"label\":\"注册日期\", \"value\":\"2015-11-16\"},"
                  "{\"index\":6, \"key\":\"last_login\", \"label\":\"上次登录时间\", \"value\":\"2015-12-22 15:38:54\"},"
                  "{\"index\":7, \"key\":\"tags\", \"label\": \"标签\", \"value\": \"企业,vip\"},"
                  "{\"index\":8, \"key\":\"leaderId\", \"value\": \"1001\"}"]";

[[QYSDK sharedSDK] setUserInfo:userInfo];

# Android SDK 调用

创建一个YSFUserInfo实例，将包含用户信息的 JSON 字符串填充到YSFUserInfo.data。调用Unicorn.setUserInfo()时将此YSFUserInfo实例作为参数传递给网易七鱼 SDK。

YSFUserInfo userInfo = new YSFUserInfo();
userInfo.userId = "uid";
userInfo.data = "[{\"key\":\"real_name\", \"value\":\"土豪\"},
                  {\"key\":\"mobile_phone\", \"hidden\":true, \"value\":\"13800000000\"},
                  {\"key\":\"email\", \"value\":\"13800000000@163.com\"},
                  {\"index\":0, \"key\":\"account\", \"label\":\"账号\", \"value\":\"zhangsan\" , \"href\":\"http://example.domain/user/zhangsan\"},
                  {\"index\":1, \"key\":\"sex\", \"label\":\"性别\", \"value\":\"先生\"},
                  {\"index\":5, \"key\":\"reg_date\", \"label\":\"注册日期\", \"value\":\"2015-11-16\"},
                  {\"index\":6, \"key\":\"last_login\", \"label\":\"上次登录时间\", \"value\":\"2015-12-22 15:38:54\"},
                  {\"index\":7, \"key\": \"tags\", \"label\": \"标签\", \"value\": \"企业,vip\" },
                  {\"index\":8, \"key\": \"leaderId\", \"value\": \"1001\" }]";

Unicorn.setUserInfo(userInfo);

# 参数说明

网易七鱼系统轻量对接中的参数，不论是 Web SDK、iOS SDK、还是 Android SDK，都由一个用户唯一性标识uid和一个表示用户信息的 JSON 数组data组成。

在 Web SDK 中uid和data都直接出现在 JSON 中。iOS SDK 和 Android SDK 中，各定义了一个保存用户信息的结构体：iOS 中为QYUserInfo，Android 中为YSFUserInfo。iOS SDK 中，QYUserInfo.userId成员为用户唯一性标识字符串，QYUserInfo.data成员为表示用户信息的 JSON 字符串。Android SDK 中，YSFUserInfo.userId成员为用户唯一性标识字符串，YSFUserInfo.data成员为表示用户信息的 JSON 字符串。

下文参数说明中的uid分别对应 Web SDK 中的 JSON 字段 uid、iOS SDK 中的QYUserInfo.userId、Android SDK 中的YSFUserInfo.userId；data分别对应 Web SDK 中的 JSON 字段 data、iOS SDK 中的QYUserInfo.data、Android SDK 中的YSFUserInfo.data。需要特别注意的是，UID长度不能超过64个字符。

参数
 类型 必须 说明
uid String 是 用户唯一性标识。
data Array / String 是 用一个数组（或表示 JSON 数组的字符串），表示要显示在客服端的扩展信息。

其中data字段用一个数组（iOS / Android SDK 中是一个表示 JSON 数组的字符串）描述用户的详细信息，数组中每个元素代表一个数据项。数据项以<key, value>对的形式为基础，增加了额外的字段以控制显示样式。数据项定义如下：

字段
 类型 必须 说明
key String 是 数据项的名称，用于区别不同的数据。其中real_name、mobile_phone、email为保留字段，分别对应客服工作台用户信息中的“姓名”、“手机”、“邮箱”这三项数据。保留关键字对应的数据项中，index、label属性将无效，其显示顺序及名称由网易七鱼系统指定。
value Mixed 是 该数据显示的值，类型不做限定，根据实际需要进行设定。
label String 是 该项数据显示的名称。
index Int 否 用于排序，显示数据时数据项按index值升序排列；不设定index的数据项将排在后面；index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列。
href String 否 超链接地址。若指定该值，则该项数据将显示为超链接样式，点击后跳转到其值所指定的 URL 地址。
hidden Boolean 否 仅对mobile_phone、email两个保留字段有效，表示是否隐藏对应的数据项，true为隐藏，false为不隐藏。若不指定，默认为false不隐藏。
isCustomField Boolean 否 是否属于自定义字段。如果是，则尝试匹配自定义字段名称并更新值，目前只支持 文本、数字、时间(13位数字时间戳)、单选、多选(用 ### 分割选中值，其中###前后都有空格)。

注意： real_name、mobile_phone、email三个保留字段的特别说明：

  • 若使用保留字段，数据将对应显示在“姓名”、“手机”、“邮箱”的位置上，顺序、名称不能指定；
  • 若使用保留字段，“姓名”、“手机”、“邮箱”对应的数据将不可编辑，以传递的数据为准；在不使用保留字段的情况下，这三项内容以客服填写的为准，并且可以修改；
  • 其中mobile_phone、email两项可以通过hidden字段隐藏，real_name不可隐藏；
  • 如果既想通过轻量对接提供“姓名”、“手机”、“邮箱”这三项数据，又希望客服可以修改、维护这些信息，可以避开保留关键字，用不同的key来提供数据；这在访客改变了联系方式，但没有及时更新用户信息的情况下非常有用。

注意： tags字段说明：

  • key值为'tags'时，该行数据对应七鱼系统内的用户标签数据
  • 更新方式为覆盖，value内为标签名，以逗号分隔（注意不带空格，英文逗号），传入时会与七鱼系统内标签信息进行比对，如果标签名一致，会将该用户标签属性更改为传入的标签属性。value如果为空值，则不做更改（不会将用户标签属性清空）。
  • 如果轻量crm和crm接口对接都有key为'tags'的数据，且二者值不同，将用接口数据覆盖轻量数据

注意： leaderId字段说明：

  • key值为'leaderId'时，该数据对应七鱼系统内的负责人数据
  • value值为该客户对应的负责人客服id，客服id可以使用openapi的客服考勤和质量报表查询，也可以在管理端会话流程-会话分配-自定义链接分配下方查询
  • 传入的负责人id不在客服工作台内显示（客服工作台会显示负责人用户名）
  • 负责人分配仅在开启手动分配开关时生效，如果开启自动分配，传入的负责人会被自动分配覆盖

注意： 提交的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高，应当在提交时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

# CRM接口对接

# 概述

企业CRM接口由企业开发者开发实现，并填写在七鱼后台的“设置--信息对接-CRM信息对接”中；当用户接入时，七鱼会调用相应接口，使用轻量对接中传递的uid；开发者在七鱼后台设置的appid以及获取token接口中拿到的token，去请求获取用户信息等接口，并将开发者的正确返回展示在当前客服聊天页面右侧的“更多信息”标签下（在“历史咨询”中也适用）。

企业实现这些接口，可以为网易七鱼系统提供用户信息、订单信息等 CRM 数据，以便客服在工作时方便地获得丰富的信息，更好的提供服务。

企业接口为一系列 HTTP （或 HTTPS）接口，由网易七鱼系统发起调用。网易七鱼系统与企业 CRM 系统通过这些接口进行数据交换，数据通常以 JSON 格式展现。即：

  • 网易七鱼系统调用企业接口时，通常是向企业接口 POST 一段描述请求内容的 JSON，企业发送该请求会自动发送两遍，第一个请求是OPTION类型，第二个请求是POST类型；（两个请求都需要支持跨域访问）
  • 企业接口返回数据给七鱼系统时，也返回一段包含所请求的数据的 JSON。

数据格式请仔细阅读每个接口的说明。

为保证数据的安全、并考虑一定的扩展性，企业需提前给网易七鱼系统分配appid、appsecret用于接口调用时的认证。认证方式见下。

本文档中的接口地址都为相对路径。接口完整的 URL 需要在网易七鱼管理端进行设置，七鱼管理后台->系统->扩展与集成

# 跨域访问

除验证用户身份接口外，其他接口都由网易七鱼系统客服端前端发起调用，所以这些接口需要支持跨域访问。接口的响应头域(Header)中需要添加以下参数：

Access-Control-Allow-Headers: origin, x-csrftoken, content-type, accept, x-auth-code, X-App-Id, X-Token
Access-Control-Allow-Method: POST, GET, OPTIONS
Access-Control-Allow-Origin: https://xxx.qiyukf.com,http://xxx.qiyukf.com

其中Access-Control-Allow-Origin中的xxx应该替换为企业在网易七鱼系统上申请的二级域名（或者可以直接设置允许全部 Access-Control-Allow-Origin: *）。

更多信息请参考 W3C Recommendation: Cross-Origin Resource Sharing (opens new window)。

# 接口认证方式

新版接口认证方式：（2022年9月22日之后创建的新企业在获取用户信息（在线）时使用新版接入方式，呼叫仍使用老版本）

POST请求将携带以下URL参数：

参数 参数说明
time 当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksum SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写)，其中md5为请求体的md5哈希值

其中checksum计算方式请参见通用说明-数据校验

老版本接口认证方式：

接口认证方式有两种可选：

  • 若企业提供获取token并且通过该接口可以获取到token时，则后续所有请求通过appid、token来确认请求的合法性（如本文档所示）；
  • 若企业不提供获取 token 并且通过该接口获取到的响应为空时，则所有请求都直接用appsecret当做token来使用。

认证参数传递方式也有两种可选：

  • 放在request body的JSON中：参数的键名为"appid"、"token"（如本文档所示）；
  • 放在request的头域(Header)中：参数的域名为"X-App-Id"、"X-Token"。

# 获取 token

GET /get_token

与其他接口不同，获取 token 接口为 GET 请求。该接口由网易七鱼系统后端服务器调用，并根据返回的有效期决定调用时机。

请求参数：

参数 类型 必须 说明
appid String 是 企业分配给网易七鱼系统的 appid
appsecret String 是 企业分配给网易七鱼系统的 appsecret

返回参数：

接口应该返回一段包含 token 和有效期的 JSON。

{
    "rlt": 0,
    "token": "qiyukf_security_token",
    "expires": 7200000
}
字段
 类型 必须 说明
rlt Int / String 是 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述，见Appendix I节。
token String 是 后续接口调用时使用的有效 token。
expires Int 否 表示此token离过期剩余的 毫秒数（非过期时间戳）。若不指定、或小于等于零，则默认为 2 小时。token失效后，其他接口应返回错误码2。

# 访客身份识别

七鱼通过用户唯一标识来识别访客身份，不同的接入渠道中所使用的用户唯一标识有所区别：

# Web接入

Web将用户发起会话时上报的uid作为用户唯一标识，在接入七鱼的网页中，调用ysf('config')函数，将uid传给七鱼，示例如下：

ysf('config', {
    uid: '123456'
});

# 移动端SDK接入

Android SDK需在发起会话时上报uid作为用户唯一标识，上报方法:创建一个YSFUserInfo实例，将包含用户信息的 JSON 字符串填充到YSFUserInfo.data。调用Unicorn.setUserInfo()时将此YSFUserInfo实例作为参数传递给网易七鱼 SDK。示例如下：

YSFUserInfo userInfo = new YSFUserInfo();
userInfo.userId="uid";
Unicorn.setUserInfo(userInfo);

iOS SDK需在发起会话时上报uid作为用户唯一标识，上报方法:创建一个QYUserInfo实例，将包含用户信息的 JSON 字符串填充到QYUserInfo.data。调用setUserInfo时将此QYUserInfo实例作为参数传递给网易七鱼 SDK。示例如下：

QYUserInfo *userInfo = [[QYUserInfo alloc] init];
userInfo.userId = @"uid";
[[QYSDK sharedSDK] setUserInfo:userInfo];

# 微信接入

使用授权方式完成的微信接入，七鱼会将访客微信OpenID作为用户唯一标示。此种方式接入，需要对接企业维护OpenID与企业原有用户体系的对应关系。 使用H5页面嵌入方式完成的微信接入，由于七鱼无法获取到OpenID，与Web接入类似的，需要通过ysf.config()函数，将访客uid传给七鱼。

# 电话接入

呼叫中心将以访客呼入电话号码作为用户唯一标识。

# 获取用户信息

（新企业在在线会话中获取用户信息时使用新版本的认证模式，呼叫仍使用老版本）

POST /get_user_info 在线会话获取用户信息

POST /get_call_user_info 呼叫中心获取电话用户信息

网易七鱼系统在需要获取访客详细信息时，会调用该接口。该接口请求类型不同于token，前端会自动发送两次请求，第一次的请求类型是OPTION，第二次的请求类型是POST，且POST提交数据的方式为application/json。

返回的数据将显示在“当前会话”中右侧用户资料区的“更多信息”标签页下，以及“历史会话”中右侧会话详情区的“更多信息”标签页下。

用户的唯一性标识会被作为请求内容 POST 到该接口。

请求示例：

{
    "appid": "qiyukf",
    "token": "qiyukf_security_token",
    "userid": "zhangsan",
    "staffphone": "057189850000"
}

请求参数：

参数 类型 必须 说明
appid String 是 企业分配给网易七鱼系统的 appid。
token String 是 当前有效的 token。
userid String 是 用户的唯一性标识。
staffphone String 否 企业和用户联系时使用的中继号码。

注意：userid来源于用户发起会话时，调用各端 SDK 的初始化代码时传递给网易七鱼系统的参数中。

**备注：**平台电商中的用户信息对接参数将增加shopid,获取对应商户下的用户信息。

返回示例：

接口应该返回一段包含用户数据的 JSON。

{
    "rlt": 0,
    "uid": "zhangsan",
    "data": [
        {"index": 0, "key": "account", "label": "账号", "value": "zhangsan", "href": "url"},
        {"index": 1, "key": "name", "label": "姓名", "value": "土豪", "edit": true, "map": "real_name", "href": "url"},
        {"index": 2, "key": "phone", "label": "手机", "value": "13800000000", "edit": true, "map": "mobile_phone", "href": "url"},
        {"index": 3, "key": "email", "label": "EMail", "value": "13800000000@163.com", "edit": true, "map": "email", "href": "url"},
        {"index": 4, "key": "tags", "label": "标签", "value": "企业,vip"},
        {"index": 5, "key": "vip", "label": "会员", "value": [{"id": 0,"name": "类型一"},{"id": 1,"name": "类型三", "check": true},{"id": 2,"name": "类型二"}], "select": true},
        {"index": 6, "key": "leaderId", "value": "1001"}

    ],
    "modify_cb": "url"
}

返回参数：

字段
 类型 必须 说明
rlt Int / String 是 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述，见Appendix I节。
uid String 否 get_call_user_info接口返回该字段，用于将同一用户手机号和uid关联，打通呼叫和在线历史咨询记录
data Array 是 用一个数组表示用户详细信息的数据。
modify_cb String 否 如果企业希望客服可以在网易七鱼系统中更新客户的信息，则在此提供一个接口的地址，用于客户信息修改后回调。接口定义见下。

其中data字段用一个数组描述用户的详细信息，数组中每个元素代表一个数据项。数据项以<key, value>对的形式为基础，增加了额外的字段以控制显示样式。数据项定义如下：

字段
 类型 必须 说明
key String 是 数据项的名称，用于区别不同的数据。特别地，如果该数据可编辑（见edit字段说明），key将作为请求的内容提交给回调接口。
value Mixed 是 该数据显示的值，类型不做限定，根据实际需要进行设定。
label String 是 该项数据显示的名称。
index Int 否 用于排序，显示数据时数据项按index值升序排列；不设定index的数据项将排在后面；index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列。
href String 否 超链接地址。若指定该值，则该项数据将显示为超链接样式，点击后跳转到其值所指定的 URL 地址。
edit Boolean 否 表示该项数据是否可编辑，true为可编辑，false为不可编辑。可编辑时该项数据的值将显示在一个输入框内，内容被编辑后将调用modify_cb接口提交更新。
map String 否 表明该项数据是否与网易七鱼系统中固定的数据项有映射关系。如真实姓名为real_name，手机号为mobile_phone，电子邮箱为email。如果一个数据项指定了正确的map值，则该数据也会同步显示在“当前会话”中右侧用户资料区的“用户资料”标签页下对应的项目中，以及“历史会话”中右侧会话详情区的“用户资料”标签页下对应的项目中。
save Boolean 否 是否将姓名、邮箱、手机号三个保留字段数据保存到网易七鱼系统中。true为保存，false或为空时不保存。将数据保存到网易七鱼系统有助于“历史会话”搜索和列表展示，不保存时则无法通过该项数据进行搜索。仅在轻量接入中不传三个保留字段时有效；若轻量传了，就展示轻量中传得值（轻量传空，就显示空）
zone Boolean 否 用于表明该项数据信息的展现位置。不设置表示仅显示在呼叫中心和在线会话“更多信息” 的标签下。true表示同时可显示在呼叫中心的“账户资料”和在线会话的“用户信息”的页面中。
select Boolean 否 用于标识该项数据是否为select下拉框。true表示该项数据为select下拉框的形式，且当select选项为true时，value字段应该为一个数组的形式（可以在value中指定初始化check为true的默认选中现，如果没指定则默认选中第一项）。
check Boolean 否 配合select一起使用，用于标识该select下拉框选项是否被选中。true表示该数据项被选中，且check为true的选项仅有一个。

注意： 返回的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高，应当在返回时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

# 微信生态获取用户信息

企业前期准备：

  1. 需要企业自行获取微信生态相关用户唯一ID

    a. 获取微信公众号/小程序 UnionID （微信官方UnionID 机制说明 (opens new window)）

    b.【企微场景】获取企微外部联系人客户的（UnionID ）和明文external_userid（企业内部开发者获取外部联系人external_userid (opens new window)）。通过此方式企业可将企微外部联系人与公众号/小程序用户关联起来。仅当联系人类型是微信用户，且企业绑定了微信开发者ID时可获取到UnionID字段。

    c.【企微场景】因企微官方不允许三方服务商获取企业明文ID。因此企业需要自行调用接口支持将七鱼获取的密文external_userid转换为企业主体对应的明文ID。（自建应用与第三方应用的对接 (opens new window)）

  2. 企业需要自行维护UnionID、明文external_userid与自己的业务数据的映射关系

    a. 建议可以通过UnionID+external_userid关联公众号/小程序/企微，小程序内登录企业自有账号、授权手机号等方式，将微信生态与其他渠道用户数据打通

POST /get_user_info（在【系统管理】-【扩展与集成】-【在线微信生态对接URL】设置URL） 请求示例：

{
    "appid": "appid",
    "openid": "微信三方id",
    "sourceappid": "主体id",
    "unionid": "企微客服(fromType为wx_cs)渠道值为密文external_user_id，其他渠道为微信unionId",
    "fromType": "wx_sc：企微客服渠道,其他为微信生态"
}

接口应该返回一段包含用户数据的 JSON。

{
  "rlt": 0,
  "uid": "wxcs-woniusanbu",
  "name": "蜗牛",
  "email": "test@163.com",
  "mobile": "13888888888",
  "level": 1,
  "data": [{ "key": "real_name", "value": "小明-七鱼" },
    { "key": "mobile_phone", "value": "15968136257" },
    { "key": "email", "value": "qiyu0@163.com" },
    {"key": "tags","hidden": false,"label": "标签","value": "test2000"},
    { "index": 0, "key": "account", "label": "账号", "value": "zhangsan", "href": "http://example.domain/user/zhangsan" },
    { "index": 1, "key": "sex", "label": "性别", "value": "先生1" },
    { "index": 2, "key": "sexa", "label": "性别2", "value": "先生2" },
    { "index": 3, "key": "sexb", "label": "性别3", "value": "先生3" },
    { "index": 10, "key": "reg_date", "label": "注册日期", "value": "2015-11-16" },
    { "index": 11, "key": "last_login", "label": "上次登录时间", "value": "2015-12-22 15:38:54" },
    {"key": "飞书用户名","label": "飞书用户名","value": "3333","isCustomField":true}]
}

返回参数：

字段
 类型 必须 说明
uid String 否 用户唯一id，用于将服务记录打通
data Array 是 用一个数组表示用户详细信息的数据。

其中data字段用一个数组描述用户的详细信息，数组中每个元素代表一个数据项。数据项以<key, value>对的形式为基础，增加了额外的字段以控制显示样式。数据项定义如下：

字段
 类型 必须 说明
key String 是 数据项的名称，用于区别不同的数据。特别地，如果该数据可编辑（见edit字段说明），key将作为请求的内容提交给回调接口。
value Mixed 是 该数据显示的值，类型不做限定，根据实际需要进行设定。
label String 是 该项数据显示的名称。
index Int 否 用于排序，显示数据时数据项按index值升序排列；不设定index的数据项将排在后面；index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列。
href String 否 超链接地址。若指定该值，则该项数据将显示为超链接样式，点击后跳转到其值所指定的 URL 地址。
map String 否 表明该项数据是否与网易七鱼系统中固定的数据项有映射关系。如真实姓名为real_name，手机号为mobile_phone，电子邮箱为email。如果一个数据项指定了正确的map值，则该数据也会同步显示在“当前会话”中右侧用户资料区的“用户资料”标签页下对应的项目中，以及“历史会话”中右侧会话详情区的“用户资料”标签页下对应的项目中。
isCustomField Boolean 否 表明是否已在网易七鱼系统中存在自定义字段做保存。

注意： 返回的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高，应当在返回时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

# 企微客服群聊获取群信息

企业前期准备：

  1. 需要客户提前做好企微自建应用接口对接，获取群chatid（获取客户群列表 (opens new window) 、 获取客户群详情 (opens new window)）
  2. 客户需要自行维护企业微信群 chatid与自己的业务数据的映射关系（可以通过群信息中群名、群公告、群管理员等）

POST /get_group_info（在【系统管理】-【扩展与集成】-【在线企微客服群聊对接URL】设置URL） 请求示例：

{
    "chatId": "wrWxx_EQAAs2IlU8oYjaSh48ve7iJi9A",
    "fromType": "wx_cs" //wx_cs:企微客服渠道
}

接口应该返回一段包含用户数据的 JSON。

{
  "rlt": 0,
  "level": 1,
  "data": [
    {"key": "tags","hidden": false,"label": "标签","value": "test2000"}, 
    {"key": "leaderId","hidden": false,"label": "标签","value": "12222"},
    {"index": 0,"key": "企微自定义字段名","label": "企微自定义字段名","value": "3333","isCustomField":true}]
}

返回参数：

字段
 类型 必须 说明
uid String 否 用户唯一id，用于将服务记录打通
data Array 是 用一个数组表示用户详细信息的数据。

其中data字段用一个数组描述用户的详细信息，数组中每个元素代表一个数据项。数据项以<key, value>对的形式为基础，增加了额外的字段以控制显示样式。数据项定义如下：

字段
 类型 必须 说明
key String 是 数据项的名称，用于区别不同的数据。特别地，如果该数据可编辑（见edit字段说明），key将作为请求的内容提交给回调接口。
value Mixed 是 该数据显示的值，类型不做限定，根据实际需要进行设定。
label String 是 该项数据显示的名称。
index Int 否 用于排序，显示数据时数据项按index值升序排列；不设定index的数据项将排在后面；index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列。
href String 否 超链接地址。若指定该值，则该项数据将显示为超链接样式，点击后跳转到其值所指定的 URL 地址。
map String 否 表明该项数据是否与网易七鱼系统中固定的数据项有映射关系。如真实姓名为real_name，手机号为mobile_phone，电子邮箱为email。如果一个数据项指定了正确的map值，则该数据也会同步显示在“当前会话”中右侧用户资料区的“用户资料”标签页下对应的项目中，以及“历史会话”中右侧会话详情区的“用户资料”标签页下对应的项目中。
isCustomField Boolean 否 表明是否已在网易七鱼系统中存在自定义字段做保存。

注意： 返回的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高，应当在返回时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

# 更新用户信息

POST /[modify_cb]

用户的唯一性标识和被修改的信息会被作为请求内容 POST 到该接口，与获取信息不一样的是，更新类接口POST提交数据的方式为application/x-www-form-urlencoded。

接口地址由获取用户信息接口/get_user_info返回的modify_cb的内容指定。

请求示例：

{
    "appid":"qiyukf",
    "token":"qiyukf_security_token",
    "userid":"zhangsan",
    "data":[
        {"key":"name", "value":"张三"},
        {"key":"phone", "value":"1397777777X"}
    ]
}

请求参数：

参数 类型 必须 说明
appid String 是 企业分配给网易七鱼系统的 appid。
token String 是 当前有效的 token。
userid String 是 用户的唯一性标识。
data Array 是 用一个数组表示修改的用户信息数据。

注意：userid来源于用户发起会话时，调用各端 SDK 的初始化代码时传递给网易七鱼系统的参数中。

其中data用一个数组描述提交修改的数据，数组的每个元素表示一个数据项。数据项以<key, value>对的形表示：

字段
 类型 必须 说明
key String 是 数据项的名称，用于区别不同的数据。key的值来源于获取用户信息/get_user_info接口返回的信息中对应数据项的key。
value String 是 该数据修改后的值。都视为字符串进行传输。

返回示例：

接口应该返回一段包含用户信息更新结果的 JSON。

{
    "rlt":0,
    "data":[
        {
            "key":"name",
            "msg":"名字太长了。"
        },
        {
            "key":"phone",
            "msg":"手机号格式错误。"
        }
    ]
}

返回参数：

字段
 类型 必须 说明
rlt Int / String 是 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述，见Appendix I节。
data Array 否 当rlt不为0时，用一个数组表示每项数据修改失败的原因提示。

其中data字段用一个数组描述修改失败的提示信息，数组中每个元素代表一个数据项。数据项定义如下：

字段 类型 必须 说明
key String 是 数据项的名称，用于区别不同的数据。对应请求中数据项的key。
msg String 是 该项数据修改失败的错误提示。

需要注意的是，客服平台前端采用失焦保存策略（鼠标移开后点击其他区域变自动保存），所以每次只能修改一个参数。该策略能为客服减少操作，提升效率。

# 获取订单信息

POST /get_order 在线会话获取用户订单信息

POST /get_call_order 呼叫中心获取用户订单信息

网易七鱼系统在调用获取访客详细信息接口/get_user_info时，会调用该接口。该接口企业在发送请求时，前端会自动发送两遍，第一遍的请求类型是OPTION，第二遍的请求类型是POST，提交数据方式采用application/json的方式。该接口可用于电商行业订单类信息，也可以用于金融行业交易类信息。

返回的数据将显示在“当前会话”中右侧用户资料区的“更多信息”标签页下，以及“历史会话”中右侧会话详情区的“更多信息”标签页下。

在这两个标签下，用户的订单信息会显示在用户详细信息（/get_user_info接口返回的数据）之下。

用户的唯一性标识会被作为请求内容 POST 到该接口。

请求示例：

{
    "appid": "qiyukf",
    "token": "qiyukf_security_token",
    "userid": "zhangsan",
    "count": 10,
    "from": 0,
    "type": 0
}

请求参数：

参数 类型 必须 说明
appid String 是 企业分配给网易七鱼系统的 appid。
token String 是 当前有效的 token。
userid String 是 用户的唯一性标识。
count Int 是 请求返回订单的最大数量。与from配合使用实现分页。
from Int 是 请求返回订单列表的偏移量，与count配合使用实现分页。
type Int 是 订单类型

注意：userid来源于用户发起会话时，调用各端 SDK 的初始化代码时传递给网易七鱼系统的参数中。

备注：：平台电商中的订单信息对接参数将增加shopid,获取对应商户下的订单信息。

返回示例：

接口应该返回包含指定用户订单类数据列表的一段 JSON。

{
    "rlt": 0,
    "count": 2,
    "orders": [
        {
            "index": 0,
            "blocks": [
                {
                    "index": 0,
                    "is_title": true,
                    "data": [
                        { "index": 0, "key": "orderid",  "label": "订单号", "value": "00001", "href": "url"}
                    ]
                },
                {
                    "index": 1,
                    "data": [
                        {"index": 0, "key": "product", "label": "产品名称", "value": "易钱包", "href": "url"},
                        {"index": 1, "key": "amount", "label": "支付金额", "value": "2000.00元"},
			{"index": 2, "key": "basic_proc", "label": "基础产品", "value": "渤海人寿保险" , "href": "url"},
                        {"index": 3, "key": "revenue_yesterday", "label": "昨日收益", "value": "1.00元"},
                        {"index": 4, "key": "revenue_amount", "label": "累计收益", "value": "2.00元" }
                    ]
                }
            ]
        },
        {
	    "index": 1,
	    "blocks": [
                {
                    "index": 0,
                    "is_title": true,
                    "data": [
                        { "index": 0, "key": "orderid",  "label": "订单号", "value": "00002", "href": "url"}
                    ]
                },
                {
                    "index": 1,
                    "data": [
                        {"index": 0, "key": "product", "label": "产品名称", "value": "易钱包", "href": "url"},
                        {"index": 1, "key": "amount", "label": "支付金额", "value": "2000.00元"},
                        {"index": 2, "key": "basic_proc", "label": "基础产品", "value": "渤海人寿保险" , "href": "url"},
                        {"index": 3, "key": "revenue_yesterday", "label": "昨日收益", "value": "1.00元"},
                        {"index": 4, "key": "revenue_amount", "label": "累计收益", "value": "2.00元" }
                    ]
                }
            ]
        }
    ]
}

返回参数：

字段
 类型 必须 说明
rlt Int / String 是 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述，见Appendix I节。
count Int 是 表示该用户订单类数据的条目总数，而非此次请求返回的订单数量。用于控制分页。
orders Array 是 用一个数组表示用户订单列表的数据。

订单列表有多层数据嵌套：

  • orders的每一个元素表示一个订单；
  • 每个订单的信息可以按照内容分类，分割成多个区块进行显示，订单的blocks数组里保存了这些区块；
  • 每个区块中用一个data数组保存具体的数据，与用户详细信息数据类似，数组中每个元素代表一个数据项，数据项以<key, value>对的形式为基础，增加了额外的字段以控制显示样式。

以下为orders中每个订单的数据定义：

字段
 类型 必须 说明
index Int 是 用于排序，显示订单列表时订单按index值升序排列；不设定index的订单将排在后面；index相同或未设定的订单将按照其在 JSON 中出现的顺序排列。
blocks Array 是 用一个数组表示该订单包含的区块。

以下为blocks中每个区块的数据定义：

字段
 类型 必须 说明
index Int 是 用于排序，显示订单时区块按index值升序排列；不设定index的区块将排在后面；index相同或未设定的区块将按照其在 JSON 中出现的顺序排列。
data Array 是 用一个数组表示该区块包含的数据。
is_title Boolean 是 表示该区块是否作为该订单的标题行，true表示是标题行，false表示不是标题行。当一个区块是标题行时，它将会以订单标题的样式进行显示；而且点击该区块时，该订单会有展开/收起表现，被指定为is_title的项，它的data数据项的返回数组仅能有一个元素作为订单标题显示。每个blocks中都需要指定一个区块作为标题。

以下为data中每个数据项的定义：

字段
 类型 必须 说明
key String 是 数据项的名称，用于区别不同的数据。
value Mixed 是 该数据显示的值，类型不做限定，根据实际需要进行设定。
label String 是 该项数据显示的名称。
index Int 否 用于排序，显示数据时数据项按index值升序排列；不设定index的数据项将排在后面；index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列。
href String 否 超链接地址。若指定该值，则该项数据将显示为超链接样式，点击后跳转到其值所指定的 URL 地址。
edit Boolean 否 表示该项数据是否可编辑，true为可编辑，false为不可编辑。可编辑时该项数据的值将显示在一个输入框内，内容被编辑后将调用modify_cb接口提交更新。
select Boolean 否 用于标识该项数据是否为select下拉框。true表示该项数据为select下拉框的形式，且当select选项为true时，value字段应该为一个数组的形式value字段应该为一个数组的形式（可以在value中指定初始化check为true的默认选中现，如果没指定则默认选中第一项）。
check Boolean 否 配合select一起使用，用于标识该select下拉框选项是否被选中。true表示该数据项被选中，且check为true的选项仅有一个。

注意： 返回的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高，应当在返回时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

# 更新订单信息

POST /[modify_cb]

订单用户的唯一标识和被修改的信息会被作为请求内容 POST 到该接口，与获取信息不一样的是，更新类接口POST提交数据的方式为application/x-www-form-urlencoded。

接口地址由获取订单信息接口get_order返回的modify_cb的内容指定。

请求示例：

{
    "appid":"qiyukf",
    "token":"qiyukf_security_token",
    "userid":"zhangsan",
    "data":[
        {"key":"amount", "value":"3000元"},
        {"key":"phone", "value":"1397777777X"}
    ]
}

请求参数：

参数 类型 必须 说明
appid String 是 企业分配给网易七鱼系统的 appid。
token String 是 当前有效的 token。
userid String 是 用户的唯一性标识。
data Array 是 用一个数组表示修改的用户信息数据。

注意：userid来源于用户发起会话时，调用各端 SDK 的初始化代码时传递给网易七鱼系统的参数中。

其中data用一个数组描述提交修改的数据，数组的每个元素表示一个数据项。数据项以<key, value>对的形表示：

字段
 类型 必须 说明
key String 是 数据项的名称，用于区别不同的数据。key的值来源于获取订单信息/get_order接口返回的信息中对应数据项的key。
value String 是 该数据修改后的值。都视为字符串进行传输。

返回示例： 接口应该返回一段包含用户信息更新结果的 JSON。

{
    "rlt":0,
    "data":[
        {
            "key":"name",
            "msg":"名字太长了。"
        },
        {
            "key":"phone",
            "msg":"手机号格式错误。"
        }
    ]
}

返回参数：

字段
 类型 必须 说明
rlt Int / String 是 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述，见Appendix I节。
data Array 否 当rlt不为0时，用一个数组表示每项数据修改失败的原因提示。

其中data字段用一个数组描述修改失败的提示信息，数组中每个元素代表一个数据项。数据项定义如下：

字段 类型 必须 说明
key String 是 数据项的名称，用于区别不同的数据。对应请求中数据项的key。
msg String 是 该项数据修改失败的错误提示。

# 自定义接口参数

网易七鱼系统提供自定义配置获取用户信息和获取订单信息接口参数的功能。针对会话的场景，网易七鱼提供了在访客接入时采用扩展crm接入的方式自定义配置接口crm请求的参数。

自定义参数的扩展crm接入代码：


	ysf('config', {
	   uid:"1442286211167",
	   data:JSON.stringify([
		   {"key":"real_name", "value":"土豪"},
		   {"key":"mobile_phone", "hidden":true, "value":"13800000000"},
		   {"key":"email", "value":"13800000000@163.com"},
		   {"index":0, "key":"account", "label":"账号", "value":"zhangsan" , "href":"http://example.domain/user/zhangsan"},
		   {"index":1, "key":"sex", "label":"性别", "value":"先生"},
		   {"index":5, "key":"reg_date", "label":"注册日期", "value":"2015-11-16"},
		   {"index":6, "key":"last_login", "label":"上次登录时间", "value":"2015-12-22 15:38:54"},
		   {"type": "crm_param", "key": "startTime", "value": "2017-05-20", "area": "user"},
		   {"type": "crm_param", "key": "endTime", "value": "2017-05-21", "area": "order"},
		   {"type": "crm_param", "key": "creatTime", "value": "2017-05-20"}
	   ])
	});
字段 类型 必须 说明
type String 是 向七鱼声明配置类型为自定义参数类型
key String 是 规定请求接口时，自定义参数的参数名字
value String 是 规定请求接口时，自定义参数的参数值
area String 否 规定自定义参数请求接口的影响范围

其中area值为user时，表示只应用在获取用户信息接口，值为order时，表示只应用在获取订单信息接口，不设置area会分别应用在获取用户信息和订单的两个接口。

# 对接方式对比与建议

轻量对接与接口对接的比较。场景、开发难度、数据隔离。

建议不同的企业、团队，用不同的对接方式。

轻量对接方式与接口对接方式，都是为了给客服在服务过程中提供丰富的访客信息，从而提高服务质量与工作效率。然而两种对接方式在使用场景与实现方式方面各有不同，以下对两种对接方式进行对比。

对比角度
 轻量对接 接口对接
数据来源 发起会话时，客户端通过 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：第三方的用户唯一标识

# 认证过程

  1. 第三方提供一个生成随机授权码authToken的授权接口，authToken生成后需要暂存在第三方服务器端，供之后的uid校验使用；
  2. 申请客服或上报CRM信息请求时，先调用上面接口，获取随机授权码authToken，并将其传递给七鱼；
  3. 七鱼前端将获取到的authToken和uid作为参数传递到七鱼服务器端；
  4. 七鱼服务器收到请求后，携带authToken和uid，调用第三方认证接口进行校验；
  5. 第三方将收到的authToken与本地暂存的authToken进行比较，看是否一致，并返回校验结果；
  6. 如果authToken和uid校验失败，七鱼服务器会忽略请求，并返回失败信息到前端页面。

# 实施流程

  1. 第三方知会七鱼需开启用户认证，并协调约定开启时间；
  2. 第三方在约定的开启之前准备好认证接口，将线上接口地址提交给七鱼，并与七鱼做好联调工作；
  3. 第三方使用支持的SDK，并按下文中代码示例完成authToken的设置工作。

# 认证模式说明

认证模式需要联系技术支持进行修改，目前支持如下几种认证模式

  1. 不做校验，直接使用上传的foreignId，允许foreignId为空
  2. 如果有authToken和foreignId才校验authToken是否有效，如果authToken校验失败则不允许申请会话
  3. 如果有foreignId，则必须同时有authToken，并且校验authToken是否有效，如果authToken校验失败则不允许申请会话
  4. 必须有foreignId，如果有authToken才校验authToken是否有效，如果authToken校验失败则不允许申请会话
  5. 必须有foreignId和authToken，并且校验authToken是否有效，如果authToken校验失败则不允许申请会话
  6. 没有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参数对应Json数据格式：

{"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":false}

响应字段：

字段 含义
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参数:

  1. ysf('config') 设置 authToken 属性
  2. 调用 pollAuthToken 或 setAuthToken 设置 authToken 值

# pollAuthToken(url, options)

# 接口描述

此接口使用http/https请求主动拉第三方接口更新token, 由于网络原因等异常情况会导致http请求, 一旦请求失败会执行重试机制，保证token的更新, 用户可以自定义重试次数(默认为4次)。

  1. 第三方自定义获取token的api的接口
  2. 更新防止 token 失效
# 请求说明
 GET 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 否 失败回调
    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必填

# 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。

← iframe对接 →