This page describes the different viewer types, the integration of viewers and the creation of viewer urls.

There are two types of viewers:

envelope viewer: contains one or several documents and conditions
document viewer: contains a single document.

The viewers are integrated in the GUI (logged in user) or are opened with a time limited viewer link (integration see below). The link is either automatically created by websignature office and send per email or created with the tyrservice (see Time Limited Viewer URL creation).

Table of Contents

Time Limited Viewer URL creation

Time limited viewer URLs forward to the document or envelope viewer and valid till a defined timestamp. The link is specific for a document or envelope and a associated signer.

Key	Description
x	viewer name: tldv: time limited document viewer tlev: time limited envelope viewer
u	user_id: The user id of the signer
t	timestamp: unix timestamp till the link is valid
d/e	the id: e: envelope id for envelope viewer d: document id for document viewer
locale	optional: language of the viewer. "de" or "en". If not present, german viewer will be used.

There are two formats for the time limited viewer:

viewer url with the parameters and an encrypted signature parameter "xx"
viewer url with all parameters encrypted in parameter "xen"

URL with urlSignature

The viewer link with url signature is deprecated. It contains the parameters "x", "u", "t", "d"/"e" and "xx".

time limited document viewer: https://host.com/process?x=tldv&u=2&t=1710370800000&d=1000&xx=piQA-jwlzblZaNWrsWnQshbAha8O_3AEkfeyyg
time limited envelope viewer: https://host.com/process?x=tldv&u=2&t=1710370800000&e=1000&xx=piQA-jwlzblZaNWrsWnQshbAha8O_3AEkfeyyg

The url signature ("xx") is created with the tyrservice method getUrlSignature:

Expand

title	TyrService getUrlSignature requests

Code Block

title	time limited document viewer: getUrlSignature request

<?xml version="1.0" encoding="UTF-8"?><methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <methodName>tyrservice.getUrlSignature</methodName>
  <params>
    <!-- sessionId -->
    <param>
      <value>ABCD:1234:KLLK</value>
    </param>
    <!-- viewer type: time limited document viewer -->
    <param>
      <value>tldv</value>
    </param>
    <param>
      <value>
        <struct>
          <!-- timestamp -->
          <member>
            <name>t</name>
            <value>1702039766378</value>
          </member>
          <!-- document id  -->
          <member>
            <name>d</name>
            <value>1000</value>
          </member>
          <!-- user id -->
          <member>
            <name>u</name>
            <value>2</value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

Code Block

title	time limited envelope viewer: getUrlSignature request

<?xml version="1.0" encoding="UTF-8"?><methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <methodName>tyrservice.getUrlSignature</methodName>
  <params>
    <!-- sessionId -->
    <param>
      <value>ABCD:1234:KLLK</value>
    </param>
    <!-- viewer type: time limited envelope viewer -->
    <param>
      <value>tlev</value>
    </param>
    <param>
      <value>
        <struct>
          <!-- timestamp -->
          <member>
            <name>t</name>
            <value>1702039766378</value>
          </member>
          <!-- document id  -->
          <member>
            <name>e</name>
            <value>1000</value>
          </member>
          <!-- user id -->
          <member>
            <name>u</name>
            <value>2</value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

Code Block

title	getUrlSignature response

<?xml version="1.0" encoding="UTF-8"?><methodResponse xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <params>
	<!-- URL signature -->
    <param>
      <value>piQA-jwlzblZaNWrsWnQshbAha8O_3AEkfeyyg</value>
    </param>
  </params>
</methodResponse>

URL with encrypted parameters

Using URLs with encrypted parameters is the preffered and safer method. The values ("x", "u", "t", "d"/"e") are encrypted with the tyrservice method getEncryptedParameters. The URL only contains the parameter "xen" (and optional parameters):

Time limited document or envelope viewer:

https://host.com/process?xen=yJtSth3pkHcE...

Expand

title	TyrService getEncryptedParameters requests

The request payload is identical to the payload of getUrlSignature:

Code Block

title	time limited document viewer: getEncryptedParameters request

<?xml version="1.0" encoding="UTF-8"?><methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <methodName>tyrservice.getEncryptedParameters</methodName>
  <params>
    <!-- sessionId -->
    <param>
      <value>ABCD:1234:KLLK</value>
    </param>
    <!-- viewer type: time limited document viewer -->
    <param>
      <value>tldv</value>
    </param>
    <param>
      <value>
        <struct>
          <!-- timestamp -->
          <member>
            <name>t</name>
            <value>1702039766378</value>
          </member>
          <!-- document id  -->
          <member>
            <name>d</name>
            <value>1000</value>
          </member>
          <!-- user id -->
          <member>
            <name>u</name>
            <value>2</value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

Code Block

title	time limited envelope viewer: getUrlSignature request

<?xml version="1.0" encoding="UTF-8"?><methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <methodName>tyrservice.getEncryptedParameters</methodName>
  <params>
    <!-- sessionId -->
    <param>
      <value>ABCD:1234:KLLK</value>
    </param>
    <!-- viewer type: time limited envelope viewer -->
    <param>
      <value>tlev</value>
    </param>
    <param>
      <value>
        <struct>
          <!-- timestamp -->
          <member>
            <name>t</name>
            <value>1702039766378</value>
          </member>
          <!-- document id  -->
          <member>
            <name>e</name>
            <value>1000</value>
          </member>
          <!-- user id -->
          <member>
            <name>u</name>
            <value>2</value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

Code Block

title	getUrlSignature response

<?xml version="1.0" encoding="UTF-8"?><methodResponse xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
  <params>
	<!-- encrypted parameters "xen" -->
    <param>
      <value>yJtSth3pkHcE...</value>
    </param>
  </params>
</methodResponse>

Integration

If you want to integrate the webSignatureOffice viewer / document URL into your existing web application (browser), there are basically two options available:
a) Display of the document viewer in a separate browser tab.
b) Display of the document viewer within your own browser page, integrated via iFrame (see example below)

...

Code Block

language	xml
title	iFrame Test

<!DOCTYPE html>
<html>

	<head>
				 
		<meta charset="utf-8">
				
		<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
	
		<title>Viewer iFrame Test</title>

		<!-- JS -->
		<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
		<script>
			jQuery(document).ready(function(urlFromBackend) 
			{
				// URL from Backend
				var url = urlFromBackend; //Response from Tyrservice method calls; example URL = https://host.com/process?x=tldv&u=1&t=1234&d=1234&xx=abcxen=yJtSth3pkHcE...
	        jQuery('.iframe iframe').attr('src', url);
			});
		</script>

		<!-- CSS -->
		<style>
			body
			{
				font-family: arial !important;
				font-size: 16px;
				line-height: 22px;
			}

			header
			{
				padding:15px;

				background-color: #23406b;
				color: #fff;
			}

			header .logo
			{
				display: inline-block;
				vertical-align: middle;
			}

			header nav
			{
				display: inline-block;
				vertical-align: middle;

				margin-left: 50px;
			}

			header nav a
			{
				margin-left: 10px;
				color: #fff;
			}
			header nav a:hover
			{
				opacity: 0.7;
			}

			footer
			{
				padding:10px;

				background-color: #23406b;
				color: #fff;
			}


			/* example for iframe styling */
			iframe
			{
				width: 100%;
				height:calc(100vh - 250px);
			}
		</style>
		
	</head>

	<body>
		<header>
			<div class="logo">Logo</div>
			<nav>
				<a href="#">Menu 1</a>
				<a href="#">Menu 2</a>
				<a href="#">Menu 3</a>
				<a href="#">Menu 4</a>
			</nav>
		</header>

		<main>
			<div class="intro">
				<h1>Beispielhafte Anbindung webSignatureOffice Viewer</h1>
			</div>

			<!-- iFrame start -->
			<div class="iframe">
				<iframe src="" name="iFrame" title="iFrame" allowfullscreen></iframe>
			</div>
			<!-- iFrame end -->
		</main>

		<footer><p>Footer</p></footer>
		
	</body>
</html>

Webhooks

The viewer posts messages to the parent when the user finished his signatures or clicks buttons:

event	post message
click "finish" or "save and quit" ("X")	viewerExit
finish all own signatures in a document/envelope (signatures of other users are left, the status is "waiting")	finishedOwnSignatures
all signatures of all users are finished in document/envelope	finishedSigning

Versions Compared

Old Version 2

New Version 3

Key

Time Limited Viewer URL creation

URL with urlSignature

URL with encrypted parameters

Integration

Webhooks

Page Comparison

Versions Compared

Old Version 2

New Version 3

Key

Time Limited Viewer URL creation

URL with urlSignature

URL with encrypted parameters

Integration

Webhooks