iOS集成DocuSign离线签名同步后如何获取正式envelope ID

问题场景 #

开发iOS应用集成DocuSign服务，采用offline-signing模式创建签署信封时，composeEnvelope方法仅返回本地临时envelope ID。当本地离线签署完成的信封同步至DocuSign官方平台后，会生成平台侧全新的正式envelope ID，需要在端侧获取该ID用于后续业务流程。

当前使用的创建签署流程代码如下：

mDSMEnvelopesManager?.composeEnvelope(with: envelope, signingMode: .offline, completion: { envelopeId, error in
    
    if let id = envelopeId {
        // 此处拿到的id是本地临时envelope ID
        self.mDSMEnvelopesManager?.resumeSigningEnvelope(withPresenting: presentingController, envelopeId: id, completion: { _, _ in })
    } else {
        // 在线模式错误处理
        self.showAlert(presentingController: presentingController, message: error.localizedDescription)
    }
})

注意：composeEnvelope和resumeSigningEnvelope的completion回调均不会返回平台正式envelope ID，回调触发时信封仅完成本地签署流程，尚未执行云端同步操作。

具体实现步骤 #

• 注册SDK提供的信封同步状态监听通知，离线信封完成云端同步、平台生成正式envelope ID后，SDK会主动抛出该通知，通知携带的userInfo中包含本地临时ID与云端正式ID的映射关系。
• 实现通知处理逻辑，从返回参数中提取正式envelope ID，关联本地存储的临时ID即可匹配对应业务单据。
• 签署完成后可主动调用同步方法触发上传，无需等待SDK自动同步时机。

代码示例 #

// 1. 在页面初始化/SDK初始化阶段注册同步通知
NotificationCenter.default.addObserver(
    self,
    selector: #selector(handleEnvelopeSyncComplete(_:)),
    name: NSNotification.Name("DSMEnvelopeSyncDidCompleteNotification"),
    object: nil
)

// 2. 实现同步完成回调处理
@objc func handleEnvelopeSyncComplete(_ notification: Notification) {
    guard let userInfo = notification.userInfo else { return }
    // 处理同步成功的信封，提取ID映射关系
    if let syncedEnvelopes = userInfo["DSMEnvelopeSyncSuccessUserInfoKey"] as? [[String: Any]] {
        for envelopeInfo in syncedEnvelopes {
            // 本地临时envelope ID
            let tempEnvelopeId = envelopeInfo["DSMEnvelopeIdKey"] as? String
            // 云端同步后生成的正式envelope ID
            let officialEnvelopeId = envelopeInfo["DSMEnvelopeRemoteEnvelopeIdKey"] as? String
            
            // 根据本地存储的tempEnvelopeId匹配业务数据，持久化存储对应的officialEnvelopeId
            print("临时ID: \(tempEnvelopeId ?? ""), 正式ID: \(officialEnvelopeId ?? "")")
        }
    }
    
    // 可选：处理同步失败的信封
    if let failedEnvelopes = userInfo["DSMEnvelopeSyncFailedUserInfoKey"] as? [[String: Any]] {
        // 实现重试、错误提示等逻辑
    }
}

// 3. 可选：在合适时机主动触发同步，比如签署完成、用户回到前台时
mDSMEnvelopesManager?.syncEnvelopes()

内容的提问来源于stack exchange，提问作者Nguyen Anh Thai