Developers
Embedding a demo
An embed puts a working AI demo — a receptionist you can call, a chat agent, a website audit — inside any web page. It runs in an iframe on the agency's own domain, so it cannot affect the page it sits in and the page cannot affect it.
Install
Paste both lines where the demo should appear. The div is the container; the script finds it and fills it.
<div data-lumina-embed="emb_yourkeyhere"
data-lumina-mode="inline"
data-lumina-theme="auto"></div>
<script src="https://yoursubdomain.luminasales.io/embed.js" async></script>The exact snippet, with your key already in it, is on the embed's card in the Lumina dashboard. Copy it from there rather than editing the example.
Floating bubble
A bubble attaches itself to the page, so there is no container — the key goes on the script tag and the whole thing is one line. Put it once in the site's shared layout.
<script src="https://yoursubdomain.luminasales.io/embed.js"
data-lumina-embed="emb_yourkeyhere"
data-lumina-mode="bubble"
data-lumina-position="bottom-right"
data-lumina-label="Talk to our AI"
async></script>Without a script tag
Some site builders will not allow one. A plain iframe works, at the cost of the automatic height — you pick a number and live with it.
<iframe src="https://yoursubdomain.luminasales.io/e/emb_yourkeyhere"
title="Live AI demo"
height="620"
style="border:0;width:100%"
allow="microphone"
loading="lazy"></iframe>Nothing renders. What now?
Almost always one of four things, in roughly this order of likelihood.
1. The domain is not on the allowed list
An embed renders only on domains you have listed for it. The browser enforces that with frame-ancestors, so an unlisted page gets nothing at all — no error in your code, just empty space. Open the embed in Lumina: refused domains are listed on its card, and the one you are looking at is usually right there.
Watch for the near-misses. A staging domain, a Vercel or Netlify preview URL, and www. versus bare are all different origins. So is http://localhost:3000 versus https://.
*.acme.com covers app.acme.com and deep.app.acme.com, but not acme.com itself. That is the CSP rule browsers use, and we match it exactly so that the two never disagree. If you need both, list both.2. The frame is sandboxed
A sandbox attribute makes the browser send a null origin, which cannot be matched against any allowed list. Remove it. Some tag managers and CMS plugins add it without saying so.
3. A parent element is clipping it
The demo measures itself and posts its height out to the loader. An ancestor with overflow: hidden or a fixed height will clip the result and it will look cut off with nothing in the console.
4. The demo is out of budget, or the plan lapsed
Each embed has its own spend ceiling, and the account has a monthly one. When an embed is out of budget the interactive part shows a short neutral message and the rest of the page keeps working. When the subscription lapses the frame collapses to nothing instead — a stranger on your client's site should not be reading about your billing.
Options
Set on the container (inline) or on the script tag (bubble). Everything except the key has a sensible default and can be left out.
| Attribute | Values | What it does |
|---|---|---|
| data-lumina-embed | emb_… | The embed key. Required. |
| data-lumina-mode | inline · bubble | Where it sits. Must match the mode set in Lumina. |
| data-lumina-theme | auto · light · dark | auto follows the visitor's system setting. Set it explicitly if your site does not. |
| data-lumina-max-width | 280–1400 | Caps the width inside a wide container. Inline only. |
| data-lumina-position | bottom-right · bottom-left | Which corner. Bubble only. |
| data-lumina-label | text | The launcher button's text. Bubble only. |
Reacting to it from your own page
The loader exposes window.LuminaEmbed. Use it to send events into your own analytics, or to mount an embed you added after page load.
LuminaEmbed.on("call_started", function (e) {
// e.key is the embed that fired it
gtag("event", "ai_demo_call_started", { embed: e.key });
});
LuminaEmbed.on("interaction", function () { /* first touch */ });
LuminaEmbed.on("resize", function (e) { /* e.height */ });
// After injecting a new container into the DOM:
LuminaEmbed.refresh();| Event | When |
|---|---|
| ready | The demo has loaded and is interactive. |
| resize | Its height changed. The loader already applied it. |
| interaction | The visitor's first click or keypress inside the demo. |
| call_started | A voice call connected. |
| call_ended | The call finished or was hung up. |
| open / close | The bubble was opened or closed. |
LuminaEmbed.off(event, handler) removes a handler and LuminaEmbed.destroy() removes every frame — useful in a single-page app when the route changes.
Per platform
WordPress
Use a Custom HTML block for the inline version. For a bubble, add the script tag to the theme's footer, or use a header-and-footer-scripts plugin. Do not paste it into a classic-editor text field — WordPress strips script tags there.
Webflow
Drag in an Embed element for inline. For a bubble, put the script in Project Settings → Custom Code → Footer Code. Note that custom code only runs on the published site, not in the Designer canvas.
Squarespace
A Code Block works on business plans and above. On lower plans, use the plain-iframe snippet in a Code Block instead — script injection is a paid feature there.
Shopify
Add a Custom Liquid section for inline, or put the bubble script in theme.liquid before </body>.
React, Next.js, Vue
Render the container as normal markup and load the script once. In React, the loader runs on mount and the container is already in the DOM, so the ordering works out — but call LuminaEmbed.refresh() after a client-side route change that mounts a new container.
useEffect(() => {
const script = document.createElement("script");
script.src = "https://yoursubdomain.luminasales.io/embed.js";
script.async = true;
document.body.appendChild(script);
return () => { window.LuminaEmbed?.destroy(); script.remove(); };
}, []);What the script does, and does not
It creates one iframe per container, listens for a height message from that iframe, and exposes the event API above. That is all of it.
It does not read or write cookies, local storage, or anything else on the host page; it does not read form fields or page content; and it sends nothing from the host page anywhere. The demo itself runs in a cross-origin iframe, which means it has no access to the surrounding document even if it wanted one. The script is served unminified — read it at /embed.js.
About the key
The emb_… key is not a secret. It ships inside the HTML of a public page and is meant to. Do not move it into an environment variable or proxy requests through your own server to hide it — it is an address, not a credential.
What protects the embed is the allowed-domain list, which the browser enforces, plus the per-embed spend budgets. If a key ends up somewhere you would rather it did not, rotate it from the Lumina dashboard; every existing snippet stops working and you reinstall the new one.
