d) Integration Document and Envelope Viewer
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).
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 |
|---|---|
x | viewer type:
|
u | user_id: The user id of the signer |
t | timestamp: unix timestamp till the link is valid |
d/e | the id:
|
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 |
|---|---|
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 |