Ryan/documenso
1
0
Fork 1
mirror of https://github.com/documenso/documenso.git synced 2025-11-12 15:53:02 +10:00
Code Issues Packages Projects Releases Wiki Activity

feat: embed signing experience (#1322)

Browse Source
This commit is contained in:
Lucas Smith
2024-09-04 23:13:00 +10:00
committed by GitHub
parent 3657050b02
commit a1a8a174bf
39 changed files with 2090 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
apps/documentation/pages/developers/embedding/index.mdx Normal file
View File

@ -0,0 +1,131 @@
---
title: Get Started
description: Learn how to use embedding to bring signing to your own website or application
---
# Embedding
Our embedding feature lets you integrate our document signing experience into your own application or website. Whether you're building with React, Preact, Vue, Svelte, Solid, or using generalized web components, this guide will help you get started with embedding Documenso.
## Availability
Embedding is currently available for all users on a **Teams Plan** and above, as well as **Early Adopter's** within a team (Early Adopters can create a team for free).
In the future, we will roll out a **Platform Plan** that will offer additional enhancements for embedding, including the option to remove Documenso branding for a more customized experience.
## How Embedding Works
Embedding with Documenso allows you to handle document signing in two main ways:
1. **Using Direct Templates**: Using direct templates you can have an evergreen template that upon completion will create a new document within Documenso.
2. **Using a Signing Token**: A more advanced option for those running rich integrations with Documenso already. Given a recipients signing token you can embed the signing experience in your application rather than direct the recipient to Documenso.
_For most use-cases we recommend using direct templates, however if you have a need for a more advanced integration, we are happy to help you get started._
## Supported Frameworks
We support embedding across a range of popular JavaScript frameworks, including:
| Framework | Package |
| --------- | -------------------------------------------------------------------------------- |
| React | [@documenso/embed-react](https://www.npmjs.com/package/@documenso/embed-react) |
| Preact | [@documenso/embed-preact](https://www.npmjs.com/package/@documenso/embed-preact) |
| Vue | [@documenso/embed-vue](https://www.npmjs.com/package/@documenso/embed-vue) |
| Svelte | [@documenso/embed-svelte](https://www.npmjs.com/package/@documenso/embed-svelte) |
| Solid | [@documenso/embed-solid](https://www.npmjs.com/package/@documenso/embed-solid) |
Additionally, we provide **web components** for more generalized use. However, please note that web components are still in their early stages and haven't been extensively tested.
## Embedding with Direct Templates
#### Instructions
To get started with embedding using a Direct Template we will need the URL segment which is also referred to as the token for the template.
You can find your URL/Token by performing the following steps:
1. **Navigate to your team's templates within Documenso**
![Team Templates](/embedding/team-templates.png)
2. **Click on the direct link template you want to embed**
This will copy the URL to your clipboard, e.g. `https://stg-app.documenso.com/d/-WoSwWVT-fYOERS2MI37k`
**For the above url the token is `-WoSwWVT-fYOERS2MI37k`**
3. Provide the token to the `EmbedDirectTemplate` component in your frameworks SDK
```jsx
import { EmbedDirectTemplate } from '@documenso/embed-react';
const MyEmbeddingComponent = () => {
const token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
return <EmbedDirectTemplate token={token} />;
};
```
---
**Converting a regular template to a direct link template**
If you don't currently have any direct link templates you can easily create one by selecting the "Direct Link" option within the actions dropdown on the templates table.
This will show a dialog which will ask you to configure which recipient should be used as the direct link signer.
![Enable Direct Link Template](/embedding/enable-direct-link.png)
---
## Embedding with Signing Tokens
To embed the signing process for an ordinary document, you’ll need a **document signing token** for the recipient. This token provides the necessary access to load the document and facilitate the signing process securely.
#### Instructions
1. Retrieve the signing token for the recipient document you want to embed
This will typically be done using an API integration where signing tokens are provided as part of the response when creating a document. Alternatively you can manually get a signing link by clicking hovering over a recipients avatar and clicking their email on a document that you own.
![Copy Recipient Token](/embedding/copy-recipient-token.png)
With the signing url on our clipboard we can extract the token the same way we did for the direct link template.
So `https://stg-app.documenso.com/sign/lm7Tp2_yhvFfzdeJQzYQF` will become `lm7Tp2_yhvFfzdeJQzYQF`
2. Provide the token to the `EmbedSignDocument` component in your frameworks SDK
```jsx
import { EmbedSignDocument } from '@documenso/embed-react';
const MyEmbeddingComponent = () => {
const token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
return <EmbedSignDocument token={token} />;
};
```
---
## Using Embedding in Your Application
Once you've obtained the appropriate tokens, you can integrate the signing experience into your application. For framework-specific instructions, please refer to the guides provided in our documentation for:
- [React](/developers/embedding/react)
- [Preact](/developers/embedding/preact)
- [Vue](/developers/embedding/vue)
- [Svelte](/developers/embedding/svelte)
- [Solid](/developers/embedding/solid)
If you're using **web components**, the integration process is slightly different. Keep in mind that web components are currently less tested but can still provide flexibility for general use cases.
## Stay Tuned for the Platform Plan
While embedding is already a powerful tool, we're working on a **Platform Plan** that will introduce even more functionality. This plan will offer:
- Additional customization options
- The ability to remove Documenso branding
- Additional controls for the signing experience
More details will be shared as we approach the release.

77
apps/documentation/pages/developers/embedding/preact.mdx Normal file
View File

@ -0,0 +1,77 @@
---
title: Preact Integration
description: Learn how to use our embedding SDK within your Preact application.
---
# Preact Integration
Our Preact SDK provides a simple way to embed a signing experience within your Preact application. It supports both direct link templates and signing tokens.
## Installation
To install the SDK, run the following command:
```bash
npm install @documenso/embed-preact
```
## Usage
To embed a signing experience, you'll need to provide the token for the document you want to embed. This can be done in a few different ways, depending on your use case.
### Direct Link Template
If you have a direct link template, you can simply provide the token for the template to the `EmbedDirectTemplate` component.
```jsx
import { EmbedDirectTemplate } from '@documenso/embed-preact';
const MyEmbeddingComponent = () => {
const token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
return <EmbedDirectTemplate token={token} />;
};
```
#### Props
| Prop | Type | Description |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| token | string | The token for the document you want to embed |
| host | string (optional) | The host to be used for the signing experience, relevant for self-hosters |
| name | string (optional) | The name the signer that will be used by default for signing |
| lockName | boolean (optional) | Whether or not the name field should be locked disallowing modifications |
| email | string (optional) | The email the signer that will be used by default for signing |
| lockEmail | boolean (optional) | Whether or not the email field should be locked disallowing modifications |
| externalId | string (optional) | The external ID to be used for the document that will be created upon completion |
| onDocumentReady | function (optional) | A callback function that will be called when the document is loaded and ready to be signed |
| onDocumentCompleted | function (optional) | A callback function that will be called when the document has been completed |
| onDocumentError | function (optional) | A callback function that will be called when an error occurs with the document |
| onFieldSigned | function (optional) | A callback function that will be called when a field has been signed |
| onFieldUnsigned | function (optional) | A callback function that will be called when a field has been unsigned |
### Signing Token
If you have a signing token, you can provide it to the `EmbedSignDocument` component.
```jsx
import { EmbedSignDocument } from '@documenso/embed-preact';
const MyEmbeddingComponent = () => {
const token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
return <EmbedSignDocument token={token} />;
};
```
#### Props
| Prop | Type | Description |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| token | string | The token for the document you want to embed |
| host | string (optional) | The host to be used for the signing experience, relevant for self-hosters |
| name | string (optional) | The name the signer that will be used by default for signing |
| lockName | boolean (optional) | Whether or not the name field should be locked disallowing modifications |
| onDocumentReady | function (optional) | A callback function that will be called when the document is loaded and ready to be signed |
| onDocumentCompleted | function (optional) | A callback function that will be called when the document has been completed |
| onDocumentError | function (optional) | A callback function that will be called when an error occurs with the document |

77
apps/documentation/pages/developers/embedding/react.mdx Normal file
View File

@ -0,0 +1,77 @@
---
title: React Integration
description: Learn how to use our embedding SDK within your React application.
---
# React Integration
Our React SDK provides a simple way to embed a signing experience within your React application. It supports both direct link templates and signing tokens.
## Installation
To install the SDK, run the following command:
```bash
npm install @documenso/embed-react
```
## Usage
To embed a signing experience, you'll need to provide the token for the document you want to embed. This can be done in a few different ways, depending on your use case.
### Direct Link Template
If you have a direct link template, you can simply provide the token for the template to the `EmbedDirectTemplate` component.
```jsx
import { EmbedDirectTemplate } from '@documenso/embed-react';
const MyEmbeddingComponent = () => {
const token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
return <EmbedDirectTemplate token={token} />;
};
```
#### Props
| Prop | Type | Description |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| token | string | The token for the document you want to embed |
| host | string (optional) | The host to be used for the signing experience, relevant for self-hosters |
| name | string (optional) | The name the signer that will be used by default for signing |
| lockName | boolean (optional) | Whether or not the name field should be locked disallowing modifications |
| email | string (optional) | The email the signer that will be used by default for signing |
| lockEmail | boolean (optional) | Whether or not the email field should be locked disallowing modifications |
| externalId | string (optional) | The external ID to be used for the document that will be created upon completion |
| onDocumentReady | function (optional) | A callback function that will be called when the document is loaded and ready to be signed |
| onDocumentCompleted | function (optional) | A callback function that will be called when the document has been completed |
| onDocumentError | function (optional) | A callback function that will be called when an error occurs with the document |
| onFieldSigned | function (optional) | A callback function that will be called when a field has been signed |
| onFieldUnsigned | function (optional) | A callback function that will be called when a field has been unsigned |
### Signing Token
If you have a signing token, you can provide it to the `EmbedSignDocument` component.
```jsx
import { EmbedSignDocument } from '@documenso/embed-react';
const MyEmbeddingComponent = () => {
const token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
return <EmbedSignDocument token={token} />;
};
```
#### Props
| Prop | Type | Description |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| token | string | The token for the document you want to embed |
| host | string (optional) | The host to be used for the signing experience, relevant for self-hosters |
| name | string (optional) | The name the signer that will be used by default for signing |
| lockName | boolean (optional) | Whether or not the name field should be locked disallowing modifications |
| onDocumentReady | function (optional) | A callback function that will be called when the document is loaded and ready to be signed |
| onDocumentCompleted | function (optional) | A callback function that will be called when the document has been completed |
| onDocumentError | function (optional) | A callback function that will be called when an error occurs with the document |

77
apps/documentation/pages/developers/embedding/solid.mdx Normal file
View File

@ -0,0 +1,77 @@
---
title: Solid.js Integration
description: Learn how to use our embedding SDK within your Solid.js application.
---
# Solid.js Integration
Our Solid.js SDK provides a simple way to embed a signing experience within your Solid.js application. It supports both direct link templates and signing tokens.
## Installation
To install the SDK, run the following command:
```bash
npm install @documenso/embed-solid
```
## Usage
To embed a signing experience, you'll need to provide the token for the document you want to embed. This can be done in a few different ways, depending on your use case.
### Direct Link Template
If you have a direct link template, you can simply provide the token for the template to the `EmbedDirectTemplate` component.
```jsx
import { EmbedDirectTemplate } from '@documenso/embed-solid';
const MyEmbeddingComponent = () => {
const token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
return <EmbedDirectTemplate token={token} />;
};
```
#### Props
| Prop | Type | Description |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| token | string | The token for the document you want to embed |
| host | string (optional) | The host to be used for the signing experience, relevant for self-hosters |
| name | string (optional) | The name the signer that will be used by default for signing |
| lockName | boolean (optional) | Whether or not the name field should be locked disallowing modifications |
| email | string (optional) | The email the signer that will be used by default for signing |
| lockEmail | boolean (optional) | Whether or not the email field should be locked disallowing modifications |
| externalId | string (optional) | The external ID to be used for the document that will be created upon completion |
| onDocumentReady | function (optional) | A callback function that will be called when the document is loaded and ready to be signed |
| onDocumentCompleted | function (optional) | A callback function that will be called when the document has been completed |
| onDocumentError | function (optional) | A callback function that will be called when an error occurs with the document |
| onFieldSigned | function (optional) | A callback function that will be called when a field has been signed |
| onFieldUnsigned | function (optional) | A callback function that will be called when a field has been unsigned |
### Signing Token
If you have a signing token, you can provide it to the `EmbedSignDocument` component.
```jsx
import { EmbedSignDocument } from '@documenso/embed-solid';
const MyEmbeddingComponent = () => {
const token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
return <EmbedSignDocument token={token} />;
};
```
#### Props
| Prop | Type | Description |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| token | string | The token for the document you want to embed |
| host | string (optional) | The host to be used for the signing experience, relevant for self-hosters |
| name | string (optional) | The name the signer that will be used by default for signing |
| lockName | boolean (optional) | Whether or not the name field should be locked disallowing modifications |
| onDocumentReady | function (optional) | A callback function that will be called when the document is loaded and ready to be signed |
| onDocumentCompleted | function (optional) | A callback function that will be called when the document has been completed |
| onDocumentError | function (optional) | A callback function that will be called when an error occurs with the document |

79
apps/documentation/pages/developers/embedding/svelte.mdx Normal file
View File

@ -0,0 +1,79 @@
---
title: Svelte Integration
description: Learn how to use our embedding SDK within your Svelte application.
---
# Svelte Integration
Our Svelte SDK provides a simple way to embed a signing experience within your Svelte application. It supports both direct link templates and signing tokens.
## Installation
To install the SDK, run the following command:
```bash
npm install @documenso/embed-svelte
```
## Usage
To embed a signing experience, you'll need to provide the token for the document you want to embed. This can be done in a few different ways, depending on your use case.
### Direct Link Template
If you have a direct link template, you can simply provide the token for the template to the `EmbedDirectTemplate` component.
```html
<script lang="ts">
import { EmbedDirectTemplate } from '@documenso/embed-svelte';
const token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
</script>
<template>
<EmbedDirectTemplate {token} />
</template>
```
#### Props
| Prop | Type | Description |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| token | string | The token for the document you want to embed |
| host | string (optional) | The host to be used for the signing experience, relevant for self-hosters |
| name | string (optional) | The name the signer that will be used by default for signing |
| lockName | boolean (optional) | Whether or not the name field should be locked disallowing modifications |
| email | string (optional) | The email the signer that will be used by default for signing |
| lockEmail | boolean (optional) | Whether or not the email field should be locked disallowing modifications |
| externalId | string (optional) | The external ID to be used for the document that will be created upon completion |
| onDocumentReady | function (optional) | A callback function that will be called when the document is loaded and ready to be signed |
| onDocumentCompleted | function (optional) | A callback function that will be called when the document has been completed |
| onDocumentError | function (optional) | A callback function that will be called when an error occurs with the document |
| onFieldSigned | function (optional) | A callback function that will be called when a field has been signed |
| onFieldUnsigned | function (optional) | A callback function that will be called when a field has been unsigned |
### Signing Token
If you have a signing token, you can provide it to the `EmbedSignDocument` component.
```jsx
import { EmbedSignDocument } from '@documenso/embed-svelte';
const MyEmbeddingComponent = () => {
const token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
return <EmbedSignDocument token={token} />;
};
```
#### Props
| Prop | Type | Description |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| token | string | The token for the document you want to embed |
| host | string (optional) | The host to be used for the signing experience, relevant for self-hosters |
| name | string (optional) | The name the signer that will be used by default for signing |
| lockName | boolean (optional) | Whether or not the name field should be locked disallowing modifications |
| onDocumentReady | function (optional) | A callback function that will be called when the document is loaded and ready to be signed |
| onDocumentCompleted | function (optional) | A callback function that will be called when the document has been completed |
| onDocumentError | function (optional) | A callback function that will be called when an error occurs with the document |

79
apps/documentation/pages/developers/embedding/vue.mdx Normal file
View File

@ -0,0 +1,79 @@
---
title: Vue Integration
description: Learn how to use our embedding SDK within your Vue application.
---
# Vue Integration
Our Vue SDK provides a simple way to embed a signing experience within your Vue application. It supports both direct link templates and signing tokens.
## Installation
To install the SDK, run the following command:
```bash
npm install @documenso/embed-vue
```
## Usage
To embed a signing experience, you'll need to provide the token for the document you want to embed. This can be done in a few different ways, depending on your use case.
### Direct Link Template
If you have a direct link template, you can simply provide the token for the template to the `EmbedDirectTemplate` component.
```html
<script setup lang="ts">
import { EmbedDirectTemplate } from '@documenso/embed-vue';
const token = ref('YOUR_TOKEN_HERE'); // Replace with the actual token
</script>
<template>
<EmbedDirectTemplate :token="token" />
</template>
```
#### Props
| Prop | Type | Description |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| token | string | The token for the document you want to embed |
| host | string (optional) | The host to be used for the signing experience, relevant for self-hosters |
| name | string (optional) | The name the signer that will be used by default for signing |
| lockName | boolean (optional) | Whether or not the name field should be locked disallowing modifications |
| email | string (optional) | The email the signer that will be used by default for signing |
| lockEmail | boolean (optional) | Whether or not the email field should be locked disallowing modifications |
| externalId | string (optional) | The external ID to be used for the document that will be created upon completion |
| onDocumentReady | function (optional) | A callback function that will be called when the document is loaded and ready to be signed |
| onDocumentCompleted | function (optional) | A callback function that will be called when the document has been completed |
| onDocumentError | function (optional) | A callback function that will be called when an error occurs with the document |
| onFieldSigned | function (optional) | A callback function that will be called when a field has been signed |
| onFieldUnsigned | function (optional) | A callback function that will be called when a field has been unsigned |
### Signing Token
If you have a signing token, you can provide it to the `EmbedSignDocument` component.
```jsx
import { EmbedSignDocument } from '@documenso/embed-vue';
const MyEmbeddingComponent = () => {
const token = 'YOUR_TOKEN_HERE'; // Replace with the actual token
return <EmbedSignDocument token={token} />;
};
```
#### Props
| Prop | Type | Description |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| token | string | The token for the document you want to embed |
| host | string (optional) | The host to be used for the signing experience, relevant for self-hosters |
| name | string (optional) | The name the signer that will be used by default for signing |
| lockName | boolean (optional) | Whether or not the name field should be locked disallowing modifications |
| onDocumentReady | function (optional) | A callback function that will be called when the document is loaded and ready to be signed |
| onDocumentCompleted | function (optional) | A callback function that will be called when the document has been completed |
| onDocumentError | function (optional) | A callback function that will be called when an error occurs with the document |