PHP集成DocuSign嵌入式签名会话超时与事件捕获问题咨询

阻止会话超时重复弹窗 #

• 初始化嵌入式签名iframe时，在配置项中添加disableLoggingAlerts: true，可直接关闭DocuSign内置的会话错误弹窗
• 额外添加iframe的postMessage事件监听，捕获到session_timeout类型的事件后，直接执行跳转逻辑，从上层阻断弹窗触发
• 生成签名视图的EnvelopeViews: createRecipient接口请求中，可配置超时回调规则，提前终止会话超时后的重复轮询请求，从根源避免弹窗触发

自定义会话超时页面 #

• 调用createRecipient接口生成嵌入式签名链接时，在请求参数中配置errorUrl字段，该字段对应的地址即为会话超时、签名失败等异常场景下的自动跳转地址
• 将errorUrl设置为自有系统开发的自定义超时页面地址即可，需要注意该地址必须为HTTPS协议，且域名需要提前添加到DocuSign后台应用的回调域名白名单中，否则跳转会被拦截

捕获签名完成按钮点击事件 #

DocuSign嵌入式签名的iframe会通过postMessage向外抛出全流程事件，在父页面添加事件监听即可捕获对应操作，参考代码如下：

window.addEventListener('message', (event) => {
  // 校验消息来源合法性，避免跨站安全风险
  if (!event.origin.includes('docusign.com')) return;
  const signEvent = JSON.parse(event.data);
  // 签名完成事件的state标识为signing_complete
  if (signEvent.state === 'signing_complete') {
    // 此处写入自有业务逻辑，例如更新单据状态、跳转成功提示页等
    console.log('用户完成签名', signEvent);
  }
  // 还可同步监听session_timeout、cancel、decline等其他事件做对应处理
})

内容的提问来源于stack exchange，提问作者developer2021