iFrame SDK API reference

<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.
Example

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 Flow
success: Signer has signed successfully the document
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
signature.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).
Example

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);
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

{
   "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. 

Usage

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.

HTML

<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.
JavaScript

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.