External embeds

Learn to Embed a lucid diagram on another website

What is an external embed?

An external embed enables you to add a Lucid document directly in your webpage. This view-only version can be configured to automatically and near-instantly update whenever changes are made to the original Lucid document. Users can also interact with the Lucid document by zooming in and out or panning through the 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 view 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.

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.
• The embedded document picker available for the token-based embed enables your users to determine which document to embed.
• 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.
• Developers can configure token-based 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 only being viewable 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.
• 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?

• Lucid external embeds are view-only. Users are unable to edit the Lucid document directly in your webpage. Instead, Lucid embeds provide a button that users click to open the document in Lucid in a new tab and edit there, as long as they have edit permissions to the document.
• 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.
• Embedding a Team Space is not currently supported. Additionally, 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 https://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>. For example, toss the following code in a CodePen to try it out.

HTML

<p>Paste a Lucid link to see the document below!</p>
<iframe
  referrerpolicy="strict-origin"
  style="width: 700px; height: 500px;">
</iframe>

TypeScript

const lucidIframe = document.querySelector('iframe');
// make sure you register cdpn.io in your dev portal for this demo to work
const clientId = 'YOUR_CLIENT_ID';

document.addEventListener('paste', (event) => {
  const maybeUrl = event.clipboardData.getData('text/plain');
  if (maybeUrl.startsWith('https://lucid.app/')) {
    const iframeUrl = new URL('https://lucid.app/embeds/link');
    iframeUrl.searchParams.set('document', maybeUrl);
    iframeUrl.searchParams.set('clientId', clientId);
    lucidIframe.src = iframeUrl.toString();
  }
})

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

Token-based

A step-by-step guide to use the token-based OAuth 2.0 external embed is coming soon! 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.