# iframe对接

# 展示效果

七鱼 iframe 页面是可以将企业自身的某个页面嵌入在七鱼工作台的特定区域。以历史会话-会话详情页为例，可达到的效果如下图：

注：第三方嵌入到七鱼系统，涉及到需要cookie鉴权要处理跨域问题（解决方法：特定业务需要跨域传输cookie，可以显性设定http response header中set-cookie为SameSite=none）SameSite (opens new window)

右侧标注区域就是嵌入的页面

注：因为是嵌入七鱼工作台，所以展示区域受到七鱼工作台整体排版限制。前端开发需要让页面自适应展示。最小宽度：280px，最大宽度：((屏幕宽度 - 20) / 2 - 5)px；高度没有限制（可以展示下拉条）。

# 展示区域

根据 iframe 页面提供的业务服务内容的不同、以及权限不同的情况，七鱼提供了展示页面可配置服务。具体可以选择的展示区域有以下9组（以组为单位进行配置，组内不同页面不能单独处理）：

1、历史会话（管理端）、在线会话（客服端）、历史会话（客服端）

2、会话质检（管理端）、会话质检结果（管理端）、会话质检结果（客服端）

3、呼叫通话记录（管理端）、呼叫电话服务（客服端）、呼叫通话记录（客服端）

4、呼叫质检（管理端）、呼叫质检结果（管理端）、呼叫质检结果（客服端）

5、工单-我受理的、我提交的、历史工单、组内工单、工单搜索（管理端）、工单-我受理的、我提交的、历史工单、组内工单、工单搜索（客服端）

6、留言（客服端）

7、智能监控（客服端）

8、客户中心（管理端）

9、聊天助手

10、移动工作台-当前会话

11、客服工作台一级菜单栏

# 参数配置

嵌入页面后，大多数企业是需要该页面能获取当前界面的一些信息的，比如需要知道当前登录的客服是谁，在当前聊天窗口中的访客是谁等。考虑到此点，七鱼在配置 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 字段进行取值即可。

# 样例

以下截图是本次测试样例的所有七鱼配置项（企业提供信息，七鱼工作人员配置或企业自己配置）

轻量传的用户信息如下：

七鱼前端最终发起的 get 请求地址为：

https://www.163.com/?StaffAccount=zhouyongchao&UserId=zyctest&authAcceptWay=md5&authTim
e=2018-11-28%2016:55:02&domain=ysftest4&fromModule=qiyu_session&id=2231480344&key1=value1&key2=va
lue2&md5=18867feae5674793333c2501fb70eb48&qiyuCustomer={%22startTime%22:%222017-05-20%22,%22endTime%22:%222018-05-20%22}&timestamp=1543395302695

参数说明：

参数	示例值	说明
StaffAccount	zhouyongchao	客服账号
UserId	zyctest	轻量 CRM 中传的用户唯一 id
id	2231480344	会话 id
key1	value1	固定参数
key2	value2	固定参数
authAcceptWay	md5	MD5 加密固定参数
authTime	2018-11-28%2016:55:02	加密计算时间
md5	18867feae5674793333c2501fb70eb48	MD5 值
qiyuCustomer	{%22startTime%22:%222017-05-20%22,%22endTime%22:%222018-05-20%22}	轻量CRM 中传的 crm_param 类型自定义接口参数
domain	ysftest4	七鱼分配给企业的二级域名
fromModule	qiyu_session	来源类型现在就 3 种: qiyu_session=七鱼在线会话; qiyu_worksheet=七鱼工单; qiyu_callcenter=七鱼呼叫中心）
timestamp	1543395302695	请求时间戳

← CRM对接在线工具条对接 →