External embeds

What is an external embed?

An external embed enables you to add a Lucid document directly in your webpage. This document version behaves as if you are editing or viewing the document in the Lucid app. Users can interact with the Lucid document by zooming in and out or panning through the document. Depending on the embed configuration, the embed can be made editable or view-only, and can be made to automatically sync updates with the original document.

Embed types

Lucid's API offers two solutions for external embeds: token-based and cookie-based. With our token-based embed solution, anyone with access to your webpage can access the document, even if they don't have a Lucid account. With our cookie-based embed solution, a user is required to be a collaborator on the document in order to view the embed in your webpage. Both types of embed allow for view-only or editable documents, however snapshots are only available through token-based embeds.

Token-based

• Choose this solution when you want users on your webpage to see Lucid documents, even if they don't have access to the document in Lucid or even a Lucid account.
• This solution relies on the OAuth 2.0 authentication standard: Any user adding a Lucid document to your webpage will first be asked whether they give permission to your application to do so.
• As part of this solution, Lucid provides a document picker component. Your app can incorporate this component to enable users to select which Lucid document to embed.
• Embedded documents can be made editable or view-only. Editable embeds always sync changes with the original document.
• Developers can configure token-based view-only embeds to either stay up-to-date with any changes made to the Lucid document or to always be a static snapshot reflecting what the document looked like at the time it was inserted.

Cookie-based

• Choose this solution if you're prioritizing a fast development cycle and if you're comfortable with the embed being accessible only by users who have permission to view the document in Lucid.
• This solution is designed for a user to copy the Lucid URL of a document and paste it into your web application. Your application would then call Lucid's API and display the embedded viewer. Please note that no document picker is available with our cookie-based embed.
• The user must be logged in to Lucid to view the embed in your webpage. This is because the embed utilizes browser cookies to authorize displaying the embedded document in your webpage.
• The user must have permission to view the Lucid document to view the document in your webpage. If a user's view permissions to the document is removed, the embed will no longer be visible on your webpage.
• Cookie-based embeds always update when changes are made to the original document.
• This is the simplest type of embed to build, as it only requires you to hit one endpoint in an iframe. It's also the simplest to use as the user only needs to copy and paste the Lucid document's URL.

What are the limitations of external embeds?

• The document picker (part of the token-based solution) and cookie-based solution both require third-party cookies to be enabled in the browser. Some browsers disable these cookies by default. Information on enabling third-party cookies can be found here: Enabling third party cookies.
• Although Lucidspark breakout boards can be embedded, they are not selectable via the document picker.
• While the token-based embedded experience provides a document picker, there is no document picker available for cookie-based embeds.
• The token-based embedded experience requires your integration to manage the granting and storage of OAuth 2.0 tokens securely. Cookie-based embeds do not require any token management. When viewing a cookie-based embed, users who do not have access will see a login or request-access screen instead.

Examples of external embed implementations:

• Simple Cookie-based Embed
• Asana
• Canvas
• Confluence
• Google Docs
• Jira
• LeanIX
• Orbus
• Slack

Technical documentation

Cookie-based

Step 1: Create an application

1. Go to the developer portal
2. Create a new application
3. Create an OAuth2 client
4. Register the authorized embedding domain. To try it out in Codepen, put cdpn.io in the list.
5. Grab your client ID. You’ll need it in the next step!

Step 2: Embedding Lucid links in your app

If you have a Lucid document URL (such as from a customer pasting it) and you want to embed it in your app,
you can use an iframe with the URL https://lucid.app/embeds/link?clientId=<client ID>&document=<URL-encoded Lucid document URL>&mode=editor. For example, toss the following code in a CodePen to try it out.

<div>
  <input id="lucid-link-input" type="text" placeholder="Paste a Lucid link to see the document below!" style="width: 700px;"/>
</div>
<div>
  <iframe
    referrerpolicy="strict-origin"
    style="width: 700px; height: 500px;">
  </iframe>
</div>

const lucidIframe = document.querySelector('iframe');
const linkInput = document.getElementById('lucid-link-input');
// make sure you register cdpn.io in your dev portal for this demo to work
const clientId = 'YOUR_CLIENT_ID';
const mode = 'editor';

linkInput.addEventListener('input', () => {
  const maybeUrl = linkInput.value;
  if (maybeUrl.startsWith('https://lucid.app/')) {
    const iframeUrl = new URL('https://lucid.app/embeds/link');
		// make sure the Lucid document url is URL-encoded
    iframeUrl.searchParams.set('document', maybeUrl);
    iframeUrl.searchParams.set('clientId', clientId);
    iframeUrl.searchParams.set('mode', mode);
    lucidIframe.src = iframeUrl.toString();
  }
});

The embed will use the share settings on the link that was pasted.

Token-based

Step 1: Create an application

1. Go to the developer portal.
2. Create a new application.
3. Create an OAuth2 client.
4. Grab your client ID and client secret. You’ll need it in the next step!

Step 2: Obtain an access token

Use Lucid's APIs to obtain an access token, which will be used in step 3. Reference the generate embed session token endpoint to see which scopes your token needs.

Step 3: Create an embed session token

Use Lucid's APIs to obtain an embed session token. Because the embed session token is short-lived, you should generate a new one whenever your app is reloaded. To view an existing embed, the embed ID should be included in the request body. To just load the document picker component and create a new embed, an embed ID is not needed.

Step 4: Embed Lucid links in your app

To display an embed viewer, use an iframe with the URL https://lucid.app/embeds?token=<embed session token from step 3>

How to use the document picker component

For creating embeds, Lucid provides a document picker component where users can select an existing document from one of their folders, create a blank document, or explore hundreds of templates.

After selecting a file, the user clicks the Continue button.

Next, the user can select the type of access other users will have when viewing the document embed. In Access Settings, the user clicks one of the following options: Edit, Comment only, or View only. If Edit is selected, other users will be able to edit the embedded Lucid document in a collaborative way without leaving your app.

If the user selects the View only access setting, they can also choose which pages to display as well as the viewer type. While the Rich Viewer provides a fully-functional view with interactive elements and high-fidelity zooming, the Simple Viewer provides a basic, fast-loading view without interactivity or high-fidelity zooming.

By default, the embedded document will show the latest document state every time your app embeds the document. To disable the auto update feature, the embedding user can deselect the Automatically update the document when the integration loads checkbox.

Finally, the user clicks the Insert button to finish creating the embed.

After an embed is created, the embed iframe will fire an EmbedCreated event that contains the embed ID for the created embed. It is important to store the embed ID in your app. In order to load an existing embed, the embed ID is required when requesting a new embed session token in step 3 above.

If you're looking to create an external embed that's available to everyone, sign up here to be a technology partner! We'd love to learn more about how you use Lucid and take our partnership to the next level.

For additional access or technical questions, please contact us in our Lucid developer forum.