RoadmapTestimonies

iFrame

Suggest Edits

iFrame SDK API reference

Version 1.5.0

Load the script below in your page to use our SDK.

<script src="https://cdn.yousign.tech/iframe-sdk-1.5.0.min.js" integrity="sha384-wrNTU81R+b2K+9A1aE1c3blhReNpdRK6Tn1fzXOXhWGZGUk+Btp0dyfnk45pVpOr" crossorigin="anonymous"></script>

<script src="https://cdn.yousign.tech/iframe-sdk-1.5.0.js" integrity="sha384-xu+nIpHcnL4yZ9ApQdQNV0qAvD1TklmiUcUuBew+Ry77qpZ/jIicdEvpj5vFpJaw" crossorigin="anonymous"></script>

Or you can download the source file and load the script manually on your page :

Download the compressed SDK (v1.5.0)
Download the uncompressed SDK (v1.5.0)

Initialization

To initialize the SDK, you need to instantiate a Yousign class with the following parameters

Parameter nameTypeDescription
signatureLinkstringThe URL of the signature request.
iframeContainerIdstringThe id attribute of the element where the iframe is initialized.
isSandbox (optional)booleanTo set if you want to test your integration with sandbox environment
const yousign = new Yousign({
  signatureLink: 'signature_link',
  iframeContainerId: 'iframe-container',
  isSandbox: false,
});

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 Flow
  • success: Signer has signed successfully
  • error: Signer has encountered an error when signing
  • ping: (healthcheck, for debug only) Signature Request is loaded (event sent every 5 seconds)
  • declined: When signer declined the signature

Each method takes a callback function as a parameter which is triggered when the corresponding event is caught.

Method nameDescription
onStarted()A function that is triggered when the signature is opened.
onSuccess()A function that is triggered when the signature is signed successfully.
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.
yousign.onStarted((data) => {
  console.log("Signer has opened the signature");
	console.log(data);
});

yousign.onSuccess((data) => {
  console.log("Signer has successfully signed");
	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);
}

Callback function data

For each event handler, Yousign retrieves some data about the signature request.

Callback function data property

Property nameTypeDescription
typestringAlways equal to yousign.
eventstarted | success | error |ping | declinedEvent type.
signer_idstringThe signer ID.
signature_request_idstringThe signature request ID.
answers (only for success and error events)arrayA array of objects who list all the fields on the document.

answers property

Property nameTypeDescription
field_idstringField ID.
field_typetext | checkbox | radio_groupThe field type, see signer fields for more information about fields).

Specific property for checkbox field type

Property nameTypeDescription
checkedbooleanDetermines if the checkbox field on the signature was checked.
optionalbooleanDetermines if the checkbox field on the signature was optional.

Specific property for text field type

Property nameTypeDescription
questionstringThe question in the text field on the signature.
answerstringThe answer of the question text field on the signature.

Specific property for radio_group field type

Property nameTypeDescription
optionalbooleanDetermines if the radio group field on the signature was optional.
radiosradio[]List of the radio button attached to the radio group.

radio property

Property nameTypeDescription
idstringThe radio button ID.
checkedbooleanDetermines if the radio button field on the signature was checked.
namestringName of the radio button
xnumberX coordinate position of the radio button field
ynumberY coordinate position of the radio button field

Errors

NameDescription
InvalidSignatureLinkThe signature link is not an URL or not valid.
IframeContainerNotFoundThe iframe container is not found.
InvalidCallbackFunctionCallback 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 to strict-origin-when-cross-origin.

Or, you can set your Referrer-Policy headers to origin-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');
    }
    
    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");
    }
  }
});

🚧

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 17 days ago