iFrame Embedded Preparation

The Embedded Preparation can be embedded directly in your own application, so your users never leave your product. Once embedded, the portal sends JavaScript events to the parent page through window.postMessage, letting you hide your loader, react when the user is done, and recover from an expired link or session.

To embed the portal, you first need a preparation link. To learn how to generate one, follow the detailed guide here: Embedded Preparation - Generate an Embedded Preparation link.

Embed the portal

Use the link returned by Generate an Embedded Preparation link as the source of an iFrame.

<iframe src="{{preparation_link}}" />

Events emitted

Every message shares the same envelope:

{ type: "yousign", event, signature_request_id }. Only expired carries an extra key.

Listen on the parent page

Always check that the message comes from Yousign before acting on it.

window.addEventListener('message', function (e) {
  // Check that the message really comes from Yousign
  if (e.origin !== 'https://yousign.app' || e.data.type !== 'yousign') {
    return;
  }

  switch (e.data.event) {
    case 'ready':
      console.log('Preparation portal is displayed, you can hide your loader');
      break;

    case 'done':
      console.log('User completed the preparation');
      // If a Done redirect URL is configured, the iFrame navigates itself right after
      break;

    case 'back':
      console.log('User clicked Back');
      // If a Back redirect URL is configured, the iFrame navigates itself right after
      break;

    case 'expired':
      console.log('Preparation stopped:', e.data.reason);
      // Request a new preparation link from your backend, then reload the iFrame
      break;

    case 'invalid':
      console.log('The preparation link could not be opened');
      break;

    case 'field.added':
    case 'field.deleted':
      console.log('Fields changed, fetch them again from the API');
      break;

    // Healthcheck, for debug only
    case 'ping':
      console.log('Ping - preparation portal is loaded');
      break;
  }
});

Handling patterns

• ready: Hide your own loading state. The event is sent once, so do not rely on it to detect a reload.
• done: if a Done redirect URL is set on the Signature Request, the iFrame navigates to it right after the event. Otherwise the portal shows its success screen and stays in place, and redirecting the user afterwards is up to you.
• back: emitted when the user clicks the Back button. The button is displayed when it is enabled on the Custom Experience attached to the Signature Request. If a Back redirect URL is set on the Signature Request, the iFrame navigates to it immediately after the event; if not, the event is the only signal and the portal stays in place, so the parent page decides what to do.
• expiredGenerate a new preparation link and load it in the iFrame. The same Signature Request can be reused as long as it is still in draft status. reason: "link" means the link had already expired when the portal tried to open it, for instance because the page was reloaded more than 10 minutes after the link was generated; reason: "session" means the one-hour session ran out mid-use.
• invalid: the link cannot be recovered. Check that you are using the link returned by the API, unchanged.
• field.added / field.deletedThese are signals, not payloads. Fetch the current fields from the API to know the exact state. A single event covers one successful operation, so deleting several fields at once emits one field.deleted, while duplicating or pasting several fields emits one field.added per created field. Moving, resizing, or editing the settings of a field emits nothing, and adding or removing an option of a radio group emits nothing either: the group itself is the observable unit.
• ping Use it for debugging only. If your page also embeds the signature iFrame, both send a ping carrying a signature_request_id; the signature one also carries a signer_id.

Configure the redirect URLs

Both Done and Back can redirect the iFrame to a URL of your own, set on the Signature Request when you create or update it:

{
  "embedded_preparation": {
    "redirect_urls": {
      "done": "https://your-app.com/done",
      "back": "https://your-app.com/back"
    }
  }
}

The iFrame navigates itself; it never touches the parent page. The done and back events are always emitted before the navigation, so a parent listening for them keeps control.

Displaying the Done and Back buttons is driven by the Custom Experience attached to the Signature Request, not by these URLs: a button enabled without a matching URL emits its event and leaves the portal in place.

Testing in Sandbox

During your integration in the Sandbox environment, you can bypass the domain verification by adding the query parameter disable_domain_validation=true to the preparation link used as a source of the iFrame.

https://yousign.app/embedded-preparation/{{signature_request_id}}?...&sandbox=true&disable_domain_validation=true

A Sandbox link already carries sandbox=true, so there is nothing else to add. This bypass only works in Sandbox: in production, authorizing your domains stays mandatory.

Events behave exactly the same in Sandbox as in production, and the origin to check is the same: https://yousign.app.