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.
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.
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.
- 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.
Query parameters
Required:
| Parameter | Description |
|---|---|
token | Signature session token |
signerSecret | Signer 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.
| Parameter | Default | Example |
|---|---|---|
showTitle | false | showTitle=true |
showDescription | false | showDescription=true |
darkMode | false | darkMode=true |
forceShowDocumentInformations | false | forceShowDocumentInformations=true |
forceLanguage | browser language | forceLanguage=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
| Issue | What 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 runs | event.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 small | The container must be at least 200px wide and 400px tall. |