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).

1 Time Limited Viewer URL
2 TyrService URL creation
3 Integration
- 3.1 iFrame Test
4 Webhooks

Time Limited Viewer URL

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 an associated signer. To build the link via tyrservice, admin priviliges are required.

Key	Description

Key	Description
x	viewer type: 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"

TyrService URL creation

The Time Limited Viewer URL can be retrieved with the method getTimeLimitedViewerUrl of the extended TyrService.

In the request following parameters of the viewer URL must be provided:

viewerType (tlev/tldv)
timestamp
id
locale
loginOrEmail (optional)

The Method returns the URL with encrypted parameters (see below).

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

If the method is called without loginOrEmail, the URL is created for the own user.

If loginOrEmail is provided, admin privileges are necessary.

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...

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=tlev&u=2&t=1710370800000&e=1000&xx=piQA-jwlzblZaNWrsWnQshbAha8O_3AEkfeyyg

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

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)

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?xen=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 sends messages to the parent window (in the case of an IFrame implementation) or to the parent opener (for a popup implementation) when the user completes their signatures or interacts with specific buttons:

event	post message

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