iFrame
iFrame SDK API reference
Version 1.6.0
Load the script below in your page to use our SDK.
<script src="https://cdn.yousign.tech/iframe-sdk-1.6.0.min.js" integrity="sha384-/7MD1voOOzWVz7FmgeMwmmd1DO85Mo0PkkxdYd9j2wDGzGDGRG/phgnL0c9Xyy52" crossorigin="anonymous"></script>
<script src="https://cdn.yousign.tech/iframe-sdk-1.6.0.js" integrity="sha384-R+s/yjLK/cbrNa3CN+AZ62oJ0C2aGzcSsGYpTnX/SI89pmrEGlAWUCdzkR2RuVR6" crossorigin="anonymous"></script>
Or you can download the source file and load the script manually on your page :
Download the compressed SDK (v1.6.0)
Download the uncompressed SDK (v1.6.0)
Initialization
To initialize the SDK, you need to instantiate a Yousign
class with the following parameters
Parameter name | Type | Description |
---|---|---|
signatureLink | string | The URL of the signature request. |
iframeContainerId | string | The id attribute of the element where the iframe is initialized. |
isSandbox (optional) | boolean | To set if you want to test your integration with sandbox environment. |
iframeAttributes (optional) | object | To set some attributes on the iframe tag. You can set only the referrerpolicy attribute. |
const yousign = new Yousign({
signatureLink: 'signature_link',
iframeContainerId: 'iframe-container',
isSandbox: false,
iframeAttributes: {
referrerPolicy: 'origin-when-cross-origin'
},
});
IframeAttributes parameters
Parameter name | Type | Description |
---|---|---|
referrerPolicy | string | Specifies which referrer information to send when fetching the iframe. |
Event handlers
Along the Signer Flow, we send events that can be caught in the parent of the iframe.
Here are the events which can be listened :
started
: Signer opened the Signature Flowsuccess
: Signer has signed successfully the documenterror
: Signer has encountered an error when signingping
: (healthcheck, for debug only) Signature Request is loaded (event sent every 5 seconds)declined
: When signer declined the signaturesignature.done
: When signature is completed (all signers have signed the Signature Request)
This is the good moment if you want to download the complete document with all signatures.
Each method takes a callback function as a parameter which is triggered when the corresponding event is caught.
Method name | Description |
---|---|
onStarted() | A function that is triggered when the signature is opened. |
onSuccess() | A function that is triggered when the signer has successfully signed the document. |
onError() | A function that is triggered when the signature encountered an error when signing. |
onPing() | A function that is triggered every 5 seconds to inform the signature request is loaded. |
onDeclined() | A function that is triggered when the signer declined the signature. |
onSignatureDone() | A function that is triggered when the Signature Request is completed (all signers have signed the Signature Request). |
yousign.onStarted((data) => {
console.log("Signer has opened the signature");
console.log(data);
});
yousign.onSuccess((data) => {
console.log("Signer has successfully signed the document");
console.log(data);
});
yousign.onError((data) => {
console.log("Signer encountered an error when signing");
console.log(data);
});
yousign.onPing((data) => {
console.log("Ping - The signature request is loaded");
console.log(data);
});
yousign.onDeclined((data) => {
console.log("Declined - The signer declined the signature");
console.log(data);
});
yousign.onSignatureDone((data)=> {
//You can download the document with all signatures in it
console.log("Signature Done - The signature request is completed");
console.log(data);
});
Download Documents after
yousign.onSignatureDone
callback eventDue to a short internal process that occurs after the
yousign.onSuccess
event, attempting to download Documents right after this event will likely result in downloading the original Documents, not the Signed ones.
To ensure you download the Signed Documents, subscribe to theyousign.onSignatureDone
callback event instead.
Callback function data
For each event handler, Yousign retrieves some data about the signature request.
Callback function data property
Property name | Type | Description |
---|---|---|
type | string | Always equal to yousign . |
event | started | success | error |ping | declined | signature.done | Event type. |
signer_id | string | The signer ID. |
signature_request_id | string | The signature request ID. |
answers (only for success and error events) | array | A array of objects who list all the fields on the document. |
answers
property
answers
propertyProperty name | Type | Description |
---|---|---|
field_id | string | Field ID. |
field_type | text | checkbox | radio_group | The field type, see signer fields for more information about fields). |
Specific property for checkbox
field type
checkbox
field typeProperty name | Type | Description |
---|---|---|
checked | boolean | Determines if the checkbox field on the signature was checked. |
optional | boolean | Determines if the checkbox field on the signature was optional. |
Specific property for text
field type
text
field typeProperty name | Type | Description |
---|---|---|
question | string | The question in the text field on the signature. |
answer | string | The answer of the question text field on the signature. |
Specific property for radio_group
field type
radio_group
field typeProperty name | Type | Description |
---|---|---|
optional | boolean | Determines if the radio group field on the signature was optional. |
radios | radio[] | List of the radio button attached to the radio group. |
radio
property
radio
propertyProperty name | Type | Description |
---|---|---|
id | string | The radio button ID. |
checked | boolean | Determines if the radio button field on the signature was checked. |
name | string | Name of the radio button |
x | number | X coordinate position of the radio button field |
y | number | Y coordinate position of the radio button field |
Errors
Name | Description |
---|---|
InvalidSignatureLink | The signature link is not an URL or not valid. |
IframeContainerNotFound | The iframe container is not found. |
InvalidCallbackFunction | Callback on event is not a function. |
{
"type":"yousign",
"event":"success",
"signer_id":"18be1ef3-9d0c-4ed2-8ba3-273a9138d743",
"signature_request_id":"60620011-8b1a-4957-8733-67969f855877",
"answers":[
{
"field_id":"00f22ce7-cdb2-45e3-becd-6face7ca8c39",
"field_type":"checkbox",
"checked":true,
"optional":false
},
{
"field_id":"dd55cceb-4ce1-4fcb-936e-8f17c7d960c5",
"field_type":"text",
"question":"How are you ?",
"answer":"Very Good"
},
{
"field_id":"050b5425-5a7a-496b-ab92-b9c9c2ce46b2",
"field_type":"radio_group",
"optional":false,
"radios":[
{
"radio_id":"9d084514-9b3a-4504-b3dd-52736da112b4",
"checked":false,
"name": "radio 1 name",
"x": 130,
"y": 135
},
{
"radio_id":"eaf1b8e9-5ab0-4870-9733-8746559ed98d",
"checked":true,
"name": "radio 2 name",
"x": 160,
"y": 165
}
]
}
]
}
Other Methods
removeMessageListener()
Remove the window.message
event listener on the case you want to instantiate a new Yousign object.
let ys = null;
if (ys) {
ys.removeMessageListener();
}
else {
ys = new Yousign({
signatureLink: signature_link,
iframeContainerId: 'iframe-container',
isSandbox: false,
});
}
Embed manually the Signature Flow in an iFrame (not recommended)
If you can't use the SDK, you can embed the signature flow without it.
You will use the signature_link
of the activate signature request response for each signer as a source of an iframe.
<iframe src="{{signature_link}}"></iframe>
You need to send the referrer when fetching the iframe, set the
referrerpolicy
attribute tostrict-origin-when-cross-origin
.Or, you can set your
Referrer-Policy
headers toorigin-when-cross-origin
Then, you can catch the messages sent by Yousign to trigger a following action depending the event.
window.addEventListener('message', function(e) {
// Check if the origin of the message is really come from Yousign
if(e.origin === 'https://yousign.app' && e.data.type === 'yousign'){
if(e.data.event === 'started'){
console.log("Signer has opened the signature");
}
if(e.data.event === 'success'){
console.log('Signer has successfully signed the document');
}
if(e.data.event === 'error'){
console.log("Signer encountered an error when signing");
}
//Healthcheck, for debug only
if(e.data.event === 'ping'){
console.log("Ping - Signature request is loaded");
}
if(e.data.event === 'declined'){
console.log("Declined - The signer declined the signature");
}
if(e.data.event === 'signature.done'){
console.log("Signature Done - The signature request is completed");
}
}
});
Don't set the
redirectUrls
when adding a signer or on the custom experience, it disabled the events sent by the iframe.
For security reasons, iFrame is available only in production on whitelisted domains. To add your domains, please get in touch with our support.
Please note that it is also possible to whitelist a subdomain (https://subdomain.domain.com) or all subdomains of a domain by using a wildcard, for example https://*.domain.com. In this case all subdomains of domain.com will be authorized.
During your integration in sandbox environment, you can bypass the domain verification by adding the query parameter disable_domain_validation=true to the
signature_link
used as a source of the iframe. This parameter will be ignored in production.
Updated about 9 hours ago