Embed signing

Overview

The Embed Signing feature allows you to integrate the document signing process directly into your web application. This provides a seamless experience for users, enabling them to sign documents without leaving your platform.

Steps

Add package

When you want to embed the signing experience, you have to create a package with generateSignerLinks and the embedded package option set to true.

Request

POST /packages/add
{
    "name": "Embedded Package Signing",
    "type": "concurrent",
    "state": "open",
    "generateSignerLinks": true,
    "options": {
        "embedded": true
    },
    "signers": [
        {
            "firstName": "signer",
            "lastName": "one",
            "email": "signer.one@example.com"
        }
    ],
    "documents": [
        {
            "fileName": "document.pdf",
            "fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
        }
    ]
}

Response

{
    "package": {
        ...
        "signers": [
            {
                ...
                 "signLink": {
                     "link": "https://sign.syngrafii.com/link/mzLzlN5zECs2SlS_VJ-njg"
                 },
                ...
            }
        ],
        ...
    }
}

Embed signing or VSR

To embed the signing or VSR experience in an iframe, you need to use the signLink.link URL provided in the add package response or by calling the packages/{packageId}/link/sign/{signerId} endpoint directly.

Signings
VSR

<iframe 
    id="signing-iframe"
    src="https://sign.syngrafii.com/link/mzLzlN5zECs2SlS_VJ-njg"
    allow="geolocation https://sign.syngrafii.com"
></iframe>

Make sure to set the allow attribute on the iframe to enable necessary permissions like geolocation access.

<iframe 
    id="vsr-iframe"
    src="https://sign.syngrafii.com/link/mzLzlN5zECs2SlS_VJ-njg"
    allow="geolocation https://sign.syngrafii.com; camera https://sign.syngrafii.com; microphone https://sign.syngrafii.com; display-capture https://sign.syngrafii.com;"
></iframe>

Make sure to set the allow attribute on the iframe to enable necessary permissions like geolocation, camera, microphone, and display-capture access.

JavaScript for VSR host embedding

Embedding a video signing room for a host requires additional JavaScript to send the position of the iframe within the parent window. Without this information the screen share video will not be correctly cropped when shared with other signers.

VSR Host Embed Script

<script>
    function sendEmbedPosition() {
        const iframe = document.getElementById("vsr-iframe");
        if (!iframe) return;

        iframe.contentWindow.postMessage({
            source: "syngrafii-embed",
            action: "embed_position",
            data: {
                window: {
                    outerWidth: window.outerWidth,
                    outerHeight: window.outerHeight,
                    innerWidth: window.innerWidth,
                    innerHeight: window.innerHeight,
                },
                embed: iframe.getBoundingClientRect()
            }
        }, "https://sign.syngrafii.com");
    }

    window.addEventListener("message", (event) => {

        // Validate origin
        if (event.origin !== "https://sign.syngrafii.com" || !event.data) return;

        switch (event.data.action) {
            case "meeting_join":
            case "meeting_start":
                sendEmbedPosition();
                break;
        }
    }, false);

    window.addEventListener("resize", sendEmbedPosition, false);
</script>

Process embed messages

When embedding the signing experience, you may want to handle certain events such as when the signing is completed or any errors occur. You can achieve this by listening for messages from the iframe.

window.addEventListener("message", (event) => {
    // Validate origin
    if (event.origin !== "https://sign.syngrafii.com" || !event.data) return;

    // Handle action
    switch (event.data.action) {
        case "signing_sent":
            // User has completed signing all documents and was redirected to /sent page.
            break;
        case "signing_close":
            // User has closed signing and was redirected to /notsent page.
            break;
        case "session_expired":
            // User session has expired due to inactivity
            break;
    }

}, false);

See the Embed messaging guide for more information.

⌘I

Getting started

Guides

API

Webhooks

Reference

Overview

Steps

Add package

Embed signing or VSR

JavaScript for VSR host embedding

Process embed messages

​Overview

​Steps

Add package

Embed signing or VSR

​JavaScript for VSR host embedding

Process embed messages

Overview

Steps

JavaScript for VSR host embedding