2. How to start
- Andy Erd
The Signature Device-API is the direct interface for communication with all StepOver signature pads. The Device-API offers all functions required to access the signature acquisition devices, record the signature and control the signature pad display. The API can be used either via DLL or OCX. The Device-API doesn´t require a license, when using StepOver signature pads. You will only need the 6. StepOver XML Certificate or when trying to communicate with the device, you will get a warning, that an uncertified application is trying to access the signature pad. The certificate is free and can be requested by mail. Read more about the certificate here.
Configuring the signature device
Before you can use your signature device, you need to configure it. The selected device is stored in the Padsettings variable, which can also be saved to the registry for long time usage. There are several functions for the configuration of the signature pad available.
| Function Name | Information |
|---|---|
| checkConnectedPad | Allows you to check, if a specific pad is connected and to configure a new signature device. |
| configurePad | Allows you to configure a signature device. |
| EnumeratePadsFirst | Function to enumerate the first signature device. Enumerate more with the next function. |
| EnumeratePadsNext | Function to enumerate the next device. These enumerate functions can be used to get an overview of all connected devices. |
| GetRegistryPadSettings | Returns the signature pad, which is currently saved in the registry. |
| isPadavAvailable | Obsolete function to check if a specific device is connected. |
| setPadSettings | Function to configure the signature pad with the Padsettings string. This function can be used with the Enumerate function to select the device without a visible SearchDialog |
Setting Driver Options
The Device-API has different functions to set options for the signing process or to change the settings of the signature pad.
| Function Name | Information |
|---|---|
| SetDriverLong | Allows to set different options of the Device-API and the signature pad (for example the device rotation settings). |
| SetDriverString | Allows to change the behavior of the Device-API. |
| SetLcdButtonOptions | Function to set the button configuration of the colour devices. |
Showing information on the signature pad
The signature pads allow to change the background image for the signature mode. If you want to show text information in the signature mode, you need to generate an image with the text and upload it before you start the signing mode. For the black/white devices you need a b/w image with 1 bit color depth. For devices with colour display you need a 16 bit image. For all pads (except for the Colour) the size of the image needs to be the same as the size of the device display, which can be retrieved with GetDriverLong (20 and 21).
| Function Name | Information |
|---|---|
| LCDImageEx, LCDImageExR | Functions to upload the background images to colour devices for the signature mode and for document viewing. |
| SetSignImage, SetSignImageEx | Function to upload the background image for the signature mode of B/W devices. |
| CreateSignatureRectangle | Function to limit the signing area on the device display (to prevent the signer from using the whole screen as input area). |
| UploadPromoImage | Function to upload promo screens to the devices (only for devices with colour display). |
The colour devices also have a Document Viewing Mode, which allows showing the document on the device while signing. The document viewing is usually handled by the SignatureAPI function /wiki/spaces/SignAPI4/pages/81395746, but it´s possible to do the same with the Device-API directly. Therefor you need to provide the document pages with LCDImageExR and react to a button click (changing the document page or zooming in/out) with sending the next page to the device.
Start Signature Mode
To collect a signature the devices needs to be set to signature mode, which changes the screen of the device and switches the LED from orange to green. Because of the internal device encryption of the biometric data, the image update of the Device-API is like a thumb cinema. The ActiveX Interface of the OCX allows you to show the signature image very easily. If you don't want to use the ActiveX component, you can collect the preview image of the signature by yourself to show it in your application.
| Function Name | Information |
|---|---|
| ReadPreviewImage | function to collect the preview image for the live signature (in case ActiveX component is not used) |
| startCapture | function to start the signature mode which allows you to sign on the device |
Stop Signing and Save Signature Data
To stop signing with the signature pad, you need to switch back to the IdleMode of the device. But before you do this, you should stop drawing on the device and collect the signature data. Drawing is disabled with setDriverLong(48) after which you can collect the final signature image. In case you want to collect the encrypted biodata, too, you also need to collect the EncryptedAESKey, because without this EncryptedAESKey, it´s not possible to decrypt the collected biodata. Finally you can use StopRead to end the SignatureMode and go back to the IdleMode.
| Function Name | Information |
|---|---|
| ReadHighResBitmap | Function, which returns the final signature image as stream/array. |
| ReadHighResBitmapBase64 | Function, which returns the final signature image in BASE64 format. |
| savePic | Function to save the signature image as file. |
| getBiodataString | Function to collect the encrypted biodata. |
| stopCapture | Function to stop the signmode. You can define, if the pad should switch into idle mode or if it should stay in the current mode (This allows to do multible signatures without having the promo screens in between). |
| StopRead | Function to stop the signmode and to switch to the IdleMode (showing the promo screens). |