@embeddedcanvas/embed-sdk

Embedded Canvas integrator SDK — mint workspace JWTs server-side, fetch embed sessions, mount white-label analytics dashboards.

Install

npm install @embeddedcanvas/embed-sdk @superset-ui/embedded-sdk
# React helper (optional):
npm install react

Monorepo: "@embeddedcanvas/embed-sdk": "workspace:*".

Migrating from @kepler/embed-sdk

The package was renamed in v1.0.0 with identical exports. Update imports only:

- import { mintEmbedJwt } from "@kepler/embed-sdk/jwt";
+ import { mintEmbedJwt } from "@embeddedcanvas/embed-sdk/jwt";

Path A — Analytics dashboard (recommended)

1. Server: session mint (embed API key)

Create an embed API key in Analytics → Connect your application. From your backend:

POST https://api.example.com/public/embed/v1/sessions
Authorization: Bearer ec_live_…
Content-Type: application/json

{ "embedToken": "…", "customerId": "1000" }

Expose the JSON to your frontend (BFF) — never put ec_live_… in the browser.

Or mint a workspace JWT server-side (@embeddedcanvas/embed-sdk/jwt) and pass jwt to the browser.

2. Browser: web component (default)

<div style="min-height: 70vh">
  <embedded-canvas-analytics
    api-base-url="https://api.example.com"
    embed-token="EMBED_TOKEN_FROM_ANALYTICS"
    customer-id="1000"
    session-url="/api/analytics/session"
    layout="chromeless"
  ></embedded-canvas-analytics>
</div>
<script type="module">
  import { registerEmbeddedCanvasAnalyticsElement } from "@embeddedcanvas/embed-sdk/web-component";
  registerEmbeddedCanvasAnalyticsElement();
</script>

JWT path: remove session-url and set jwt="…" from your backend.

3. Browser: React (alternative)

import { EmbeddedAnalytics } from "@embeddedcanvas/embed-sdk/react";

<EmbeddedAnalytics
  apiBaseUrl="https://api.example.com"
  embedToken="EMBED_TOKEN_FROM_ANALYTICS_PAGE"
  customerId={user.customerId}
  jwt={jwtFromYourBackend}
/>

4. Browser: vanilla mount (advanced)

import { mountAnalyticsEmbed } from "@embeddedcanvas/embed-sdk";

await mountAnalyticsEmbed({
  embedToken: "…",
  customerId: "1000",
  mountPoint: document.getElementById("analytics")!,
  fetchSession: () => fetch("/api/analytics/session").then((r) => r.json()),
  events: {
    onReady: () => console.log("embed ready"),
    onViewLimit: ({ message }) => alert(message),
  },
});

Handles session API → guest token refresh → @superset-ui/embedded-sdk with white-label UI defaults. See SDK.md for events (v1.1+), sizing (v1.2+), layout modes (v1.5+), host theme passthrough (v1.6+).

Host theme passthrough — inherit your app’s CSS variables into the embed shell:

<embedded-canvas-analytics … host-theme="inherit"></embedded-canvas-analytics>

await mountAnalyticsEmbed({ …, hostTheme: true });

Release history: CHANGELOG.md.

5. Hosted iframe (no SDK)

import { analyticsHostedEmbedUrl } from "@embeddedcanvas/embed-sdk";

const src = analyticsHostedEmbedUrl("https://app.example.com", embedToken, {
  customerId: "1000",
  jwt,
});
// <iframe src={src} />

Use your workspace custom embed domain as appBaseUrl when configured.

Session API (direct)

import {
  fetchAnalyticsEmbedSession,
  createEmbedSessionFetcher,
  EmbedSessionError,
} from "@embeddedcanvas/embed-sdk";

const session = await fetchAnalyticsEmbedSession({
  apiBaseUrl: "https://api.example.com",
  embedToken: "…",
  customerId: "1000",
  jwt,
});
// session.guestToken, session.supersetDomain, session.embedUiConfig, …

EmbedSessionError includes status and optional code (e.g. embed_view_limit).

Embed API keys (no JWT on your backend)

Use ec_live_… keys from the control plane with POST /public/embed/v1/sessions from your server. Pair with <embedded-canvas-analytics session-url="…"> on the frontend. See EMBED_API_KEYS.md.

Legacy chart embeds

Chart embeds use the same JWT helper with a chart id as sub:

const jwt = mintEmbedJwt({
  sub: chartId,
  signingKey: process.env.EMBEDDED_CANVAS_SIGNING_KEY!,
  ttlSeconds: 900,
  claims: { tenant_id: user.tenantId },
});

Iframe: https://app.example.com/embed/{embedToken}?jwt=…

Security

• Signing key and embed API keys: backend only, never in frontend bundles.
• JWT sub must match the dashboard/chart row id in the control plane.
• customer_id in query must match JWT when both are present (RLS binding).
• Production requires JWT on session API (isPublic is dev-only).

Related docs

• docs/embed/SDK.md — full integration guide
• docs/embed/WEB_COMPONENT_STARTER.html — reference page
• docs/embed/NPM_SDK.md — publish / release
• docs/embed/EMBED_GATEWAY.md
• docs/embed/WHITE_LABEL_EMBED.md