The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
docs(sdk): add statically generated docs/llms.txt (#67506)
Phoomparin Manodd830db3926b
diff --git a/docs/llms.txt b/docs/llms.txtnew file mode 100644index 00000000000..e7f13671d69--- /dev/null+++ b/docs/llms.txt@@ -0,0 +1,1264 @@+# Metabase Modular Embedding Reference++> Complete guide for embedding Metabase charts, dashboards, query builder, and AI chat into your applications.++## Overview++Metabase offers two primary ways to embed analytics:++1. **Modular Embedding JS** - Embed individual components (dashboards, questions, query builder, AI chat) with full customization+2. **Modular Embedding SDK** - React SDK for advanced embedding with custom layouts and plugins++### When to Use Modular Embedding++- **SSO Embeds**: Multi-tenant self-service analytics with drill-through, query builder, and AI chat. Requires JWT or SAML authentication.+- **Guest Embeds**: Simple, secure charts and dashboards without SSO. View-only with locked parameters for data filtering.++### Feature Comparison++| Feature | SSO | Guest | SDK |+|---------|-----|-------|-----|+| Charts & Dashboards | ✅ | ✅ | ✅ |+| Drill-through | ✅ | ❌ | ✅ |+| Query Builder | ✅ | ❌ | ✅ |+| AI Chat (Metabot) | ✅ | ❌ | ✅ |+| Collection Browser | ✅ | ❌ | ✅ |+| Advanced Theming | ✅ | ❌ | ✅ |+| Custom Layouts | ❌ | ❌ | ✅ |+| Plugins | ❌ | ❌ | ✅ |+| Data Permissions | ✅ | ❌ | ✅ |++---++## Quick Start Paths++### Path 1: Simple Web Components (No React Required)++Best for: Adding analytics to any web app with minimal code.++```html+<!-- Load embedding library -->+<script defer src="https://your-metabase-url/app/embed.js"></script>++<script>+ defineMetabaseConfig({+ instanceUrl: "https://your-metabase-url",+ apiKey: "mb_dev_api_key", // For local testing only+ theme: {+ colors: {+ brand: "#9B5966",+ background: "#FFFFFF"+ }+ }+ });+</script>++<!-- Embed a dashboard -->+<metabase-dashboard dashboard-id="1" with-title="true"></metabase-dashboard>++<!-- Embed a question -->+<metabase-question question-id="5"></metabase-question>+```++### Path 2: React SDK (Advanced)++Best for: React apps needing custom layouts, plugins, and full control.++```bash+# Install (use dist-tag matching your Metabase version)+npm install @metabase/embedding-sdk-react@58-stable+```++```tsx+import { MetabaseProvider, StaticDashboard } from "@metabase/embedding-sdk-react";++function App() {+ return (+ <MetabaseProvider+ authConfig={{+ metabaseInstanceUrl: "https://your-metabase-url",+ apiKey: "mb_dev_api_key" // For local testing only+ }}+ >+ <StaticDashboard dashboardId={1} />+ </MetabaseProvider>+ );+}+```++---++## Authentication++### Development: API Keys (localhost only)++```javascript+// Web components+defineMetabaseConfig({+ instanceUrl: "https://your-metabase-url",+ apiKey: "mb_your_api_key"+});++// React SDK+authConfig={{+ metabaseInstanceUrl: "https://your-metabase-url",+ apiKey: "mb_your_api_key"+}}+```++**⚠️ API keys only work on localhost and should never be used in production.**++### Production: JWT SSO (Requires Pro/Enterprise)++**⚠️ Important:** The SDK automatically uses the JWT endpoint configured in Metabase Admin settings. You don't need `fetchRequestToken` unless you require custom headers/auth.++#### Backend Setup (Node.js example)++```javascript+const jwt = require("jsonwebtoken");++app.get("/sso/metabase", async (req, res) => {+ const user = getCurrentUser(req);++ const token = jwt.sign(+ {+ email: user.email,+ first_name: user.firstName,+ last_name: user.lastName,+ groups: [user.group],+ exp: Math.round(Date.now() / 1000) + 60 * 10 // 10 min expiration+ },+ METABASE_JWT_SHARED_SECRET+ );++ // For SDK requests (check for response=json query param)+ if (req.query.response === "json") {+ res.status(200).json({ jwt: token });+ } else {+ // For full app embedding+ const ssoUrl = `${METABASE_INSTANCE_URL}/auth/sso?token=true&jwt=${token}`;+ res.redirect(ssoUrl);+ }+});+```++#### Frontend Configuration++```tsx+// React SDK+import { defineMetabaseAuthConfig } from "@metabase/embedding-sdk-react";++// ✅ CORRECT - Default setup (works for most cases)+const authConfig = defineMetabaseAuthConfig({+ metabaseInstanceUrl: "https://your-metabase-url"+ // SDK automatically uses JWT endpoint configured in Metabase admin+ // No fetchRequestToken needed!+});++// ❌ DEPRECATED - DO NOT USE+const authConfig = defineMetabaseAuthConfig({+ metabaseInstanceUrl: "https://your-metabase-url",+ authProviderUri: "..." // REMOVED - configure in Metabase admin instead+});+```++### Production: SAML SSO (Requires Enterprise)++```tsx+const authConfig = defineMetabaseAuthConfig({+ metabaseInstanceUrl: "https://your-metabase-url",+ preferredAuthMethod: "saml"+});+```++### Guest Embeds (No User Accounts Required)++Backend generates signed JWT tokens containing resource ID and locked parameters:++```javascript+const jwt = require("jsonwebtoken");++const payload = {+ resource: { dashboard: 10 }, // or { question: 5 }+ params: { category: ["Gizmo"] }, // Locked parameters+ exp: Math.round(Date.now() / 1000) + 10 * 60+};++const token = jwt.sign(payload, METABASE_SECRET_KEY);+```++Frontend:++```html+<script>+ defineMetabaseConfig({+ isGuest: true,+ instanceUrl: "https://your-metabase-url"+ });+</script>++<metabase-dashboard token="YOUR_JWT_TOKEN"></metabase-dashboard>+```++**⚠️ Never hardcode tokens in HTML. Fetch from your backend dynamically.**++## ⚠️ Common Gotchas for Code Generation++### 1. Deprecated Props (DO NOT USE)+- ❌ `authProviderUri` - DEPRECATED, remove from all code+- ❌ `jwtProviderUri` - DEPRECATED, remove from all code+- ❌ `config` prop on MetabaseProvider - DEPRECATED, use `authConfig` instead++### 2. fetchRequestToken Usually Not Needed+**DON'T add `fetchRequestToken` unless explicitly needed for custom headers/auth.**++The SDK automatically fetches tokens from the JWT endpoint configured in Metabase Admin settings. Adding `fetchRequestToken` unnecessarily can break backend code that handles legacy interactive embedding redirects, especially if you forget to pass `response=json` in the request.++**Only use `fetchRequestToken` when:**+- You need custom headers (e.g., `Authorization: Bearer ${token}`)+- You need custom fetch logic beyond the default++**Default behavior (works for most cases):**+```tsx+const authConfig = defineMetabaseAuthConfig({+ metabaseInstanceUrl: "https://your-metabase-url"+ // No fetchRequestToken needed - SDK uses admin-configured JWT endpoint+});+```++**Custom fetchRequestToken (only when needed):**+```tsx+const authConfig = defineMetabaseAuthConfig({+ metabaseInstanceUrl: "https://your-metabase-url",+ fetchRequestToken: async () => {+ const response = await fetch("https://your-backend/sso/metabase", {+ headers: { "Authorization": `Bearer ${yourToken}` }+ // SDK adds ?response=json automatically+ });+ return await response.json();+ }+});+```++### 3. Numeric IDs Must Be Integers, Not Strings+**ALWAYS parse URL parameters and strings to integers using `parseInt()`.**++```tsx+// ❌ WRONG - String IDs will cause errors+const dashboardId = searchParams.get("id"); // "123" (string)+<StaticDashboard dashboardId={dashboardId} /> // ERROR!++// ✅ CORRECT - Parse to integer+const dashboardId = parseInt(searchParams.get("id"), 10); // 123 (number)+<StaticDashboard dashboardId={dashboardId} /> // Works!++// ✅ Also works with entity IDs (strings starting with letters)+const dashboardId = searchParams.get("id"); // "abc123def"+<StaticDashboard dashboardId={dashboardId} /> // Works!+```++**Rule of thumb:**+- Numeric IDs (e.g., `123`): Must be `number` type → use `parseInt(value, 10)`+- Entity IDs (e.g., `"abc123def"`): Must be `string` type → use as-is++---++## React SDK Components++### Dashboards++#### StaticDashboard+Lightweight, view-only dashboard.++```tsx+import { StaticDashboard } from "@metabase/embedding-sdk-react";++<StaticDashboard+ dashboardId={123}+ withTitle={true}+ withDownloads={false}+ initialParameters={{ productId: 42 }}+ hiddenParameters={["category"]}+/>+```++#### InteractiveDashboard+Dashboard with drill-downs, click behaviors, and question navigation.++```tsx+import { InteractiveDashboard } from "@metabase/embedding-sdk-react";++<InteractiveDashboard+ dashboardId={123}+ withTitle={true}+ withDownloads={true}+ plugins={{+ dashboardCardMenu: {+ withDownloads: true,+ withEditLink: false,+ customItems: [+ {+ label: "Custom Action",+ icon: "info",+ action: (question) => console.log(question)+ }+ ]+ }+ }}+/>+```++#### EditableDashboard+Fully editable dashboard with add/edit/layout capabilities.++```tsx+import { EditableDashboard } from "@metabase/embedding-sdk-react";++<EditableDashboard+ dashboardId={123}+ onSave={(dashboard) => console.log("Saved:", dashboard)}+/>+```++### Questions++#### StaticQuestion+Lightweight, view-only question/chart.++```tsx+import { StaticQuestion } from "@metabase/embedding-sdk-react";++<StaticQuestion+ questionId={456}+ height="400px"+ initialSqlParameters={{ productId: 42 }} // For SQL questions only+/>+```++#### InteractiveQuestion+Question with filters, summarize, drill-through, and query builder.++```tsx+import { InteractiveQuestion } from "@metabase/embedding-sdk-react";++// Default layout+<InteractiveQuestion questionId={456} />++// Custom layout with namespaced components+<InteractiveQuestion questionId={456}>+ <InteractiveQuestion.Title />+ <InteractiveQuestion.Filter />+ <InteractiveQuestion.Summarize />+ <InteractiveQuestion.QuestionVisualization />+ <InteractiveQuestion.SaveButton />+</InteractiveQuestion>+```++#### Query Builder (New Question)++```tsx+<InteractiveQuestion questionId="new">+ <InteractiveQuestion.Editor />+ <InteractiveQuestion.QuestionVisualization />+ <InteractiveQuestion.SaveButton />+</InteractiveQuestion>+```++### AI Chat (Metabot)++Embed AI-powered natural language querying.++```tsx+import { MetabotQuestion } from "@metabase/embedding-sdk-react";++<MetabotQuestion+ collectionId={7} // Scope AI to specific collection+ layout="sidebar" // "auto" | "stacked" | "sidebar"+/>+```++### Collection Browser++Let users navigate and explore Metabase collections.++```tsx+import { CollectionBrowser } from "@metabase/embedding-sdk-react";++<CollectionBrowser+ initialCollectionId="root"+ readOnly={false}+ visibleEntityTypes={["dashboard", "question"]}+/>+```++### Create Dashboard Modal++```tsx+import { CreateDashboardModal } from "@metabase/embedding-sdk-react";++<CreateDashboardModal+ collectionId={7}+ onClose={() => setIsOpen(false)}+ onCreate={(dashboard) => console.log("Created:", dashboard)}+/>+```++---++## Web Component Reference++### Dashboard Component++```html+<metabase-dashboard+ dashboard-id="1" <!-- Required: ID or entity ID -->+ with-title="true" <!-- Show title (default: true) -->+ with-downloads="false" <!-- Enable downloads (default: false) -->+ drills="true" <!-- Enable drill-through (default: true) -->+ with-subscriptions="false" <!-- Enable subscriptions -->+ refresh="60" <!-- Auto-refresh in seconds -->+ initial-parameters='{"productId": "42"}'+ hidden-parameters='["category"]'+></metabase-dashboard>+```++### Question Component++```html+<metabase-question+ question-id="5" <!-- Required: ID or entity ID, or "new" -->+ with-title="true" <!-- Show title (default: true) -->+ with-downloads="false" <!-- Enable downloads (default: false) -->+ drills="true" <!-- Enable drill-through (default: true) -->+ initial-sql-parameters='{"productId": "42"}' <!-- SQL questions only -->+ is-save-enabled="false" <!-- Allow saving -->+ target-collection="personal" <!-- Force save location -->+></metabase-question>+```++### Browser Component++```html+<metabase-browser+ initial-collection="root" <!-- Required: collection ID or "root" -->+ read-only="false" <!-- Allow create/edit (default: true) -->+></metabase-browser>+```++### AI Chat Component++```html+<metabase-metabot+ layout="auto" <!-- "auto" | "stacked" | "sidebar" -->+></metabase-metabot>+```++---++## Theming and Appearance++### Complete Theme Object++```javascript+{+ fontFamily: "Lato", // or "Custom" for Metabase custom font+ fontSize: "16px",+ lineHeight: 1.5,++ colors: {+ // Primary colors+ brand: "#9B5966",+ "brand-hover": "#DDECFA",+ "brand-hover-light": "#EEF6FC",++ // Text colors+ "text-primary": "#4C5773",+ "text-secondary": "#696E7B",+ "text-tertiary": "#949AAB",++ // Background colors+ background: "#FFFFFF",+ "background-light": "#F0F2F5",+ "background-secondary": "#EDF2F5",+ "background-hover": "#F9FBFC",+ "background-disabled": "#F3F5F7",++ // UI elements+ border: "#EEECEC",+ filter: "#7172AD",+ summarize: "#88BF4D",+ positive: "#BADC58",+ negative: "#FF7979",+ focus: "#CAE1F7",+ shadow: "rgba(0,0,0,0.08)",++ // Chart colors (up to 8)+ charts: [+ "#9B59B6",+ { base: "#E74C3C", tint: "#EE6B56", shade: "#CB4436" }+ ]+ },++ components: {+ dashboard: {+ backgroundColor: "#2F3640",+ gridBorderColor: "#EEECEC",+ card: {+ backgroundColor: "#2D2D30",+ border: "1px solid #EEECEC"+ }+ },++ question: {+ backgroundColor: "#2E353B",+ toolbar: {+ backgroundColor: "#F3F5F7"+ }+ },++ tooltip: {+ textColor: "#FFFFFF",+ secondaryTextColor: "#949AAB",+ backgroundColor: "#2E353B",+ focusedBackgroundColor: "#0A0E10"+ },++ table: {+ cell: {+ textColor: "#4C5773",+ backgroundColor: "#FFFFFF",+ fontSize: "12.5px"+ },+ idColumn: {+ textColor: "#9B5966",+ backgroundColor: "#F5E9EB"+ }+ },++ number: {+ value: {+ fontSize: "24px",+ lineHeight: "21px"+ }+ },++ cartesian: {+ padding: "4px 8px"+ },++ pivotTable: {+ cell: { fontSize: "12px" },+ rowToggle: {+ textColor: "#FFFFFF",+ backgroundColor: "#95A5A6"+ }+ },++ popover: {+ zIndex: 4+ }+ }+}+```++### Applying Themes++#### Web Components++```html+<script>+ defineMetabaseConfig({+ instanceUrl: "https://your-metabase-url",+ theme: {+ colors: {+ brand: "#9B5966",+ background: "#FFFFFF"+ }+ }+ });+</script>+```++#### React SDK++```tsx+import { defineMetabaseTheme } from "@metabase/embedding-sdk-react";++const theme = defineMetabaseTheme({+ colors: {+ brand: "#9B5966",+ background: "#FFFFFF"+ }+});++<MetabaseProvider theme={theme} authConfig={authConfig}>+ {/* Your components */}+</MetabaseProvider>+```++---++## Plugins (React SDK Only)++### Global Plugins++Applied to all components via `MetabaseProvider`:++```tsx+<MetabaseProvider+ authConfig={authConfig}+ pluginsConfig={{+ mapQuestionClickActions: (clickActions, dataPoint) => {+ // Return custom actions or default actions+ return [+ ...clickActions,+ {+ name: "custom-action",+ title: "Custom Action",+ icon: "info",+ action: () => console.log(dataPoint)+ }+ ];+ },++ handleLink: (url) => {+ console.log("Link clicked:", url);+ return false; // Prevent default+ },++ getNoDataIllustration: () => "data:image/svg+xml;base64,...",+ getNoObjectIllustration: () => "data:image/svg+xml;base64,..."+ }}+>+ {/* Your components */}+</MetabaseProvider>+```++### Component-Level Plugins++Applied to individual components:++```tsx+<InteractiveQuestion+ questionId={456}+ plugins={{+ mapQuestionClickActions: (clickActions, dataPoint) => {+ // Custom behavior for this question only+ if (dataPoint.column.name === "Plan") {+ return [{+ name: "alert",+ title: "Show Alert",+ action: () => alert(dataPoint.value)+ }];+ }+ return clickActions; // Default for other columns+ }+ }}+/>+```++### Dashboard Card Menu Plugin++```tsx+<InteractiveDashboard+ dashboardId={123}+ plugins={{+ dashboardCardMenu: {+ withDownloads: true,+ withEditLink: false,+ customItems: [+ {+ label: "Export to CSV",+ icon: "download",+ action: (question) => {+ // Custom export logic+ console.log("Exporting:", question);+ }+ }+ ]+ }+ }}+/>+```++Or replace the entire menu:++```tsx+<InteractiveDashboard+ dashboardId={123}+ plugins={{+ dashboardCardMenu: (question) => (+ <CustomMenu question={question} />+ )+ }}+/>+```++---++## Setup Checklist++### Metabase Configuration++1. **Enable Modular Embedding**+ - Go to **Admin Settings > Embedding**+ - Toggle **Enable modular embedding** (for web components) or **Modular embedding SDK** (for React)++2. **Configure CORS**+ - Add allowed origins: `https://*.example.com`+ - `localhost` is automatically included for development++3. **SameSite Cookie Setting** (if embedding on different domain)+ - Go to **Admin Settings > Embedding > Security**+ - Set **SameSite cookie** to **None** (requires HTTPS)++4. **Authentication Setup**+ - **Development**: Create API key at **Settings > Authentication > API keys**+ - **Production (JWT)**: Configure at **Settings > Authentication > JWT**+ - **Production (SAML)**: Configure at **Settings > Authentication > SAML**++### Application Setup++#### Web Components++```html+<!DOCTYPE html>+<html>+<head>+ <title>Embedded Analytics</title>+</head>+<body>+ <!-- 1. Load embedding library -->+ <script defer src="https://your-metabase-url/app/embed.js"></script>++ <!-- 2. Configure -->+ <script>+ function defineMetabaseConfig(config) {+ window.metabaseConfig = config;+ }++ defineMetabaseConfig({+ instanceUrl: "https://your-metabase-url",+ apiKey: "mb_dev_api_key" // For local testing+ });+ </script>++ <!-- 3. Embed components -->+ <metabase-dashboard dashboard-id="1"></metabase-dashboard>+</body>+</html>+```++#### React SDK++```bash+# 1. Install+npm install @metabase/embedding-sdk-react@58-stable+```++```tsx+// 2. Configure and embed+import { MetabaseProvider, StaticDashboard } from "@metabase/embedding-sdk-react";++function App() {+ return (+ <MetabaseProvider+ authConfig={{ // ✅ authConfig NOT config+ metabaseInstanceUrl: "https://your-metabase-url",+ apiKey: "mb_dev_api_key"+ }}+ >+ <StaticDashboard dashboardId={1} /> {/* ✅ number type */}+ </MetabaseProvider>+ );+}+```++---++## Common Patterns++### Multi-Tenant Analytics with Data Segregation++```javascript+// Backend: Sign JWT with user's group+const token = jwt.sign(+ {+ email: user.email,+ groups: [user.tenantId], // e.g., "tenant_123"+ exp: Math.round(Date.now() / 1000) + 60 * 10+ },+ METABASE_JWT_SHARED_SECRET+);+```++In Metabase, configure [data sandboxing](https://www.metabase.com/docs/latest/permissions/data-sandboxes) to filter data based on `groups`.++### Custom JWT Fetch (Only When You Need Custom Headers)++**⚠️ Only use this pattern if you need custom headers or auth. Most apps don't need this.**++```tsx+import { defineMetabaseAuthConfig } from "@metabase/embedding-sdk-react";++// Only add fetchRequestToken if you need custom headers/auth+const authConfig = defineMetabaseAuthConfig({+ metabaseInstanceUrl: "https://your-metabase-url",+ fetchRequestToken: async () => {+ const response = await fetch("https://your-backend/sso/metabase", {+ method: "GET",+ credentials: "include", // For cookies+ headers: {+ "Authorization": `Bearer ${yourAuthToken}` // Custom header+ }+ // SDK automatically adds ?response=json query param+ });+ return await response.json(); // { jwt: "..." }+ }+});+```++### Dynamic Parameters++```tsx+const [productId, setProductId] = useState(42);++<InteractiveDashboard+ dashboardId={123} // ✅ number type+ initialParameters={{ productId }} // ✅ values can be any type+/>+```++### Parsing IDs from URL Parameters++```tsx+import { useSearchParams } from "react-router-dom";++function DashboardPage() {+ const [searchParams] = useSearchParams();++ // ✅ CORRECT - Parse numeric IDs to integers+ const dashboardId = parseInt(searchParams.get("id"), 10);++ // ❌ WRONG - Don't pass string IDs for numeric dashboards+ // const dashboardId = searchParams.get("id"); // "123" won't work!++ return <InteractiveDashboard dashboardId={dashboardId} />;+}+```++### Guest Embed with Locked Parameters++```javascript+// Backend: Lock parameters to prevent tampering+const payload = {+ resource: { dashboard: 10 },+ params: {+ // User can't change these+ tenant_id: user.tenantId,+ // User can change these+ date_range: null+ },+ exp: Math.round(Date.now() / 1000) + 10 * 60+};+```++### Checking Authentication Status++```tsx+import { useMetabaseAuthStatus } from "@metabase/embedding-sdk-react";++function MyComponent() {+ const { status, user } = useMetabaseAuthStatus();++ if (status === "loading") return <Spinner />;+ if (status === "error") return <Error />;+ if (status === "success") return <Dashboard user={user} />;+}+```++### Custom Loading and Error Components++```tsx+const CustomLoader = () => <div>Loading analytics...</div>;+const CustomError = ({ error }) => <div>Error: {error.message}</div>;++<MetabaseProvider+ authConfig={authConfig}+ loaderComponent={CustomLoader}+ errorComponent={CustomError}+>+ {/* Your components */}+</MetabaseProvider>+```++---++## SDK Hooks++### useMetabaseAuthStatus+Get current authentication status.++```tsx+const { status, user } = useMetabaseAuthStatus();+// status: "loading" | "success" | "error"+// user: { id, email, first_name, last_name, groups }+```++### useCurrentUser+Get current authenticated user.++```tsx+const user = useCurrentUser();+// Returns: { id, email, first_name, last_name, groups }+```++### useCreateDashboardApi+Programmatically create dashboards.++```tsx+const createDashboard = useCreateDashboardApi();++const handleCreate = async () => {+ const dashboard = await createDashboard({+ name: "New Dashboard",+ description: "Description",+ collection_id: 7+ });+ console.log("Created:", dashboard);+};+```++### useApplicationName+Get Metabase instance name.++```tsx+const appName = useApplicationName();+```++### useAvailableFonts+Get available fonts in Metabase.++```tsx+const fonts = useAvailableFonts();+```++---++## Versioning++**Critical**: Use npm dist-tag matching your Metabase version.++| Metabase Version | npm Install Command |+|------------------|---------------------|+| 1.58.x | `npm install @metabase/embedding-sdk-react@58-stable` |+| 1.57.x | `npm install @metabase/embedding-sdk-react@57-stable` |+| 1.56.x | `npm install @metabase/embedding-sdk-react@56-stable` |+| 1.55.x | `npm install @metabase/embedding-sdk-react@55-stable` |+| 1.54.x | `npm install @metabase/embedding-sdk-react@54-stable` |++Starting with Metabase 57, the SDK uses a two-part architecture:+- **SDK Package**: Lightweight npm package (`@metabase/embedding-sdk-react`)+- **SDK Bundle**: Full SDK code served from your Metabase instance++This ensures version compatibility between SDK and Metabase.++---++## Limitations++### SDK Limitations+- No server-side rendering (SSR)+- No verified content or official collections+- No subscriptions or alerts in SDK components+- No custom click behavior destinations to other Metabase items+- Only one interactive dashboard per page (multiple static dashboards OK)+- Leaflet 1.x compatibility issues (use Leaflet 2.x)++### Guest Embed Limitations+- No drill-through or click actions+- No query builder+- No AI chat+- No row/column-level security (use locked parameters instead)+- No usage analytics++---++## Security Best Practices++1. **Never share Metabase accounts**+ - Each end-user must have their own account (for SSO embeds)+ - Session tokens can be used to access Metabase API directly++2. **Never hardcode secrets**+ - API keys and JWT secrets belong on backend only+ - Fetch tokens dynamically from your server++3. **Use data sandboxing**+ - Configure [row-level permissions](https://www.metabase.com/docs/latest/permissions/data-sandboxes) in Metabase+ - Map user groups to data filters++4. **Validate JWT payloads**+ - Always validate exp (expiration)+ - Keep expiration short (10-15 minutes)++5. **Secure CORS**+ - Only allow specific origins+ - Never use wildcard (`*`) in production++6. **HTTPS required**+ - SameSite=None cookies require HTTPS+ - Use HTTPS for all production embeds++---++## Troubleshooting++### "Failed to fetch" errors+- Check CORS configuration in Metabase+- Verify `instanceUrl` matches your Metabase domain exactly+- Check browser console for specific CORS errors++### Authentication failures+- Verify JWT signature matches secret key+- Check JWT expiration hasn't passed+- Ensure user exists in Metabase with correct email+- Check groups match Metabase group names++### Components not rendering+- Ensure `MetabaseProvider` wraps all SDK components+- Check IDs are correct (numeric IDs must be `number` type, not strings)+- Parse URL parameters with `parseInt(value, 10)` for numeric IDs+- Verify user has permissions to view the item+- Check browser console for errors++### TypeScript errors about ID types+```tsx+// ❌ WRONG+const id = "123"; // string+<StaticDashboard dashboardId={id} /> // Type error!++// ✅ CORRECT+const id = 123; // number+<StaticDashboard dashboardId={id} />++// ✅ CORRECT - Parse from URL+const id = parseInt(urlParams.get("id"), 10);+<StaticDashboard dashboardId={id} />+```++### Theme not applying+- Colors must be valid CSS color values+- Component-level styles override global theme+- Visualization settings in Metabase override theme++### Cross-domain issues+- Set SameSite=None in Metabase settings+- Use HTTPS (required for SameSite=None)+- Safari may require "Allow cross-site tracking"++---++## Resources++- **Live Demo**: [Shoppy Demo App](https://metaba.se/sdk-demo)+- **Sample Code**: [Shoppy Source](https://github.com/metabase/shoppy)+- **Sample App**: [Embedding Sample](https://github.com/metabase/modular-embedding-sample-app)+- **SDK on npm**: [metaba.se/sdk-npm](https://metaba.se/sdk-npm)+- **Documentation**: [Metabase Embedding Docs](https://www.metabase.com/docs/latest/embedding/introduction)+- **Bug Reports**: [GitHub Issues](https://github.com/metabase/metabase/issues)+- **Community**: [Discourse Forums](https://discourse.metabase.com/)++---++## Architecture Notes++### Web Components Architecture+- Metabase serves `embed.js` from your instance+- Custom elements: `<metabase-dashboard>`, `<metabase-question>`, etc.+- Framework-agnostic (works with any web stack)++### React SDK Architecture (v57+)+- **SDK Package** (`@metabase/embedding-sdk-react`): Lightweight bootstrapper+- **SDK Bundle**: Full code served from Metabase instance+- Ensures SDK always matches Metabase version++### Authentication Flow (JWT)+1. User accesses your app+2. Your app sends request to your backend+3. Backend generates signed JWT with user info+4. Backend returns `{ jwt: "..." }` to frontend+5. SDK sends JWT to Metabase+6. Metabase validates signature and creates session+7. Session cookie enables subsequent API calls++### Entity IDs vs Numeric IDs+- **Numeric IDs**: `dashboardId={123}` - Changes when importing/exporting+- **Entity IDs**: `dashboardId="abc123def"` - Stable across environments+- Use Entity IDs for production embeds that sync across instances++---++## Quick Reference++### ⚠️ Deprecated Fields - DO NOT USE+```+authProviderUri - REMOVED: Configure JWT endpoint in Metabase admin instead+jwtProviderUri - REMOVED: Configure JWT endpoint in Metabase admin instead+config (MetabaseProvider) - REMOVED: Use authConfig prop instead+```++### Essential Web Component Attributes+```+dashboard-id, question-id - Required: resource identifier+with-title - Boolean: show/hide title+with-downloads - Boolean: enable/disable downloads+drills - Boolean: enable/disable drill-through+initial-parameters - JSON: default filter values+hidden-parameters - Array: filters to hide+token - String: JWT for guest embeds+refresh - Number: auto-refresh interval (seconds)+```++### Essential SDK Props+```+dashboardId, questionId - Required: number (not string!) or entity ID string+ ⚠️ Parse URL params: parseInt(value, 10)+withTitle - Boolean: show/hide title+withDownloads - Boolean: enable/disable downloads+initialParameters - Object: default filter values+hiddenParameters - Array: filters to hide+isSaveEnabled - Boolean: allow saving+targetCollection - String/Number: force save location+plugins - Object: plugin configuration+```++### Essential MetabaseProvider Props+```+authConfig - Required: authentication config (NOT "config")+theme - Object: theme configuration+pluginsConfig - Object: global plugins+loaderComponent - Component: custom loader+errorComponent - Component: custom error display+```++**⚠️ DEPRECATED Props (DO NOT USE):**+```+config - DEPRECATED: Use authConfig instead+```++---++## Entity ID Usage Pattern++```tsx+// Get entity ID from Metabase+// Admin > Tools > Model Caching > Click info icon on any item++// Use in embeds (stable across environments)+<StaticDashboard dashboardId="abc123def456" />+<StaticQuestion questionId="xyz789ghi012" />+```++---++## Example: Complete Production Setup++**⚠️ Note:** This example shows `fetchRequestToken` for demonstration, but most apps using cookie-based auth don't need it. Only add `fetchRequestToken` if you need custom headers.++### Backend (Express.js)++```javascript+const express = require("express");+const jwt = require("jsonwebtoken");+const cors = require("cors");++const app = express();++// CORS for SDK requests+app.use(cors({+ origin: "https://your-app.com",+ credentials: true+}));++// JWT endpoint+app.get("/sso/metabase", async (req, res) => {+ const user = await getCurrentUser(req);++ const token = jwt.sign(+ {+ email: user.email,+ first_name: user.firstName,+ last_name: user.lastName,+ groups: [`tenant_${user.tenantId}`],+ exp: Math.round(Date.now() / 1000) + 60 * 10+ },+ process.env.METABASE_JWT_SECRET+ );++ if (req.query.response === "json") {+ res.json({ jwt: token });+ } else {+ res.redirect(`${process.env.METABASE_URL}/auth/sso?token=true&jwt=${token}`);+ }+});++app.listen(3001);+```++### Frontend (React)++```tsx+import {+ MetabaseProvider,+ InteractiveDashboard,+ defineMetabaseAuthConfig+} from "@metabase/embedding-sdk-react";++// ✅ CORRECT - Default (no fetchRequestToken needed for cookie-based auth)+const authConfig = defineMetabaseAuthConfig({+ metabaseInstanceUrl: "https://metabase.company.com"+});++// Or if you need custom headers:+// const authConfig = defineMetabaseAuthConfig({+// metabaseInstanceUrl: "https://metabase.company.com",+// fetchRequestToken: async () => {+// const response = await fetch("https://api.company.com/sso/metabase", {+// credentials: "include",+// headers: { "Authorization": `Bearer ${token}` }+// });+// return await response.json();+// }+// });++function Analytics() {+ return (+ <MetabaseProvider authConfig={authConfig}> {/* ✅ authConfig NOT config */}+ <InteractiveDashboard dashboardId="abc123def" /> {/* ✅ Entity ID (string) */}+ </MetabaseProvider>+ );+}+```++### Metabase Configuration++1. **JWT Setup** (Admin > Authentication > JWT)+ - JWT Identity Provider URI: `https://api.company.com/sso/metabase`+ - String used by Metabase to encode: `[Copy shared secret from backend]`++2. **Embedding** (Admin > Embedding)+ - Enable modular embedding SDK: ✓+ - Authorized origins: `https://your-app.com`++3. **SameSite Cookie** (Admin > Embedding > Security)+ - SameSite cookie setting: None++4. **Data Permissions** (Admin > Permissions > Data)+ - Create groups: `tenant_123`, `tenant_456`, etc.+ - Configure data sandboxes per group++---++*Last Updated: December 2025*+*Metabase Version: 1.58+*\ No newline at end of file