Skip to main content
Web Integration
Learn how to integrate the IgniSign signature interface into your web applications

Overview​

Embed the signer in your application with an iframe, or let IgniSign email the signer a link (BySide). The signer host is the same in every environment:

https://sign.ignisign.io

DEVELOPMENT, STAGING and PRODUCTION do not use a different hostname. The environment is selected by the API key that created the signature request. There is no client-sign.ignisign.io host, and there is no script on cdn.ignisign.io.

Embedded Integration with iframe​

The iframe loads the signing page for one signer. Your backend creates the signature request and passes four values to your frontend: signatureRequestId, signerId, signatureSessionToken and signerAuthSecret.

Implementation Steps
1
Backend Creates Signature Request
Your backend uses the API to create a signature request and get the signature session token
2
Backend Provides Details to Frontend
Your backend provides the signature request ID, signer ID, session token, and signer auth secret to your frontend
3
Frontend Embeds Signature Interface
Your frontend adds an iframe that loads https://sign.ignisign.io with the required parameters
4
Set Up Communication
Listen for postMessage events from https://sign.ignisign.io
Flow
Basic Implementation

The iframe URL is:

https://sign.ignisign.io/signature-requests/{signatureRequestId}/signers/{signerId}/sign?token={signatureSessionToken}&signerSecret={signerAuthSecret}

Open that URL inside an iframe. An embedded session opened as a top-level browser tab shows "This page must be displayed in an iframe".

The container must be at least 200px wide and 400px tall. 500px is a safe height.

<div id="signature-container" style="width: 100%; height: 500px;">
<iframe
  id="signature-iframe"
  title="IgniSign"
  src="https://sign.ignisign.io/signature-requests/{signatureRequestId}/signers/{signerId}/sign?token={signatureSessionToken}&signerSecret={signerAuthSecret}"
  style="width: 100%; height: 100%; border: none;"
  allow="publickey-credentials-get; publickey-credentials-create"
></iframe>
</div>

IGNISIGN_COMPLETE, IGNISIGN_ERROR, IGNISIGN_CANCELED and IGNISIGN_PROGRESS are not events. A listener that switches on those names never runs.

Using the JavaScript SDK

The browser SDK builds the same iframe URL and handles these events. It is optional. Install it from npm. There is no hosted script.

npm install @ignisign/js @ignisign/public
import { IgnisignJs } from "@ignisign/js";
import { IGNISIGN_APPLICATION_ENV } from "@ignisign/public";

const ignisignJs = new IgnisignJs(appId, IGNISIGN_APPLICATION_ENV.DEVELOPMENT);

await ignisignJs.initSignatureSession({
htmlElementId: "signature-container",
signatureRequestId,
signerId,
signatureSessionToken,
signerAuthSecret,
sessionCallbacks: {
handleSignatureSessionFinalized: async (signatureIds) => {
console.log(signatureIds);
},
handleSignatureSessionError: async (errorCode, errorContext) => {
console.error(errorCode, errorContext);
},
},
});

Full parameter list: Browser JS SDK.

Security Considerations
  • Accept postMessage only from https://sign.ignisign.io
  • Load the parent page over HTTPS
  • The session token and signer auth secret are query parameters of the iframe URL. Treat that URL as a secret.

BySide Integration with Email Delivery​

BySide does not use an iframe. Your backend creates the signature request with the Node.js SDK (npm install @ignisign/sdk). IgniSign emails the signer a link on https://sign.ignisign.io. Your backend learns that the signature is done from a webhook, not from a return URL on your site.

Implementation Steps
1
Backend Creates Signature Request
Your backend uses the API to create a signature request with the signer's email address
2
IgniSign Emails the Signer
IgniSign sends an email with the signature link on https://sign.ignisign.io
3
Signer Completes Process on IgniSign
The signer opens the link and signs on the IgniSign page
4
Configure Webhooks
Your backend receives the signature and proof events

Query parameters​

Required:

ParameterDescription
tokenSignature session token
signerSecretSigner auth secret

Optional. The browser SDK appends the first four from displayOptions; forceLanguage is read by the signing page. hideTitle, lang and returnUrl are not parameters.

ParameterDefaultExample
showTitlefalseshowTitle=true
showDescriptionfalseshowDescription=true
darkModefalsedarkMode=true
forceShowDocumentInformationsfalseforceShowDocumentInformations=true
forceLanguagebrowser languageforceLanguage=FR

forceLanguage takes an IGNISIGN_LANGUAGES code (EN, FR, DE, IT, …). Case and region are ignored: fr, fr-FR and FR all select French. nb and nn map to NO.

Example:

https://sign.ignisign.io/signature-requests/{signatureRequestId}/signers/{signerId}/sign?token={signatureSessionToken}&signerSecret={signerAuthSecret}&showTitle=false&darkMode=true&forceLanguage=FR

Common issues​

IssueWhat to check
The iframe host does not resolve (NXDOMAIN)The host is https://sign.ignisign.io in every environment. client-sign.ignisign.io does not exist.
"This page must be displayed in an iframe"The URL was opened as a top-level tab. Load it in an iframe.
The completion handler never runsevent.origin must be https://sign.ignisign.io. The type values are SIGNATURE_FINALIZED (data.signatureIds), SIGNATURE_ERROR (data.errorCode, data.errorContext), OPEN_URL (data.url) and NEED_PRIVATE_FILE_URL. IGNISIGN_COMPLETE, IGNISIGN_ERROR, IGNISIGN_CANCELED and IGNISIGN_PROGRESS are not sent.
The SDK refuses to start, or warns that the iframe is too smallThe container must be at least 200px wide and 400px tall.

Next steps​