Integrate the 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 afteryousign.onSignatureDonecallback eventDue to a short internal process that occurs after the
yousign.onSuccessevent, 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.onSignatureDonecallback 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 property| Property 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 type| Property 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 type| Property 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 type| Property 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 property| Property 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
referrerpolicyattribute tostrict-origin-when-cross-origin.Or, you can set your
Referrer-Policyheaders 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
redirectUrlswhen adding a signer or on the custom experience, it disabled the events sent by the iframe.
For security reasons, iFrame in production is only available on authorized domains. To authorize your domains, please follow this guide.
During your integration in sandbox environment, you can bypass the domain verification by adding the query parameter disable_domain_validation=true to the
signature_linkused as a source of the iframe. This parameter will be ignored in production.
Updated 10 days ago