参数配置 - 网易七鱼 API

嵌入页面后，大多数企业是需要该页面能获取当前界面的一些信息的，比如需要知道当前登录的客服是谁，在当前聊天窗口中的访客是谁等。考虑到此点，七鱼在配置 iframe 的时候可以配置一些参数，在客服点击tab 访问 iframe 的时候通过 GET 请求带过去。具体参数有以下四大类：

1、映射参数

截图中红色标注区域为七鱼可提供映射的参数，黄色标注区域为映射至企业所用的参数名。

注：七鱼提供的客服账号需要开发者自己处理与实际客服人员的对应关系。如果轻量对接中没有传用户唯一 id和手机号，七鱼就无法映射回传给开发者。

2、固定参数

顾名思义，固定参数就是写死不变的，企业可以根据自身需求将七鱼请求 iframe 时候需要带上的固定参数给到 iframe 配置人员。 3、加密参数

考虑到 iframe 页面直接从七鱼页面发起，做用户和来源校验比较困难。七鱼访问 iframe 页面时，会拼接客服账号，用户账号等信息，为了避免越权访问，七鱼在页面的 url 中增加了 signature 参数，用于参数的完整性校验，以及确认链接由七鱼系统发起。在调用的 url 最后，增加 signature 参数，signature 参数值通过企业的 AppSecret 和 url 的参数串拼接，然后取 sha1 哈希值得到。同时，为了保证 url 的时效性，url 会附带一个 timestamp 参数，为生成 url 时的时间戳。对于 timestamp 不在指定范围（过早或过晚）的调用，被访问方可以拒绝。

java 代码示例如下：

// 假设 iframe 页面计算各个参数后，url 为：https://iframe.custom.com/path?param1=value1&param2=value2&paramN=valueN
String url = "https://iframe.custom.com/path?param1=value1&param2=value2&paramN=valueN";
String appSecret = "6226D081B3DB401E94AB61A864DF93B2"; // 取扩展与集成页面 开发者ID 下的 AppSecret
String queryString = "param1=value1&param2=value2&paramN=valueN"; // 可通过 javax.servlet.http.HttpServletRequest#getQueryString() 获取
String signature = org.apache.commons.codec.digest.DigestUtils.sha1Hex(appSecret + queryString);
// 得到最终的url
url = url + "&signature=" + signature;

为了保持对之前的兼容，同时保留了下面的 md5 校验参数，具体实现方式是：开发者提供用于加密校验的MD5_Key秘钥和固定加密字段Target，七鱼在请求的时候会将 MD5_Key 与当前的请求时间及Target三者做md5加密，并在url拼接时带上以下3个参数：

七鱼考虑到iframe 页面的信息安全因素，提供了MD5校验，具体实现方式是：开发者提供用于加密校验的MD5_Key秘钥和固定加密字段Target，七鱼在请求的时候会将MD5_Key与当前的请求时间及Target三者做md5加密，并在url拼接时带上以下3个参数：

参数	说明
authAcceptWay	加密方式，该值固定为“md5”开发者可以直接舍弃
md5	MD5 加密值
authTime	请求时间，格式为yyyyMMdd HH:mm:ss

开发者可以通过已有的MD5秘钥和固定加密字段Target以及七鱼请求带过来的authTime来验证md5值的有效性。以下是参数生成方法：

String authTime = TimeUtil.readableByDateTimeOfTimestamp(now);

String md5 = MD5.md5(md5Key.trim() + authTime.trim() + target.trim()).toLowerCase();

4、自定义接口参数

该参数比较特殊，不是七鱼人员可配置的，是开发者在轻量 CRM对接中传递给七鱼的。以下是七鱼开发指南对于自定义接口参数的说明：

该参数本身是在用户 CRM 信息接口中使用的，可以在用户发起会话的时候由开发者动态配置参数，然后客服查看访客更多信息（七鱼调用企业 CRM接口）时，七鱼可以在请求中把这类参数回传给企业 CRM 接口。iframe 也使用了这套逻辑，并且不区分 area，会将所有的"type"和"crm_param"类型的参数透传给iframe页面，企业在iframe页面中通过url拼接上来的qiyuCustomer 字段进行取值即可。