Integrator quickstarts

Audience: Engineers embedding dashboards

Step-by-step walkthrough: Hello World React embed — BFF, Vite host, tenant filters, and CSP (full tutorial in Help).

Runnable examples are available in our integrator quickstarts.

Sample SaaS app

Full deployable Next.js host: tenant sign-in, httpOnly cookie, BFF session route, embedded dashboard, tenant switcher, Docker + Vercel notes.

→

cd packages/embed-sdk && pnpm build
cd examples/integrator/sample-saas
cp .env.example .env.local # EMBED_API_KEY, EMBED_TOKEN, API URL
npm install && npm run dev # http://localhost:3100

Use this as the end-to-end reference; smaller snippets below are extracted patterns.

React

Vite + <EmbeddedAnalytics /> with BFF fetchSession.

→

# Terminal 1 — BFF
cd examples/integrator/node-bff && cp .env.example .env && node --env-file=.env server.mjs

# Terminal 2 — UI
cd packages/embed-sdk && pnpm build
cd examples/integrator/react && pnpm install && pnpm dev

Next.js

App Router route app/api/analytics/session/route.ts + client embed component.

→

Copy app/ files into your Next.js project. Set EMBED_API_KEY, EMBED_TOKEN, EMBEDDED_CANVAS_API_URL in .env.local.

Node BFF

Standalone session mint — use with any frontend.

→

POST /api/analytics/session
Content-Type: application/json

{ "customerId": "CUST-1004" }

Proxies to POST /public/embed/v1/sessions with Authorization: Bearer ec_live_….

Plain HTML

Web component + session-url — Vue, Angular, Svelte, or static sites.

→

<embedded-canvas-analytics
 embed-token="EMBED_TOKEN"
 customer-id="CUST-1004"
 session-url="/api/analytics/session"
 layout="chromeless"
></embedded-canvas-analytics>

Error codes

Session and mount failures return JSON { error, code }. The SDK maps these to host-visible panels (no blank iframe):

`code`	Meaning
`jwt_expired`	Workspace JWT expired — mint a new one server-side
`tenant_mismatch`	`customerId` ≠ JWT claim
`missing_origin`	App URL not on dual allowlist
`runtime_unavailable`	Runtime not provisioned / inactive
`runtime_outage`	Runtime unreachable right now
`warehouse_timeout`	Warehouse query timeout
`permission_denied`	DB user cannot read mart data
`catalog_not_entitled`	Tenant not entitled to dashboard

Full list: @embeddedcanvas/embed-sdk → EMBED_ERROR_CODES.

Production security

Before pilot cutover:

Secrets — embed API key and signing key server-only
Tenant binding — derive customerId from auth on the BFF
Dual allowlist — staging + prod origins in Analytics and runtime builder
CSP — frame-src + connect-src for runtime and API (Security & CSP)
Token TTL — short JWTs; SDK refreshes guest tokens automatically (autoRefreshToken, default on)
Tenant switch — React customerId prop or controller.setCustomerId; web component customer-id attribute
Responsive iframe — SDK sizes iframe to mount container by default (resize: true)