Chaindoc Embed SDK

Official JavaScript/TypeScript SDK for embedding Chaindoc signature flows into web applications

What is Chaindoc Embed SDK?

Chaindoc Embed SDK is a lightweight JavaScript library that allows you to seamlessly integrate document signing functionality into your web application. Instead of redirecting users to a separate signing page, you can embed the entire signing experience directly within your site using a modal dialog or inline container.

Features

• Zero Backend Integration - SDK manages iframe lifecycle; your backend only creates signing sessions
• Event-Driven Architecture - Type-safe postMessage API for real-time communication
• Multiple Display Modes - Modal overlay or inline embedding
• Framework Agnostic - Works with React, Vue, Angular, vanilla JavaScript, or any web framework
• TypeScript Support - Full type definitions included
• Secure by Default - Origin validation and sandboxed iframe
• Lightweight - Zero runtime dependencies, <10KB gzipped
• Auto-Responsive - Iframe automatically resizes based on content

Installation

npm install @chaindoc_io/embed-sdk

Or using yarn:

yarn add @chaindoc_io/embed-sdk

CDN Usage

You can also use the SDK directly via CDN:

<script src="https://unpkg.com/@chaindoc_io/embed-sdk"></script>
<script>
  const sdk = new ChaindocEmbed.ChaindocEmbed({
    publicKey: "pk_live_xxx",
    environment: "production",
  });
</script>

Quick Start

import { ChaindocEmbed } from "@chaindoc_io/embed-sdk";

// Initialize SDK
const sdk = new ChaindocEmbed({
  publicKey: "pk_live_xxx",
  environment: "production",
});

// Open signature flow in modal
const instance = sdk.openSignatureFlow({
  sessionId: "ses_xxx", // From your backend
  email: "[email protected]",
  mode: "modal",
  language: "en", // Optional: UI language (en, ru, uk, pl, de, es, pt, fr, et, kk, zh, hi, tr, vi)
  onSuccess: (data) => {
    console.log("Document signed!", data);
    instance.close();
  },
  onError: (error) => {
    console.error("Signing failed:", error);
  },
});

publicKey today

publicKey is still required and validated on SDK initialization, but it is not currently forwarded to the iframe or used for runtime authentication. The real embedded auth flow is:

1. Your backend creates an embedded session
2. The signer verifies OTP
3. The iframe receives a short-lived JWT for /api/v1/embedded/*

The field remains in the API for backward compatibility and future productization, but for Phase 0 it should be understood as ceremonial rather than security-critical runtime auth.

How It Works

1. Your backend creates a signing session via Chaindoc API
2. You pass the sessionId to the SDK
3. SDK opens an iframe with the Chaindoc signing UI
4. User completes OTP verification and signs the document
5. SDK receives success event and calls your callback
6. You can verify the signature on your backend

Display Modes

Modal Mode (Default)

Opens a centered modal dialog with overlay - perfect for most use cases.

Inline Mode

Embeds the signing flow directly into a container element on your page - ideal for multi-step forms or dedicated signing pages.

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Mobile Safari 14+
• Chrome Android 90+

Documentation

For detailed documentation, API reference, and examples, visit:

• Introduction
• Quick Start
• API Documentation
• Chaindoc SDKs
• Changelog - Version history

Changelog

See CHANGELOG.md for release history and migration guides.

License

MIT License - see LICENSE file for details

Support

• GitHub Issues: Report a bug
• Documentation: https://chaindoc.io/docs

Made with ❤️ by the Chaindoc team