Tutorial: Cookie-based embeds

Lucid's Embed API enables you to display a Lucid document directly in your web page using an <iframe>, so users can view or edit the document directly without leaving your page.

Cookie-based embeds are easier to build than token-based embeds, but can only be viewed by Lucid users who have access to the document. For a more detailed comparison, see the Lucid Embed APIs overview.

This page will walk you through creating a cookie-based embed application, including a working example you can build in minutes!

Step 1: Create an application

1. Go to the developer portal
2. Create a new application
3. Create an OAuth2 client
4. Register your authorized embedding domains. For now, so you can 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

After 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 this URL: https://lucid.app/embeds/link?clientId=<client ID>&document=<URL-encoded Lucid document URL>.

For a quick example, toss the following code in a CodePen to try out the API. (Make sure you registered cdpn.io as an Authorized Domain in the developer portal.)

<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: 800px; height: 600px;">
  </iframe>
</div>

const lucidIframe = document.getElementById('lucid-iframe');
const linkInput = document.getElementById('lucid-link-input');

// Replace this with your client ID from the developer portal
const clientId = 'YOUR_CLIENT_ID';

linkInput.addEventListener('input', () => {
  const documentUrl = linkInput.value;
  if (documentUrl.startsWith('https://lucid.app/')) {
    const iframeUrl = new URL('https://lucid.app/embeds/link');
    // this URL-encodes the document URL
    iframeUrl.searchParams.set('document', documentUrl);
    iframeUrl.searchParams.set('clientId', clientId);
    lucidIframe.src = iframeUrl.href;
  }
});

If a user views the embed who doesn't have access to the document, they will be able to accept the share link (if applicable) or request access to the document.

(If you would like any user to be able to view the document, even if they don't have a Lucid account, you'll need to use a token-based embed instead. See Tutorial: Token-based embeds.)

Note that the host page's domain must be present in your client's "Authorized Embedding Domains" list, and the browser must send a referrer header when loading the iframe. (That's why the demo above includes referrerpolicy="strict-origin".)

Step 3 (optional): Embedding a document editor

By default, cookie-based embeds present the document in a lightweight view-only mode. If you want to embed a full interactive editor, add mode=editor to the URL. For example, add this to your CodePen from the previous step:

iframeUrl.searchParams.set('mode', 'editor');

Just like view-only embeds, the embedded editor limits access to whatever permission the user already has for that document. If the user only has View or Comment access, the embedded editor will be restricted accordingly.