Web端页面嵌入

使用场景

在真实的业务场景中，一些比较复杂的场景，例如合同签署和模板设计，包含复杂的前端交互和数据处理，仅靠服务端API的能力，难以快速解决问题。腾讯电子签支持开发者将前端页面集成到自己的系统中，可以通过iframe嵌入的方式，解决前端的复杂问题。同时，嵌入的页面可以支持隐藏腾讯电子签的品牌信息，可以将腾讯电子签完全作为自己系统能力的一部分。

可支持的集成场景

当前可以支持的集成场景

• 创建印章；
• 创建模板；
• 修改模板；
• 预览模板；
• 预览合同；
• 发起合同；

陆续会开放更多的集成场景

获取页面嵌入链接

参考接口：创建嵌入web的链接

EmbedType参数是WEB嵌入资源类型，根据不同的取值获取Web页面嵌入的链接。

资源类型	参数值	资源ID
创建印章	CREATE_SEAL	无
创建模板	CREATE_TEMPLATE	无
修改模板	MODIFY_TEMPLATE	模板ID
预览模板	PREVIEW_TEMPLATE	模板ID
预览流程	PREVIEW_FLOW	合同ID

可以通过请求的方式，获取页面嵌入链接，再设置到iframe的src属性上。

// 以获取模板的方法举例
export default function CreateTemplate() {
  const location = useLocation();
  const [srcUrl, setSrcUrl] = useState('');
  const [loading, setLoading] = useState(false);

  const getCreateTemplateUrl = async () => {
    setLoading(true);
    // getWebUrl内部封装，ChannelCreateEmbedWebUrl
    const res = await getWebUrl({
      EmbedType: 'CREATE_TEMPLATE',
    });
    setLoading(false);
    setSrcUrl(res?.data?.data?.WebUrl || '');
  };

  useEffect(() => {
    getCreateTemplateUrl();
  }, []);

  return (
    <div className="demo-wrapper">
      {loading ? <Loading></Loading> : <iframe src={srcUrl}></iframe>}
    </div>
  );
}

发起合同

参考接口：创建预发起合同

发起合同时，当发起方需要填写合同控件时，可以通过调用发起合同的接口，获取到可嵌入的Web页面。在填写了控件之后，再发起合同。

前端集成的代码，可以参考获取页面嵌入链接中的示例代码，最佳实践如下：

第一步：用户输入发起方参数

此步骤中的交互表单，需要由开发者自己实现。发起合同的表单，可以参考下图的交互。表单填写完成后，服务端经过转发，调用腾讯云API接口创建预发起合同，即可获取到页面嵌入链接。

第二步：填写签署区控件并指定签署方

将返回的页面链接，放到页面的iframe中。

第三步：完成发起

Web端消息接口

腾讯电子签在嵌入的页面中，提供了对外暴露的消息接口，用于在iframe集成的时候，实现内外数据通信。消息通讯的机制，适用于一些业务数据的传递，以及对页面事件的监控。

开发者在使用iframe集成腾讯电子签页面后，可以在自己的系统页面内，使用addEventListener注册事件监听器。即可接收到腾讯电子签的前端页面推送的消息。

组件封装

以下为React组件的封装方法，可供参考

import React, { useRef } from 'react';

const Iframe = ({ src }) => {
  const iframeRef = useRef();

  useEffect(() => {
    const handler = (evt) => {
      // 通过messageType判断场景类型
      // 通过origin判断消息来源于电子签域名
      if (evt.data.messageType === 'NOT_LOGIN' && evt.origin === 'embed.qian.tencent.com') {
        // 处理你的业务逻辑
      }
    };
    window.addEventListener('message', handler); // 绑定消息的监听
    return () => {
      // 注意要记得解绑
      window.removeEventListener('message', handler);
    };
  }, []);

  return <iframe ref={iframeRef} src={src}></iframe>;
};

export default Iframe;