Getting started

Complete Installation, including the application requirements, before initializing the viewer. For release 2026.1.2, the shared iOS SDK installation guide covers the registry package setup.

Getting started

The WYSIWYS SDK has to be initialized prior using any provided method.

self.wysController = [[WYSIWYSController alloc] initWithConfiguration:[self configurationWithUsername:username]];
-(WYSPdfViewerConfiguration*) configurationWithUsername:(NSString *)username{
    WYSPdfViewerConfiguration* configuration = [WYSPdfViewerConfiguration new];
    configuration.username = username;
    configuration.storageKey = [@"your key" dataUsingEncoding:NSUTF8StringEncoding];
    configuration.license = @"The license";
    return configuration;
}

• The license is a licence key provided by Sysmosoft for a unique package name.
• The storageKey is a 64 bytes long key that will be used to encrypt data on the device. This key must not be stored in an unsecured storage or hardcoded in the app. It might be derived from a user's input, or securely stored using iOS keychain.
• The username represents the user that will sign document. It is used to retrieve a signature field dedicated to the user.

Opening a document

NSError* error = nil;
WYSPDFViewer* pdfViewer = [wysController openDocument:pdf documentID:documentId viewerConfiguration:self.viewerConfiguration signatureConfiguration:self.signatureConfiguration error:&error]
self.extendedLayoutIncludesOpaqueBars = YES;
    [self addChildViewController:self.pdfViewer];
    self.pdfViewer.view.frame = CGRectMake(0, 0, self.pdfContainer.bounds.size.width, self.pdfContainer.bounds.size.height);
    self.pdfViewer.view.autoresizingMask = (UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight);
    [self.pdfContainer addSubview:self.pdfViewer.view];
    [self.pdfViewer didMoveToParentViewController:self];

When opening a document, the following arguments must be provided :

• A pdf as byte array.
• A documentId that is identifying the document.
• The WYSViewerConfiguration signatureConfiguration :
  • The viewerDelegate is a delegate of type WYSViewerDelegate to listen events emitted by the document reader
  • continuousScrolling a boolean to set the scrolling mode page per page or continuous (default: page per page)
  • verticalScrolling a boolean to set the scrolling direction to horizontal or vertical (default: horizontal)
  • The backgroundColor is the background color behind the page view.
• The WYSSignatureConfiguration signatureConfiguration :
  • The signatureProcessDelegate is a delegate of type WYSSignatureProcessDelegate to listen events emitted by the SDK to follow the signing process
  • The WYSSignatureAppearance to setup the visual appearance of the digital signature (see Customizing visual signatures)
  • The WYSWatermarkAppearance to setup the visual appearance of the watermark printed in case of refusal (see Customizing watermark)
  • The WYSSignatureAttributes to setup the signature attributes that will be embedded along with the signature (only for PDF) (see Customizing digital signature attributes)
  • The WYSSignatureAppearanceCreation introduces a mechanism to customize the signature appearance. This allows for a flexible approach to render visual signature, for various implementation strategies. This feature offers developers an option to enhance signature personalization and integration with existing systems.

The document will be loaded asynchronously in the view and the event WYSPdfViewerDelegate#documentDidLoad is sent once the document is displayed.

Form documents with standard inputs can be edited directly by the user and all its modifications are automatically saved.

Reopening a document

The user has many reasons to be interrupted while editing a document. After being opened, a document remains in progress and all modifications are automatically saved in an secured internal storage.

It's possible to know if a document is in progress using the method below :

[wysController documentInProgress:documentId];

It's possible to reopen the document using the WYSIWYSController#reopenDocument method that takes the same arguments except the pdf that is not needed.

WYSPDFViewer* pdfViewer = [wysController reopenDocument:documentId viewerConfiguration:self.viewerConfiguration signatureConfiguration:self.signatureConfiguration error:&error];

The document will be loaded asynchronously in the view and the event WYSPdfViewerDelegate#documentDidLoad is sent once the document is displayed.

Customizing visual signatures

The configuration class WYSSignatureAppearance offers different possibilities to customize the visual signature :

• handwrittenSignatureEnabled : Enable handwritten signature. When enabled, the user will have to draw its signature or pick one if multiple are available.
• signerName : The text to be shown as visual signature if the handwrittenSignatureEnabled is disabled
• signerNameFont : The font to use to draw the visual signature (default : [UIFont boldSystemFontOfSize:48])
• dateTimePattern : The pattern to use to format the signature date (default: yyyy-MM-dd HH:mm)
• dateFont : The font to use to draw the signature date (default : [UIFont systemFontOfSize:28])
• signatureDescription : An optional description to be displayed in the signature field.
• signatureDescriptionFont : The font to use to draw the signature description (default : [UIFont boldSystemFontOfSize:28])
• signatureGraphic : The graphic that will be displayed in the bottom of the signature (default : nil, preferred width if using default font size: 512px)
• invisibleSignature : The digital signature will be applied on a new invisible signature field (default : NO)

Customizing watermark

The configuration class WYSWatermarkAppearance offers different possibilities to customize the visual appearance of the watermark :

• title : Set the short title that will be displayed as watermark on refused document
• titleFont : The font to use to draw the watermark (default : [UIFont systemFontOfSize:80])
• dateTimePattern : The pattern to use to format the watermark date (default: yyyy-MM-dd HH:mm:ss)
• dateFont : The font to use to draw the watermark (default : [UIFont systemFontOfSize:25])
• rotation : The rotation in degrees of the watermark (default 0)

Customizing digital signature attributes

The configuration class WYSSignatureAttributes offers different possibilities to customize the attributes of the digital signature :

• signatureName : Set the name attribute of the signature. It is sometimes displayed in the signature details of some PDF Viewer, but usually only the CN of the certificate is displayed. Default : The username provided in PdfViewerConfiguration#username.
• signatureLocation : Set the location attribute of the signature.
• signatureReason : Set the reason attribute of the signature. Default : accepted or refused, depending the user's decision.
• estimatedSignatureSize : Set the estimated size of the digital signature in bytes. It must not be lower than the actual signature size. Default : 32768 (32KB)

Showing a document (read only)

This method can be used to simply display a document as it is. No signature process will be enabled. The signatureProcessDelegate is therefore not required and any attempt to call an other method (like acceptDocument or refuseDocument) on the controller will crash the application.

NSError* error = nil;
self.pdfViewer = [wysController showDocument:pdf viewerConfiguration:self.viewerConfiguration error:&error];

When showing a document, the following arguments must be provided :

• A pdf as byte array.
• The WYSViewerConfiguration signatureConfiguration :
  • The viewerDelegate is a delegate of type WYSViewerDelegate to listen events emitted by the document reader
  • continuousScrolling a boolean to set the scrolling mode page per page or continious (default: page per page)
  • verticalScrolling a boolean to set the scrolling direction to horizontal or vertical (default: horizontal)

Unlike open and reopen method, the document will be stored securely (to avoid big document in memory) as long as a reference on the viewer is kept. When the viewer returned by this method is destroyed (by the app or the OS), the file is erased as well.

Retrieving document info

When a document is loaded, the following information are available:

• Page count : Retrieves the number of pages in the document with the API WYSIWYSController#pageCount
• Page index : Retrieves the current page index of the document with the API WYSIWYSController#pageIndex

When the user is scrolling to another page, the application can be informed by implementing the delegate method WYSViewerDelegate#didPageChanged:(int)

Accepting / Refusing a document

Once a document is opened. It can be either accepted or refused.

[wysController acceptDocument];
[wysController refuseDocument];

When accepting a document, the signature flow might differ depending the document to be signed (see previous section).

When refusing a document, a watermark will be applied on each page and the document will be signed with an invisible signature. Signing refused documents might not be needed depending the use case of the app.

In both case, the document is saved before preparing it for digital signature.

Signature positioning

After accepting the document, the visual signature will be created according to the signature appearance configuration. The event WYSSignatureProcessDelegate#signatureRequiresPositioning is emitted. In the meantime, the visual signature will be displayed allowing the user to position and resize it.

The app must call the following method to finish the positioning process :

[wysController signaturePositionned];

or the following method to cancel it:

[wysController cancelSignaturePositioning];

Final confirmation

Before processing the effective digital signature, the user has to confirm the signature of the updated document. A preview of the document will be shown to the user and the event WYSPdfViewerDelegate#onConfirmationRequired is emitted.

The app must call the following method to confirm the signature :

[wysController confirmSignature];

The preview will not be displayed for document that are not visually modified during signature (document without empty signature field).

The event WYSPdfViewerDelegate#willPrepareDocument is emitted when starting to prepare the document, allowing the app to display a loading indicator.

Once the document is prepared for signature, the event WYSPdfViewerDelegate#documentPreparedForSignature:(NSData*) documentDigest withReason:(NSString*)reason is emitted.

The documentDigest received must be signed and then inserted into a PKCS#7 detached signature. This signature can be generated client-side or using a remote signature API.

[wysController embedSignature:pkcs7];

• The signature is a valid PKCS#7 detached signature, generated for the given documentDigest

The SDK provides also a method to embed the signature without the need to have a PdfViewer displayed. It allows the application to embed the signature from a background task or from a different view.

[WYSIWYSController embedSignature:documentId signatureConfiguration:signatureConfiguration signature:signature];

The last event WYSSignatureProcessDelegate#processDidFinishWithReason:(NSString*)reason andDocument:(NSData*)document is then emitted and the signed file is given as parameter. If something went wrong, WYSPdfViewerDelegate#processDidFailWithError:(nonnull NSError*) error is then emitted with the error in parameter.

When a document is not going to be reopened anymore, the app must explicitly dispose the document.

[WYSIWYSController disposeDocument:documentId];

Saving a document

It's possible to force the saving of the document by calling the method WYSIWYSController#saveDocument. This method must be called if you want to keep any modification done on the document.

Saving a document is only possible when the user is modifying it. After the call of one of the following method:

[wysController acceptDocument];
[wysController refuseDocument];

calling WYSIWYSController#saveDocument will have no effect.

Documents with required fields

The SDK verifies that a document containing required fields is completed before being accepted.

If the document is accepted using the WYSIWYSController#acceptDocument method but a required field is empty, the event WYSPdfViewerDelegate#missingRequiredFormField is emitted and the document must be accepted again once all the required fields are filled.

Documents with multiple signature fields

If a document contains multiple empty signature fields, the SDK lets the user decide which field is the most appropriate for him.

When this situation occurs, the event WYSPdfViewerDelegate#selectSignatureFormField is emitted directly after calling WYSIWYSController#acceptDocument. The viewer will scroll the document to the first available signature field and enable the field selection.

The app is responsible to notify the user that he has to click on a signature field.

Once selected, the app is notified with the WYSPdfViewerDelegate#didSelectSignatureFormField event and the process continues as if a single field was present.

Managing handwritten signatures

If WYSSignatureAppearance#handwrittenSignatureEnabled is set to YES, handwritten signatures applied in a signature field are automatically handled by the SDK :

• When there is no signature in the storage, the user is prompted to draw its signature
• When there is a single signature in the storage, it is automatically applied in the storage
• When there are multiple signatures in the storage, the user is prompted to select a signature.

In order to let the possibility to the user to add a second signature or to manage its existing signatures, a signature settings view can be opened.

UITableViewController* signatureVC = [WYSIWYSController openSignatureSettings];
[self.navigationController pushViewController:signatureVC animated:YES];