Once you start a transaction and actions are ready to be processed, participants are redirected to our signature page.
For a smoother signature process, you can embed our signature page into your website using an iframe. To do so, follow the steps below.
Note that the instant messaging feature is not available in the iframe. For more details about this feature, visit Chat with a participant.
Important: You must authorize the iframe domain before you can integrate it into your website.
1. Set up the iframe
Inject or call the embed.js script in your website
We provide you with a script that generates our signature page. Depending on the environment you use, inject or call one of the following embed.js scripts.
- PREPROD environment: https://apps.alpha.universign.com/npds/embed.js
<script src="https://apps.alpha.universign.com/npds/embed.js"></script>
- PROD environment: https://apps.universign.com/npds/embed.js
<script src="https://apps.universign.com/npds/embed.js"></script>
Provide a DOM element
Create a div tag with id, width and height, as in the example below.
<div id="container-iframe" style="width: 70%; height: 600px"></div>
The div element height should not be a percentage value as the height of the iframe is in percentage (100%). If the div element of the iframe doesn’t have a fixed height, the height of the iframe will be a smaller value.
We recommend you to have a height value smaller than window.innerHeight.
For advanced signatures that require identity documents verification, if the iframe height is less than 725px, a scroll will appear for identity document loading steps.
If the iframe width is less than 768px, navigation is reduced, and steps descriptions are not displayed.
Call the initIframe function
To display the signature page in the iframe, call the initIframe function with required parameters (The DOM element id and the signature page full URL), as in the example below.
<body onload="initIframe('container-iframe', 'https://apps.universign.com/npds/act_8JW4Dl1L5Kkzk')"></body>
Note that you need to retrieve the signature page full URL (including the participant action ID) from the transaction object, as in the code example below.
"actions" : [ {
"id" : "act_8JW4Dl1L5Kkzk",
"actor" : "[email protected]",
"state" : "open",
"url" : "https://apps.universign.com/npds/act_8JW4Dl1L5Kkzk",
"tasks" : [ {
"type" : "signature",
"state" : "todo",
"field" : "fld_QzBQ"
} ],
"stalled" : false
} ]
2. Listen to events
The embedded iframe communicates with your website via events. This allows you to launch the appropriate workflows depending on participants actions.
The list of events is as follows:
Transaction events
actionpage.opened: the signature page is accessed and the participant started the signature process.action.refused: the participant refused to perform his/her action.action.closed: the participant performed his/her action.transaction.lifecycle.completed: all participants have performed their actions and the transaction is completed.
Registration events
registration.lifecycle.open: The participant can start the certificate creation journey.registration.lifecycle.in_progress: The participant is still performing actions requested in the certification creation journey.registration.lifecycle.rejected: The participant has rejected the validated identity.registration.lifecycle.error: The participant’s registration session has expired.registration.lifecycle.success: The participant’s certificate has been issued successfully.
Note that the above mentioned events are specific to the iframe integration.
You need to inject the following script in your website, to be able to follow events.
<script>
window.addEventListener('npdsEvent', function(event) {
console.log(event.detail.eventType, event.detail.actionId);
}, false);
</script>
Closing the iframe and redirecting
Once the signing journey is complete, your application decides what happens next: closing the iframe, showing a confirmation message, or redirecting to another page. We don’t enforce any particular behavior — you keep full control over your users’ experience, by hooking your own logic into the action.closed and transaction.lifecycle.completed events described above (depending on whether you want to react as soon as one participant is done, or wait until every participant has completed the journey).
In the example below, ‘npdsEvent’ refers to the event you want to listen to.
<script>
window.addEventListener('npdsEvent', function(event) {
if (event.detail.eventType === 'action.closed') {
document.getElementById('container-iframe').style.display = 'none';
window.location.href = 'https://your-website.example.com/thank-you';
}
}, false);
</script>
Good to know — Client-side events vs. webhooks
Client-side events are useful for driving the interface in real time, but they should not be treated as the source of truth for your business actions (database updates, workflow triggers, contractual validation). A user can close their browser before the event is received.
For critical actions, always rely on our webhooks: they notify you server-side on every status change, reliably and independently of browser behavior (tab closed, connection lost, etc.). See the full webhooks reference for the list of events and their format.
3. Full code example
Below is an example of a full iframe integration within a single web page.
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Universign signature page iframe integration</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://apps.universign.com/npds/embed.js"></script>
<script>
window.addEventListener('npdsEvent', function(event) {
console.log(event.detail.eventType, event.detail.actionId);
}, false);
</script>
</head>
<body onload="initIframe('container-iframe', 'https://apps.universign.com/npds/act_8JW4Dl1L5Kkzk')">
<div style="display:flex; justify-content:space-between; align-items:stretch; height:56vh;">
<div id="container-iframe" style="width: 70%; height: 600px">
</div>
</div>
</body>
</html>
Note that by default, the access to the signature page is protected with an OTP (even through the iframe integration). However, you may need to disable this access control. For more details, visit Disable signature page access control .
Iframe display
Once your integration done, the signature page will display in an iframe integrated to your own website.
