Web页面嵌入能力说明

使用场景

腾讯电子签支持开发者将部分核心前端页面集成到自己的系统中，可以通过 iframe 嵌入的方式，解决前端的复杂问题，从而大大提高集成效率。

支持的集成页面

常规页面	创建印章
	印章列表
	印章详情
	企业拓展服务配置页面
合同签署页面	企业签署方PC签署页面

主题风格配置

API 链接

创建页面主题配置

能力说明

通过此接口，可以配置 Web 页面嵌入时，Web 页面中的个性化配置，包括主题色以及是否显示电子签 Logo 等。此接口全局生效，应在调其他可嵌入页面接口之前调用。

接口能力说明

获取常规可嵌入页面

API 链接

获取常规可嵌入页面

接口能力说明

通过此接口可获取创建印章、企业拓展服务配置等常规页面。EmbedType 参数是 WEB 嵌入资源类型，根据不同的取值获取 Web 页面嵌入的链接。

页面名称	参数值	资源 ID
创建印章	CREATE_SEAL
印章列表页	PREVIEW_SEAL_LIST
印章详情页	PREVIEW_SEAL_DETAIL	印章 ID
企业拓展服务配置页	EXTEND_SERVICE

获取企业签署合同 web 页面

API 链接

获取企业签署合同 web 页面

接口能力说明

通过此接口可获取单个或多个合同的 PC 端签署页面，仅支持企业签署方。

页面示例

企业拓展服务

创建印章

印章列表

印章详情

企业签署合同

iframe 嵌入前端代码示例

以获取创建模板（CREATE_TEMPLATE）页面的场景为例。以下为 React 组件的封装方法，可供参考。

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

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

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

  return <div className='demo-wrapper'>{loading ? <div class='loading'></div> : <iframe src={srcUrl}></iframe>}</div>;
}

Web 端消息接口

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

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

目前已支持的消息类型如下：

消息类型	描述	页面范围
NOT_LOGIN	页面未登录或者登录态失效时触发	所有页面

以下为 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;