嵌入DocuSign时，iframe返回URL传递参数（envelope、PF、r ID）问题排查

一、怎么在iframe返回的URL里传递envelope、PF和r ID参数？ #

其实DocuSign提供了两种靠谱的方式来确保这些参数能在iframe的流程中正确传递：

1. 直接在iframe的src里拼参数
   当你写iframe标签的时候，把PF（你的PowerForm ID）、r（收件人角色ID）和envelopeId直接拼到PowerForm的URL后面就行，格式大概是这样：

   <iframe 
     src="https://demo.docusign.net/Member/PowerFormSigning.aspx?PF=你的PowerFormID&r=收件人角色ID&envelopeId=目标信封ID"
     width="100%" 
     height="800"
   ></iframe>
   

   注意：得确保你的PowerForm后台配置允许接收这些参数——去DocuSign后台编辑PowerForm的时候，要开启参数传递的相关选项，不然传了也白搭。

2. 通过完成回调URL传递参数
   如果是想在签名完成后的跳转页面拿到这些参数，那得在PowerForm的设置里配置“完成后重定向URL”，并且在URL里用DocuSign的占位符来自动填充参数值。比如：

   • 登录DocuSign后台找到对应的PowerForm，进入编辑界面
   • 找到“完成设置”，把重定向URL设成https://你的域名/回调页面?envelopeId={envelopeId}&PF={powerFormId}&r={recipientId}
     这样用户签完名后，iframe跳转到你的回调页面时，这些参数就会被自动替换成实际值，直接读取就行。

二、为啥直接开PowerForm链接能拿到参数，iframe里就不行？ #

这个问题我之前也碰到过，大概率是这几个原因：

• 跨域安全限制搞的鬼
  现代浏览器的SameSite Cookie政策和跨域安全规则，会限制iframe访问第三方域名的Cookie或者本地存储。如果你的参数是通过Cookie传递的，iframe里的页面根本读不到；但直接打开链接时，页面和DocuSign在同一上下文，就能正常获取。
  解决办法：要么让DocuSign那边把Cookie设成SameSite=None; Secure（前提是你的页面是HTTPS），要么干脆把参数都通过URL传递，别用Cookie。

• PowerForm默认禁止iframe嵌入
  有些PowerForm后台默认设置了禁止iframe加载（通过X-Frame-Options或者Content-Security-Policy头），这时候虽然iframe能打开页面，但会限制参数的传递和读取。
  解决办法：去DocuSign后台检查PowerForm的“嵌入设置”，确保允许在iframe中加载，同时开启参数传递的权限。

• 你在iframe里的URL没拼对参数
  直接打开的URL里参数是全的，但你写iframe的src时可能漏了参数，或者拼错了参数名（比如把envelopeId写成envelope，r的大小写搞错了）。
  解决办法：把直接打开的URL和iframe的src URL对比一下，确保参数名、值完全一致，没遗漏也没拼写错误。

• iframe的sandbox属性限制了权限
  如果你给iframe加了sandbox属性，可能限制了页面的导航或者参数传递。比如只加了allow-same-origin是不够的，得加上allow-top-navigation、allow-forms这些权限，才能让参数正常传递。
  举个例子：

  <iframe 
    src="你的PowerForm完整URL"
    sandbox="allow-same-origin allow-scripts allow-forms allow-top-navigation"
    width="100%" 
    height="800"
  ></iframe>
  

最后总结下排查步骤 #

1. 先检查iframe的src有没有正确拼接所有需要的参数；
2. 去DocuSign后台确认PowerForm允许iframe嵌入，且开启了参数传递；
3. 检查iframe的sandbox权限是否足够；
4. 打开浏览器开发者工具，看看网络请求里参数有没有被正确发送，有没有跨域相关的报错。

按这个步骤走，基本上能解决问题。

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