# # Signature Workflow API Migration Guide

## # Background of Changes

Starting from version 11.0.0, Foxit PDF SDK for Web has restructured the signature and signature verification-related APIs. This change aims to enhance the flexibility and extensibility of the signature workflow while providing developers with more powerful customization capabilities. The new API not only unifies the service entry points for signature and signature verification but also supports deep customization of the signature UI, significantly improving integration efficiency for diverse business scenarios.

## # Key Changes

### # API Hierarchy Adjustments

- The previou version used APIs like `PDFUI.registerSignatureFlowHandler` and `PDFUI.setVerifyHandler` to customize signature and verification workflows.

- The new version introduces `SignatureWorkflowService`, which provides unified management of signature workflows, signer policies, and overrides for signature/verification processes.

- The new version introduces `SignatureService.setVerifyHandler`, enabling the configuration of a global verification handler. This handler is effective not only during manual verification by users but also in verification workflows triggered by JavaScript Actions.

### # Signature Workflow Customization

- The new `overrideSigningWorkflow` and `overrideVerifyWorkflow` APIs have been introduced, enabling developers to fully customize the signature and verification workflows.

### # Signer Display Policy

- The new `setSignerOverridePolicy` API has been introduced, allowing developers to customize the display logic for signer names.

### # UI Customization Capability

- Starting from version 11.0.0, developers can fully customize the UI for signing, verification, signature properties, and related features by implementing the `IViewerUI` API and its subinterfaces, including `ISignatureUI`, `ISignDocDialog`, `ISignVerifiedResultDialog`, and `ISignedSignaturePropertiesDialog`.

- Simply inject the implementation class of the custom UI when initializing the `PDFViewer`.

## # Migration Recommendations

### # Comparison of Old and New APIs

Old API | New API/Usage | Description
--- | --- | ---
`PDFUI.registerSignatureFlowHandler({sign:()=>Promise.resolve(...)})` | `SignatureWorkflowService.overrideSigningWorkflow` | Override the signature process
`PDFUI.registerSignatureFlowHandler({verify:()=>Promise.resolve(...)})` | `SignatureWorkflowService.overrideVerifyWorkflow` | Override the signature verification process
`PDFUI.registerSignatureFlowHandler({showVerificationInfo: ()=>Promise.resolve(...)})` | `ISignatureUI#getSignVerifiedResultDialog` | Customize signature verification result UI
`PDFUI.registerSignatureFlowHandler({showSignatureProperty: ()=>Promise.resolve(...)})` | `ISignatureUI#getSignVerifiedResultDialog` | Customize signed signature attributes result UI
`PDFUI.registerSignatureFlowHandler({getSigner: ()=>Promise.resolve(...)})` | `SignatureWorkflowService#setSignerOverridePolicy` | Override signer name (UI display only)
`PDFUI.setVerifyHandler` | `SignatureService.setVerifyHandler` | Customize verification process

### # Example of migrating code for customizing signature and verification processes

1. Customize signature process:

   Previous Version:

       pdfui.registerSignatureFlowHandler({
           sign: (field) => {
               // Return custom signature settings
           }
       })

   New Version:

       service.overrideSigningWorkflow(async (field) => {
           // Return custom signature settings
       });

2. 自定义验签流程：

   Previous Version:

       pdfui.registerSignatureFlowHandler({
           verify: (field) => {
               // Return verification result
           }
       })

   New Version:

       service.overrideVerifyWorkflow(async (signature) => {
           // Return verification result
       });

### # UI Custom API Migration Example

- Previous Version

      pdfui.registerSignatureFlowHandler({
          showVerificationInfo: field => {
              // Display verification information
          },
          showSignatureProperty: field => {
              // Display signature properties
          }
      })

- New Version

      class CustomSignatureUI implements ISignatureUI {
          async getSignDocumentDialog() {
              /* ... */
          }
          async getSignVerifiedResultDialog() {
              /* ... */
          }
          async getSignedPropertiesDialog() {
              /* ... */
          }
      }
      class CustomViewerUI extends PDFViewCtrl.TinyViewerUI {
          async getSignatureUI() {
              return new CustomSignatureUI();
          }
      }
      new PDFViewer({
          viewerUI: new CustomViewerUI(),
          // Other configurations...
      });

## # Notes

- The new API must be used with Foxit PDF SDK for Web version 11.0.0 or later.
- When customizing the UI, strictly implement the API definitions, paying attention to resource release and asynchronous processing.
- The legacy API has been marked as deprecated starting from version 11.0.0. It is recommended to migrate to the new API as soon as possible.

For detailed API descriptions and more examples, please refer to the relevant documentation:

- Legacy Signature API Documentation
- New Signature Workflow API Documentation
- Custom Signature UI Documentation