Skip to main content

Usage

Browser support​

The Signature SDK can be used in an HTML page by accessing the JavaScript controls. SigCaptX installs components that allow a signature-enabled web application to be used in a range of browsers.

The product has been tested with:

  • MS Edge
  • Chrome
  • Firefox

Firefox/Chrome installations​

The browsers must have been installed and run before installing SigCaptX. Additionally:

  Firefox 64-bit
    - With .EXE (combined) installer: no action necessary
    - With .MSI installer: must be run from command line with 'FF64=1'

  Firefox Portable
    - With .EXE (combined) installer:  
        - From command line (eg for silent install), add FFP="Firefox Portable Folder"
        - From UI, click 'Options' then enter or browse to "Firefox Portable Folder"
    - With .MSI installer:  must be run from command line with FFP="Firefox Portable Folder"

  Note that MSI log files are created in the folder %TEMP%

Samples​

The samples for the SigCaptX are hosted on GitHub:

SigCaptX method summary​

To access the Signature Library directly, calls are made indirectly via a localhost web server which is installed as an extension of the Signature Library. A JavaScript framework is provided to give access to the local web server. The JSONP communication technique is used as the interface to the local web server using HTTPS requests.

info

The general process is as follows:

  • The web browser loads an HTML page containing JavaScript application code from the web server. The application code includes the framework required to access the localhost web server.
  • To perform signature library functions, the application calls the localhost server via framework functions.
    • These functions make JSONP-HTTPS requests and provide a callback function.
    • The framework functions return immediately, leaving the server to run independently.
  • The server actions the framework function by calling the Signature Library DLL. For example, in the case of signature capture the DLL performs the necessary i/o with the signature tablet.
  • Once complete, the server triggers the callback via JSONP, passing the return data.
  • The callback function retrieves the data and completes the operation.
  • For example, in the case of signature capture:
    • The app calls the capture function.
    • Its callback calls renderBitmap to get the signature image.
    • That callback displays the image on the page.

To illustrate, an HTML page creates the signature image display area:

<div id="imageBox" class="boxed" style="height:35mm;width:60mm;border:1px solid #d3d3d3;">
</div>

JavaScript application code provides the necessary functionality. For example to capture a signature:

function Capture()
{
  // call the Signature Library function with a callback function name
  dynCapt.Capture(sigCtl, "who", "why", null, null, onDynCaptCapture);
  return;

  // the callback function runs when signature capture completes (OK or Cancel)
  function onDynCaptCapture(dynCaptV, SigObjV, status)
  {
    if(wgssSignatureSDK.DynamicCaptureResult.DynCaptOK != status)
      {
        print("Capture returned: " + status);
      }
      switch( status )
      {
        case wgssSignatureSDK.DynamicCaptureResult.DynCaptOK:
          sigObj = SigObjV;
          print("Signature captured successfully");
          var flags = wgssSignatureSDK.RBFlags.RenderOutputBase64 |
                      wgssSignatureSDK.RBFlags.RenderColor24BPP;
          var imageBox = document.getElementById("imageBox");
          sigObj.RenderBitmap("bmp", imageBox.clientWidth, imageBox.clientHeight, 0.7, 0x00000000, 0x00FFFFFF, flags, 0, 0, onRenderBitmap);
          break;
        case wgssSignatureSDK.DynamicCaptureResult.DynCaptCancel:
          print("Signature capture cancelled");
          break;
        default:
          print("Capture Error " + status);
          break;
      }
  }

  function onRenderBitmap(sigObjV, bmpObj, status)
  {
    if(wgssSignatureSDK.ResponseStatus.OK == status)
    {
      var imageBox = document.getElementById("imageBox");
      if(null == imageBox.firstChild)
      {
        imageBox.appendChild(bmpObj.image);
      }
      else
      {
        imageBox.replaceChild(bmpObj.image, imageBox.firstChild);
      }
    }
    else
    {
      print("Signature Render Bitmap error: " + status);
    }
  }
}

SigCaptX Image

Web server​

The web server contains four significant parts:

  • Web Service
  • Web Server
  • Root Certificate
  • Configuration

Web Service​

wgssSigCaptX_Service.exe is installed as a Windows Service and provides an arbitration service.

At startup it reads a configuration value and attaches to the specified localhost port.

By default the service is attached to https://localhost:8000

The web service function is to arbitrate between different instances of the web server: each user logged in to Windows runs a unique instance of the server.

  • The service tells a new server instance which port to attach to.
  • The service tells a new browser application which port the server is attached to.

Web Server​

wgssSigCaptX_Server.exe is the Server which performs the Signature SDK functionality. It is installed so that it starts automatically when a user logs in to Windows.

A new instance of the server is started when a user first logs in to Windows. On startup the server gets a port number from the web service and attaches to that port.

By default the first server is attached to https://localhost:8001

The next user’s server will attach to https://localhost:8002 and so on.

The server responds to HTTPS requests and carries out the requested function by calling the Signature SDK DLLs. Each function in the SDK framework has a corresponding function in the server to perform the operation. The server retains the Signature SDK data and uses references to allow the browser application to read and write data values.

On completion of a function call the server completes the HTTPS request which allows the browser application to resume.

Root Certificate​

During SigCaptX installation a unique self-signed root certificate is created and installed in the Windows Certificate Store. The certificate is used by the web server to provide the secure HTTPS access required for JSONP communication.

Following installation the certificate can be viewed in the Windows Certificate Manager as:

Unique Localhost Wacom Certificate Authority

Configuration​

During installation registry values are created in:

	[HKEY_LOCAL_MACHINE\SOFTWARE\Wacom\SigCaptX]

or for a 32-bit server on 64-bit Windows:

	[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Wacom\SigCaptX]

The values are generally reserved for internal use but the following value is used to define the web service start port:

 	start_port  REG_DWORD   0x00001f40 (8000)

If a web service port other than 8000 should be used it can be defined here.

If required, the upper limit of web server port allocation can also be changed from the default value:

	end_port    REG_DWORD   0x0000ffff (65535)

JavaScript SDK Framework​

Overview​

The JavaScript SDK framework is provided in the file signaturesdk.js.

A web application includes the framework script in the normal way:

    <script src="wgssSigCaptX.js"></script>

The framework provides:

  • Wacom Signature SDK functions
  • JSONP communication functions

The framework replicates the API of the Wacom Signature Library. API-equivalent Signature Library objects are created in the framework and control is passed to the web server through the use of JSONP communication. The same object methods and properties are available through the framework while the data is held in the web server. That is, the framework provides indirect access to the Signature Library.

The concept of JSONP communication can be illustrated with a simple example:

In a web page containing:

<script type="text/javascript">
function my_callback(data)
{
  window.alert("my_callback data: " + data.number);
}
</script>
<script src="scriptfile.js"></script>

The contents of scriptfile.js:

my_callback({"number": 10})

When the web page is opened in a browser the static file scriptfile.js is loaded and executed, resulting in a popup message displaying “my_callback data: 10”.

The SDK framework uses an extensive elaboration of this technique by requesting script from the local web server. The web server creates the script dynamically and is able to insert the return data and the callback function name supplied in the request.

API​

The SDK framework is accessed through its main class WacomGSS_SignatureSDK.

An application can create objects equivalent to those using the Signature SDK directly:

WacomGSS_SignatureSDK
SigCtl
DynamicCapture
SigObj
Hash
Key
WizCtl
InputObj

Refer to the Wacom Signature Components API for details of the object methods and properties.

Note that SigCtl is maintained for API compatibility. The SigCtl properties relate to its appearance as an ActiveX control and are not applicable to the framework implementation.

SDK Samples​

SigCaptX's samples can be accessed on our GitHub here.

PortCheck​

Use the PortCheck test page to verify the SigCaptX installation:

The samples can usually be copied to disk and opened in a browser, for example:

                file:///C:/SigCaptX-SDK-Samples/PortCheck.htm

Depending on security settings, this can raise a warning. Allow the blocked content to continue.

If no messages appear in the test page, the browser may not be prompting to allow scripts to run.

Security warnings can be avoided by hosting the samples on a secure site, as would be the case in a production system.

Use the PortCheck test page to verify the SigCaptX installation.

Web Service​

If the service is not running or is not accessible the following message appears:

  • Detecting SigCaptX
  • SigCaptX service not detected

Web Server​

If the web service is running but the server has not been started the following message appears:

  • Detecting SigCaptX
  • SigCaptX service detected, but not the server

Root certificate​

If the certificate has not been successfully installed the browser will display a warning similar to: Root Certificate

Signature Capture​

SigCaptX-Capture.html demonstrates basic signature capture. Press Start to sign on the signature tablet and display the signature:

Browser

Double-click the signature to display information stored in the signature (Name/Date/Reason).