Skip to content

Browser SDK

Every method of @esigncomply/browser, what each one records, and the requirements an integration has to respect.

@esigncomply/browser is headless. It renders nothing. It observes elements you built, reports ceremony events from the signer's browser straight to the Esign Comply API, and tells your code whether the ceremony can proceed. It authenticates with the short-lived session client token (esc_ct_...) that your server gets from POST /v1/sessions. It never holds a secret API key.

The steps a ceremony needs come from the session, not from this page. Read ceremony.remainingSteps() and satisfy what it lists. The model behind the steps is in The ceremony.

Install

npm install @esigncomply/browser
import { EsignComply, EsignComplyError } from "@esigncomply/browser";

The package is an ES module with type declarations and no dependencies. It exports EsignComply (with attach and version), the EsignComplyError class, the VERSION string and the types on this page: Ceremony, AttachOptions, Session, StepResult, Finding, CompleteResult, Verification, VerificationResult, AccessSample, PresentDocumentOptions, ObserveAssentOptions, RenewalElements, RequiredString, CeremonyEventMap and the rest.

A script-tag build is also published at the versioned path /sdk/v1/esigncomply.js on esigncomply.com. It defines one global, EsignComply, with the same attach function, version, and EsignComplyError.

<script src="https://esigncomply.com/sdk/v1/esigncomply.js"></script>

Attach

EsignComply.attach

const ceremony = await EsignComply.attach({ clientToken, apiUrl });
Option Type Required Description
clientToken string Yes The client_token of the session your server created. Starts with esc_ct_. Kept in memory only.
apiUrl string No Regional API base, for example https://api.eu.esigncomply.com/v1. Pass the api_url field of the session your server created. Default: https://esigncomply.com/v1.

attach reads the session ID, the test or live flag and the expiry from the token itself. It then reads the session with GET /v1/sessions/{id} and records client.attached (tag observed). The event carries the SDK version and the page address without query string or fragment. Unless the session uses minimal capture it also carries the viewport size, the browser language and the time zone.

It resolves with a Ceremony object. It rejects with an EsignComplyError:

Code When
invalid_request attach ran outside a browser (during server rendering). Raised in the browser SDK, status 0.
invalid_api_key clientToken is not a session client token. Secret keys never go to the browser. Raised in the browser SDK, status 0, param: "clientToken".
client_token_expired The session has expired. Create a new session and attach again.
domain_mismatch The page origin is outside the registered domain (live) or the test allowlist (test).

Any other API or network error rejects the same way. A failed attach leaves nothing behind: listeners are removed and the token is forgotten.

EsignComply.version is the SDK version string. ceremony.session is the last known session object: object, id, status, livemode, expires_at, assurance_level, signature_method, capture_mode, minimal_capture, required_steps, completed_steps, remaining_steps, documents, required_strings, record_id, purpose, locale and, when the API returns it, api_url. The SDK updates status, completed_steps, remaining_steps and record_id on it as steps are recorded.

EU region. A client token does not carry the API host. Return api_url from your server next to the client token and pass it as apiUrl, or the SDK reads the session from the US host. When apiUrl is not passed and the session it read names an api_url, the SDK uses that base for the calls that follow.

Documents

presentDocument

await ceremony.presentDocument({
  versionId: "dv_3kT9",
  mode: "hyperlink", // "hyperlink" | "inline" | "scrollbox"
  link: document.querySelector("#tos-link"),
});
Option Type Description
versionId string A version pinned on this session (session.documents[].version_id).
mode "hyperlink", "inline" or "scrollbox" How the document is put in front of the signer.
link Element The anchor the signer follows. Required for hyperlink.
container Element The element that holds the document text. Required for inline and scrollbox.
downloadControl, printControl Element Optional. The controls that save or print the exact pinned version.

Records document.presented (tag observed) and satisfies the step document.presented:<version_id>. Resolves with a StepResult. It rejects with invalid_request and rule CR-08 when versionId is not a version of this session, or when the element the mode needs (link or container) is missing.

Every report carries the mode and the language: the lang or hreflang attribute of the element, or else the language of the registered version.

What the event carries depends on the mode:

Mode Recorded
hyperlink Link text and address, whether the address is on the same site, and whether a download or print control exists. Unless capture is minimal: link visibility, underline, contrast against the surrounding text, font size, the viewport, whether the signer opened the link, and the hash of the page behind a same-origin link.
inline Whether a download or print control exists. Unless capture is minimal: the hash of the text inside the container (render_hash) and the viewport. The text is taken from the element marked data-esc-document when the container is or holds one, otherwise from the container.
scrollbox As inline, plus whether the signer scrolled to the end.

For a hyperlink on the same origin, the SDK fetches the linked page and hashes the text of the element marked data-esc-document (see Data attributes). It prefers the element whose attribute value is the version ID, then the first marked element. If the page does not answer with HTML within 4 seconds, or has no marked element, the link is still recorded and no hash is sent. The API compares that hash, or the inline render_hash, with the registered version. The hash covers the element's text content in Unicode NFC with whitespace and zero-width characters removed. In live mode a mismatch on an enforced rule rejects with render_mismatch (CR-08).

A presentation can be reported more than once: when the link becomes visible, when the signer opens it (a click, or a middle-button click), or when a scroll box reaches its end. Each report is a new document.presented event. Calling presentDocument again with the same version, element and mode returns the same promise, so a re-render does not record twice. A call with another element for the same version replaces the earlier presentation. A presentation that failed can be tried again with the same element.

The SDK records measured events only: link opened, scroll completed. It never reports that a signer read a document.

These three steps apply when the session's required_steps contain disclosure.presented, access.demonstrated and econsent.given. The walkthrough is in Consumer e-consent.

presentDisclosure

await ceremony.presentDisclosure({ container: document.querySelector("#econsent-disclosure") });

Records disclosure.presented (tag observed): the hash of the disclosure text and the headings found inside the container. Unless capture is minimal, the time the disclosure was on screen is measured, and the event is sent again with that time just before the consent event. Resolves with a StepResult. A missing container rejects with invalid_request and rule CR-16. A second call with the same element returns the same promise.

accessSample

const sample = await ceremony.accessSample(); // { format, instruction, html }

Fetches the sample document for the access demonstration from GET /v1/sessions/{id}/access-sample. The sample contains a six-digit code. Show instruction and render html in the page. This call records no event.

demonstrateAccess

await ceremony.demonstrateAccess({ code: codeField.value });

Records access.demonstrated (tag observed) when the code matches the one inside the sample. A wrong code rejects with verification_failed. Calling it before the disclosure rejects with step_out_of_order.

giveEConsent

ceremony.giveEConsent({ checkbox: document.querySelector("#econsent") });

Watches the consent checkbox. The promise resolves once the signer has ticked it and econsent.given (tag observed) is recorded with the control's label text, its state when the page loaded, whether the change came from a trusted user event, and its current state. Call it when the control renders, not from its change handler. If the signer unticks the box, the SDK reports that too and the step counts as outstanding again.

The tick is sent only after disclosure.presented and access.demonstrated are recorded. A box the SDK did not see being ticked (rendered checked, or ticked before the call) is reported with the signing act, inside complete(). A missing checkbox rejects with invalid_request and rule CR-01. If the API refuses the event the promise rejects, and a new call for the same control starts over.

Notice and intent

observeAssent

ceremony.observeAssent({
  region: document.querySelector("#assent"),   // notice text, links, checkbox, button
  checkbox: document.querySelector("#agree"),
  submit: document.querySelector("#create-account"),
});
Option Type Required Description
region Element Yes The container that holds the notice text, the document links, the assent control and the button.
submit Element Yes The button that performs the signing act.
checkbox Element No An unchecked native checkbox, or an element with role="checkbox" and aria-checked.
typedName input or textarea No An empty field for the signer's full name.
canvas canvas No Only for a drawn signature. Strokes are collected as vector points.
slots object No Values for the required_strings slots the page fills in: literal text, the element that shows it, or named parts of an element list.

The method follows from what you pass: canvas gives drawn, typedName gives typed, checkbox gives checkbox, none of them gives button acceptance (click). A missing region rejects with invalid_request and rule CR-02. A missing submit rejects with invalid_request and rule CR-03.

It records two steps.

notice.captured (tag observed), immediately. The visible text of the region without control values, the checkbox label and its initial state, the submit label, the document links, the number of primary buttons, and slot values. Unless capture is minimal it also carries the serialized markup of the region (up to 100 KB, without scripts or form values), font size, weight and contrast of the notice text, the body font size, whether notice and button fit in one viewport, whether the notice sits above the button, the distance between them, the distance from each document link to the button, and the number of visible primary buttons outside the region. In minimal capture no snapshot is taken unless the session requires the step.

intent.captured (tag observed), on the signer's action.

Control When the event is sent What it carries
Checkbox When the signer ticks the box. An untick is reported as well. Label text, button text, initial state, trusted, current state.
Typed name, drawn signature, button only Once, inside complete(). Nothing is sent while the signer types or draws. Control type, labels, initial state, trusted, the typed name, and the strokes when a canvas was passed and capture is not minimal.

trusted is true only when every change the SDK saw on the control came from a real user event. For button acceptance it is whether the click on the button was a real user event. A box ticked by script is reported as it is, with trusted: false, and fails CR-01. A control that was checked or prefilled when the page loaded is reported with that initial state. The SDK does not correct the page.

When a control is rendered checked or prefilled, or was already used when the SDK started watching it, the SDK raises a CR-01 finding of its own on the finding event (source: "sdk") before anyone clicks. The API still judges the rule on the event.

The button text is read when the signer clicks the button, before your page changes it to a busy label. Strokes are vector points relative to the canvas, without timing or pressure, up to 4,000 points. An element marked data-esc-clear inside the region clears them.

The promise resolves with the StepResult of the notice, or null when no snapshot is taken. Calling observeAssent again with the same elements returns the same promise. A call with other elements replaces the earlier watch. The promise is safe to leave unawaited: a failure also reaches the error event.

reviewPresented

await ceremony.reviewPresented({ container: document.querySelector("#review"), correctable: true });

Records review.presented (tag observed) with the hash of the summary text and whether the signer can correct inputs. correctable defaults to true when the container holds an element marked data-esc-correct. Used by CR-13.

Verification

L2 and L3 sessions contain the step identity.verified. L3 sessions also contain identity.verified:passkey. See L2 verification and L3 passkeys.

verify.start

const v = await ceremony.verify.start({ method: "email_otp" }); // "email_otp" | "email_link" | "sms_otp" | "passkey"

Calls POST /v1/sessions/{id}/verifications. For the first three methods it asks Esign Comply to send a one-time code or link to the address or number on the session's signer object. The browser cannot change the destination. For passkey use verify.passkey instead, which also runs the browser prompt. Resolves with a Verification:

Field Description
id Verification ID, for example ver_2bQd.
method The method started.
destination Masked destination, for example d***@example.org, or null.
status pending.
expiresAt Codes are valid for 10 minutes.
attemptsRemaining Starts at 5.
code Test mode only: present when the message was not delivered, so automation can continue.
challenge Passkey only: the WebAuthn options the API issued.

After email_link the signer confirms from the message, outside your page. The SDK then reads the session every 3 seconds, for up to 10 minutes, and emits stepRecorded for identity.verified once the link was used.

verify.confirm

const result = await ceremony.verify.confirm({ code: "418205" });
// { id, status: "confirmed" | "failed" | "registered", attemptsRemaining }

Confirms the code for the verification started last, with POST /v1/sessions/{id}/verifications/{ver_id}/confirm. On confirmed the API itself records identity.verified (tag observed), and the SDK emits stepRecorded for it with sequence: null. On failed show attemptsRemaining and let the signer try again. After five wrong attempts the session ends and the call rejects with verification_failed. registered occurs only in the passkey flow. Calling confirm before any start rejects in the browser with invalid_request and rule CR-17.

verify.passkey

const result = await ceremony.verify.passkey();
// { id, status: "confirmed" | "failed" | "registered", attemptsRemaining }

Runs the passkey step of an L3 session. It takes no arguments. Call it from a click handler, because browsers show the passkey prompt only in response to a user action. The signer's email or phone must already be verified in the same session.

What the call does:

  1. It starts a verification with { "method": "passkey" }. The API answers with phase: "register" and WebAuthn creation options when the signer has no passkey for this relying party, or with phase: "authenticate" and WebAuthn request options when one is on file.
  2. It runs the platform prompt: navigator.credentials.create() for the register phase, navigator.credentials.get() for the authenticate phase.
  3. It confirms the verification with the browser's response, sent as attestation (register) or assertion (authenticate).
  4. If the API answers registered, the new passkey is on file but the step is not recorded yet. The SDK starts a second verification at once, which is the authenticate phase, and runs steps 2 and 3 again. The signer sees two prompts.
Outcome Result
The assertion verified Resolves with status: "confirmed". The API recorded identity.verified for the step identity.verified:passkey, and the SDK emits stepRecorded.
The API could not verify the response Resolves with status: "failed" and the attemptsRemaining of that verification. Call verify.passkey() again to retry.
A second registration in a row Resolves with status: "registered". The SDK registers at most once per call. Call verify.passkey() again.
No passkey support in the browser, or the prompt was dismissed or did not complete Rejects in the browser with verification_failed, status 0 and rule CR-17. Offer another method or let the signer try again.
Email or phone not verified yet in this session Rejects with 409 step_out_of_order.
Plan without L3 Rejects with 403 plan_feature_unavailable.

When the session's signature_method is passkey and this call resolved with confirmed, complete() sends passkey as the signature method. The request and response bodies of both phases are in L3 passkeys.

Optional events

Call these only when the session's required_steps or the generated prompt ask for them. The checkbox methods behave like giveEConsent: they watch the control and resolve when the tick is recorded.

Method Event recorded Tag Step satisfied
languageSelected(code) language.selected observed none
ageAttested({ checkbox }) signer.age_attested asserted none
renewalTerms({ region, elements }) renewal_terms.presented observed renewal_terms.presented
renewalConsent({ checkbox, region? }) renewal.consent_given observed renewal_consent.captured
electronicAgreement({ checkbox }) electronic_agreement.given observed electronic_agreement.captured
sensitiveCaptureConsent({ checkbox }) sensitive_capture.consent_given observed sensitive_capture_consent.captured
acknowledge({ checkbox }) acknowledgment.given observed acknowledgment.captured
billingConfirm() billing.confirm asserted none

All of them resolve with a StepResult.

  • languageSelected(code) takes the language code the signer chose, for example "de", and records it as language.
  • The checkbox methods take { checkbox }, an unchecked native checkbox or an element with role="checkbox". They record the control's label text, its state when the page loaded, whether the change was a trusted user event, and the current state.
  • renewalConsent, electronicAgreement, sensitiveCaptureConsent and acknowledge also record separate_from_terms: whether the control is a different element from the terms checkbox passed to observeAssent.

renewalTerms and renewalConsent

await ceremony.renewalTerms({
  region: document.querySelector("#renewal-terms"),
  elements: {
    renewal_term: "every month",
    price: "$12.00",
    cancellation_policy: document.querySelector("#cancel-policy"),
    cancel_path: "Settings, then Billing, then Cancel plan",
  },
});
ceremony.renewalConsent({ checkbox: document.querySelector("#renewal-agree") });

renewalTerms records the text of the renewal block, the value of each element (renewal_term, price, cancellation_policy, cancel_path and the optional minimum_purchase, each as literal text or as the element that shows it), and whether the consent control sits in the same container. Unless capture is minimal it also measures the font size, weight and contrast of the block's text, the font size of the surrounding text, whether the block is set off by a border or a background of its own (or marked data-esc-set-off), and its distance to the consent control. The consent control is the checkbox passed to renewalConsent, or else a checkbox inside the region. A missing region rejects with invalid_request and rule CR-10.

renewalConsent records the tick of the renewal checkbox and whether that checkbox is separate from the terms checkbox. The tick is sent only after renewal_terms.presented is recorded. If the terms were measured against another control, the SDK sends renewal_terms.presented once more, measured against this checkbox. See CR-10, CR-21 and CR-23.

billingConfirm

Call ceremony.billingConfirm() immediately before your page submits a payment or starts billing. It is used only to order events (CR-22).

Steps and strings

remainingSteps

submitButton.disabled = ceremony.remainingSteps().some((s) => s !== "signature.applied");

Returns the outstanding steps in ceremony order. The ceremony is ready when only signature.applied is left. The list follows the page, not only the API: a checkbox that was unticked or a name field that was emptied counts as outstanding again. Subscribe to change to keep a button in sync.

requiredStrings

for (const s of ceremony.requiredStrings()) {
  // { slot, block, rule, kind: "verbatim" | "elements", text?, translations?, elements?, statutory?, label, check }
}

Returns the wording the session's jurisdiction packs ask the page to carry. Render each verbatim string unchanged in the slot it names, and fill each elements list with your own values. Strings with check: true are looked for in the captured assent region (CR-20).

Complete and cancel

complete

const result = await ceremony.complete(); // { recordId, receipt, verifyUrl, status }

Sends the signing act. Call it from the real submit handler, after the user's own click. It takes one optional argument, { typedName }, for pages that do not pass a typedName element to observeAssent.

What happens, in order:

  1. Events already on their way are sent first, and every watched control reports its final state, in ceremony order.
  2. If a step other than signature.applied is still outstanding, the SDK reads the session once more, in case a step was recorded outside the page (an emailed link). If steps are still outstanding, the call rejects in the browser with steps_incomplete, missingSteps, a rule and a fix. The signing act is not sent.
  3. A typed-name signature without a name rejects in the browser with steps_incomplete and param: "signature.typed_name".
  4. The SDK calls POST /v1/sessions/{id}/complete with the method, the label and button text, the typed name and the client time, under one idempotency key per signing act.
  5. A network failure or a 5xx answer retries the same request with the same key, up to two more times. If the answer is still lost, the SDK reads the session and, when a record already exists, resolves with it. The signer is never asked to act twice.

The method sent is passkey when the session's signature_method is passkey and verify.passkey() resolved with confirmed on this ceremony object. Otherwise it is drawn when a canvas was passed, typed when there is a typed name, and else the method observeAssent derived (checkbox or click), or the session's signature_method when observeAssent was not called.

Field Description
recordId The record, for example rec_Z4m8.
receipt Signed receipt, or null while the seal is pending or when the record was recovered after a lost response.
verifyUrl Verification page for the record, or null when recovered.
status recorded or pending_seal as the API answered, or unknown when the record was recovered.

A double click gets the same promise. After a completed ceremony, further calls resolve with the same result. On success the SDK stops watching the page, emits stepRecorded for signature.applied with the findings and advisories the API returned, and sets session.status to completed. When the API refuses the signing act, the SDK reads the session again so that remainingSteps() shows the API's view, and the next try uses a new idempotency key.

Never. Do not grant access or show "signed" on this result. It was delivered to the browser. Your server confirms the record with a secret key first: see Server confirmation.

cancel

await ceremony.cancel();

Cancels the session with POST /v1/sessions/{id}/cancel, for a decline control. The session moves to cancelled, the SDK stops watching the page, and no record is made. Resolves with nothing.

Events

on

const off = ceremony.on("finding", (f) => console.log(f.rule, f.message, f.fix));
off(); // unsubscribe
Event Payload Fired when
finding Finding A conformance finding did not pass: in an event response, behind an error, or with the signing act. Includes findings the SDK raises before the API sees the event (source: "sdk").
stepRecorded StepResult The API recorded a ceremony step. For identity.verified and signature.applied, which the API records itself, sequence is null.
expired { sessionId } The token's expiry time passed, or the API answered client_token_expired. Create a new session.
error EsignComplyError Any method failed. The same error also rejects the caller's promise. Each error is emitted once.
change { remainingSteps } The list remainingSteps() returns has changed: a step was recorded, or a watched control changed.

on returns the function that unsubscribes. An exception thrown by a handler is caught and logged. It does not stop the ceremony.

destroy

ceremony.destroy() removes every listener and observer and forgets the token. Call it when the component unmounts. Every method that talks to the API rejects with session_not_active afterwards, and no further events are emitted.

Results

interface StepResult {
  id: string;                 // evt_91xA
  type: string;               // "document.presented"
  sequence: number | null;    // null for steps the API records itself
  tag: string;                // "observed" | "asserted"
  versionId?: string;
  status: "pass" | "warn" | "block";
  findings: Finding[];
  remainingSteps: string[];
}

interface Finding {
  rule: string;               // "CR-01"
  status: "pass" | "warn" | "block";
  state: "enforce" | "advise";
  message: string;
  fix?: string;
  measurement?: Record<string, unknown>;
  maps_to?: string[];
  event_type?: string;
  version_id?: string;
  doc_url: string;            // https://esigncomply.com/docs/conformance#cr-01
  source?: "sdk";
}

Findings are advisory. state: "enforce" can refuse a live record. state: "advise" is measured and stored only. Test mode never blocks. The rules are listed in Conformance rules.

Errors

Every method rejects with one type, EsignComplyError, so a person or an AI coding tool can read the error and repair the page.

Field Description
code Stable machine code from the error reference, for example steps_incomplete. network_error when the API could not be reached.
type Error type from the API envelope, for example ceremony_error.
status HTTP status. 0 for a refusal made in the browser or a network failure.
message What happened. name is always EsignComplyError.
rule Conformance or pack rule that produced the error, for example CR-01.
missingSteps Steps still outstanding, on steps_incomplete and step_out_of_order.
findings The findings behind a conformance_failed or render_mismatch.
fix Plain-language repair: the fix of the first finding that has one, or the calls that record the missing steps, or a standard fix for the code.
param The option or request field at fault.
docUrl Link to the conformance rule when the rule is a CR- rule, otherwise the link the API sent for the code.
recordId Set when the session already has a record.
retryAfter Seconds, from Retry-After.
requestId The API request ID.

Errors raised in the browser, before or without an API answer, have status 0:

Code Type When
invalid_request invalid_request_error A required option or element is missing, attach ran outside a browser, confirm was called before start, or Web Crypto is not available on the page.
invalid_api_key authentication_error clientToken is not a session client token.
steps_incomplete ceremony_error complete() was called with steps outstanding, or without the typed name.
verification_failed ceremony_error verify.passkey(): no passkey support, or the prompt was dismissed.
client_token_expired authentication_error The token's expiry time has passed.
session_not_active conflict_error The ceremony was destroyed.
network_error api_error The API could not be reached.
internal_error api_error An unexpected failure inside the SDK.

An API answer without an error body becomes not_found for a 404 and internal_error otherwise.

try {
  const result = await ceremony.complete();
  await confirmOnServer(result.recordId);
} catch (err) {
  if (err instanceof EsignComplyError) {
    if (err.code === "client_token_expired") return restartCeremony();
    if (err.code === "network_error" || err.status >= 500) {
      return showMessage("We could not confirm whether your acceptance was recorded. Please wait while we check.");
    }
    showMessage(err.message); // keep the form, do not retry automatically
  }
}

On network_error do not treat the agreement as signed. Reconcile the same session on your server before asking the signer to act again.

Data attributes

The SDK reads these optional attributes on your own elements.

Attribute Where Meaning
data-esc-document The element that renders a document version. Optionally set its value to the version ID. The text that is hashed and compared with render_hash.
data-esc-download, data-esc-print Controls on the document page or inside the container. A control that saves or prints the exact pinned version.
data-esc-slot="<slot>" An element inside the assent region. The text shown for a required_strings slot.
data-esc-primary A custom element that acts as a primary button. Counted with submit buttons for CR-07.
data-esc-clear A button inside the assent region. Clears the strokes of a drawn signature.
data-esc-correct An element inside the review container. The signer can correct inputs from the review step.
data-esc-set-off The renewal terms region. The block is set off from the surrounding text.

Requirements that matter to an integrator

  • Small and self-contained. Under 15 KB compressed, no third-party dependencies, no cookies, no local or session storage. The client token lives in memory only.
  • Direct channel. Events go with fetch from the signer's browser to the regional API host, one at a time and in the order the page produced them. Each request carries the client token in the Authorization header and no cookies. An event that fails on the network or with a 5xx answer is sent again, up to two more times, under the same idempotency key. Never proxy SDK calls through your own server: the record would then show your server, not the signer's device.
  • Registered text only. Inline text and same-origin link targets are hashed and compared with the registered version. Render the version fetched from Esign Comply, unmodified. Do not copy document text into your repository.
  • Controls start clear. Every checkbox starts unchecked and every typed-name field starts empty. The SDK reports a pre-checked or prefilled control as it found it.
  • The user acts. Never call .click(), set .checked or submit on the user's behalf. Programmatic changes are reported with trusted: false. A trusted event shows that a user gesture occurred in the browser. It does not establish who acted.
  • No keystrokes, no screenshots. Only the submitted name is sent, once, with the signing act. Drawn strokes are sent only when a canvas is passed and are kept only when drawn capture is switched on for the domain. Apart from two page-level measurements (the body font size and a count of primary buttons outside the region), the SDK reads only the elements you name and the page behind a same-origin document link.
  • Minimal capture. When session.minimal_capture is true (EU, UK and CH packs, or a profile set to eu_minimal), the SDK sends no markup, styles, layout, link measurements, viewport, browser language, time zone or strokes, does not fetch the page behind a document link, and does not time the disclosure. The steps and method calls stay the same.
  • Outstanding steps. Keep the action control disabled until remainingSteps() contains only signature.applied.
  • Typed errors. Every rejection carries the rule ID and a fix.
  • Test mode is verbose. With a test session every recorded event, every finding that did not pass and every error is logged to the browser console with the rule ID and a documentation link.
  • Browser support. Current Chrome, Safari, Firefox and Edge, and mobile web views. The page must be served over HTTPS or from localhost, because hashing uses Web Crypto.

Content Security Policy

The SDK makes no network calls except fetch to the API host and a same-origin read of a linked document page. It uses no eval and injects no styles or scripts, so no unsafe-inline is needed.

Content-Security-Policy: connect-src https://esigncomply.com https://api.eu.esigncomply.com

Keep only the host of your region if you prefer. If your policy does not already allow same-origin requests, add 'self' so the SDK can read the document page behind a link. Without it the link is still recorded, and its target is not compared.

Server-rendered frameworks

Importing the package during server rendering is safe: nothing at module scope touches window or document. EsignComply.attach() itself must run in the browser. Call it inside an effect or an event handler of a client component. In Next.js that means a file marked "use client". See React hooks and the Next.js guide.

Complete example

A signup form with a checkbox and a button, at L1. The server creates the session with the Node SDK and returns only the client token, the API URL and the documents.

<form id="signup">
  <input id="email" type="email" autocomplete="email" required />
  <div id="assent">
    <p>
      By checking the box and clicking Create account, you agree to the
      <a id="tos-link" href="/legal/terms">Terms of Service</a> and acknowledge the
      <a id="privacy-link" href="/legal/privacy">Privacy Notice</a>.
    </p>
    <label><input id="agree" type="checkbox" /> I agree to the Terms of Service and Privacy Notice</label>
    <button id="create-account" type="submit" disabled>Create account</button>
  </div>
  <p id="message" role="alert"></p>
</form>
import { EsignComply, EsignComplyError } from "@esigncomply/browser";

const form = document.querySelector<HTMLFormElement>("#signup")!;
const submit = document.querySelector<HTMLButtonElement>("#create-account")!;
const message = document.querySelector<HTMLElement>("#message")!;

// Your own route. It calls esc.sessions.create() with the secret key and returns
// { clientToken, apiUrl, documents } to the browser. Nothing else.
const res = await fetch("/api/ceremony", { method: "POST" });
if (!res.ok) throw new Error("Unable to create ceremony");
const { clientToken, apiUrl, documents } = await res.json();

const ceremony = await EsignComply.attach({ clientToken, apiUrl });

await ceremony.presentDocument({ versionId: documents[0].version_id, mode: "hyperlink", link: document.querySelector("#tos-link") });
await ceremony.presentDocument({ versionId: documents[1].version_id, mode: "hyperlink", link: document.querySelector("#privacy-link") });

ceremony.observeAssent({
  region: document.querySelector("#assent"),
  checkbox: document.querySelector("#agree"),
  submit,
});

const sync = () => {
  submit.disabled = ceremony.remainingSteps().some((step) => step !== "signature.applied");
};
ceremony.on("change", sync);
ceremony.on("expired", () => {
  message.textContent = "This page has been open for a while. Reload it to continue.";
});
sync();

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  try {
    const result = await ceremony.complete(); // { recordId, receipt, verifyUrl, status }
    // Your authenticated route confirms the record with the secret key before creating the account.
    const confirmed = await fetch("/api/signup/finish", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ recordId: result.recordId, email: form.email.value }),
    });
    if (!confirmed.ok) throw new Error("Not confirmed");
    location.assign("/welcome");
  } catch (err) {
    // A refusal (4xx, or one made in the browser) carries a message and a fix: keep the form.
    // Anything else is inconclusive: never proceed without a confirmed record.
    const refused = err instanceof EsignComplyError && err.code !== "network_error" && err.status < 500;
    message.textContent = refused
      ? err.message
      : "We could not confirm whether your acceptance was recorded. Please wait while we check.";
  }
});