d) Viewer Integration
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 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.
getTimeLimitedViewerUrl request
<?xml version="1.0" encoding="UTF-8"?>
<methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
<methodName>tyrservice.getTimeLimitedViewerUrl</methodName>
<params>
<param>
<!-- session id -->
<value>XXXX-YYYY-ZZZZ</value>
</param>
<param>
<!-- viewer type: time limited document viewer (tldv) or time limited envelope viewer (tlev) -->
<value>tlev</value>
</param>
<param>
<!-- document or envelope id -->
<value>
<i4>82610</i4>
</value>
</param>
<param>
<!-- unix timestamp -->
<value>1765190385000</value>
</param>
<param>
<!-- locale -->
<value>de</value>
</param>
<param>
<!-- optional: user login -->
<value>user1</value>
</param>
</params>
</methodCall>
getTimeLimitedViewerUrl response
<?xml version="1.0" encoding="UTF-8"?>
<methodResponse xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
<params>
<param>
<value>
https://host.com/process?xen=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)
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>
Viewer-URL and Creation-URL
To sign envelopes as a logged in user in the websignatureOffice GUI, the Viewer-URL is used. To create an envelope the Creation-URL is used:
creation URL: https://host.com/login/#/create-envelope?id=foo
viewer URL: https://host.com/login/#/viewer?type=envelope&id=foo
To open the URL, the user must log in. The URL is not user specific.
TyrService Creation: Envelope URL Methods
The TyrService provides three methods for generating envelope URLs:
getEnvelopeUrl(String sessionId, Integer envelopeId)Returns the creation URL if the envelope's status is Draft. Otherwise, it returns the envelope viewer URL.getViewerUrl(String sessionId, Integer envelopeId)Returns the viewer URL for the envelope, regardless of its current status.getCreationUrl(String sessionId, Integer envelopeId)Returns the creation URL for the envelope, regardless of its current status.
The first method, getEnvelopeUrl, returns a status-specific URL, which guarantees that the URL can be opened successfully by the client.
In contrast, the other two methods (getViewerUrl and getCreationUrl) return the requested creation or viewer URL even if the envelope's current status is inappropriate for that action. If the status differs, these URLs will lead to an error when accessed.
getEnvelopeUrl request
<?xml version="1.0" encoding="UTF-8"?>
<methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
<methodName>tyrservice.getEnvelopeUrl</methodName>
<params>
<param>
<!-- session id -->
<value>XXXX-YYYY-ZZZZ</value>
</param>
<param>
<!-- envelope id -->
<value>
<i4>1191</i4>
</value>
</param>
</params>
</methodCall>getEnvelopeUrl response
<?xml version="1.0" encoding="UTF-8"?>
<methodResponse xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
<params>
<!-- status draft returns creation url -->
<!-- <param>
<value>
https://refactor.webso.stepover.de/#/create-envelope?type=envelope&id=xyz</value>
</param> -->
<!-- other status returns viewer url -->
<param>
<value>
https://host.com/app/login/#/viewer?type=envelope&id=xyz
</value>
</param>
</params>
</methodResponse>getCreationUrl request
<?xml version="1.0" encoding="UTF-8"?>
<methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
<methodName>tyrservice.getCreationUrl</methodName>
<params>
<param>
<value>XXX-YYY-ZZZ</value>
</param>
<param>
<value>
<i4>1228</i4>
</value>
</param>
</params>
</methodCall>getViewerUrl request
<?xml version="1.0" encoding="UTF-8"?>
<methodCall xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
<methodName>tyrservice.getViewerUrl</methodName>
<params>
<param>
<value>XXX-YYY-ZZZ</value>
</param>
<param>
<value>
<i4>1228</i4>
</value>
</param>
</params>
</methodCall>
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 |