Developers
Embed JavaScript API
The loader script exposes window.LuminaEmbed on the page it runs on. Use it to feed demo activity into your own analytics, or to control embeds in a single-page app.
Availability
window.LuminaEmbed exists as soon as /embed.js has executed. The script is loaded async, so on a page that scripts against it immediately, guard the access.
function whenReady(fn) {
if (window.LuminaEmbed) return fn(window.LuminaEmbed);
document.addEventListener("DOMContentLoaded", function () {
if (window.LuminaEmbed) fn(window.LuminaEmbed);
});
}Methods
| Method | What it does |
|---|---|
| on(event, handler) | Subscribe. The handler receives an object with the key of the embed that fired it. |
| off(event, handler) | Unsubscribe the same function reference. |
| refresh() | Mount any container added to the DOM since load. Safe to call repeatedly — an already-mounted container is skipped. |
| destroy() | Remove every frame and drop every handler. Use it when a single-page app leaves the route. |
Events
| Event | Fires when | Payload |
|---|---|---|
| ready | The demo has loaded and is interactive. | { key } |
| resize | Its height changed. The loader has already applied it. | { key, height } |
| interaction | The visitor's first click or keypress inside the demo. Fires once per load. | { key } |
| call_started | A voice call connected. | { key } |
| call_ended | The call finished or was hung up. | { key } |
| lead | The visitor submitted their details. | { key } |
| open / close | The bubble was opened or closed. | { key } |
Example: send demo activity to your analytics
whenReady(function (Lumina) {
Lumina.on("interaction", function (e) {
gtag("event", "ai_demo_engaged", { embed: e.key });
});
Lumina.on("call_started", function (e) {
gtag("event", "ai_demo_call", { embed: e.key });
});
});Example: a single-page app
// On route enter, after the container is in the DOM:
window.LuminaEmbed?.refresh();
// On route leave:
window.LuminaEmbed?.destroy();Messages, if you would rather not use the wrapper
Underneath, each frame posts to its parent. Every message carries source: "lumina-embed", which is how you tell ours apart from every other widget on the page.
window.addEventListener("message", function (event) {
if (event.origin !== "https://yoursubdomain.luminasales.io") return;
if (!event.data || event.data.source !== "lumina-embed") return;
// event.data.type is one of the events in the table above
});event.origin first. Any page on the internet can post a message into yours, and a handler that trusts event.data.source alone is trusting a string an attacker chose.Creating and managing embeds
This script only runs embeds on a page. To create embeds, change their allowed domains or budgets, or fetch the install snippet from your own code, use the REST API (the embeds resources) or the MCP server. In the dashboard, Lumina Assistant can do all of it for you, including writing the snippet.
