From 062d7fc49dded7cdc8ff6c4dda6509ff7fafb17b Mon Sep 17 00:00:00 2001 From: Artyom Keydunov Date: Thu, 23 Apr 2026 21:04:24 -0700 Subject: [PATCH 1/2] docs: restructure embedding section around iframe/SDK/headless taxonomy Reorganize the Embedding tab to use a clean three-tier categorization (Iframe, SDK, Headless embedding) and split iframe embedding pages by what you embed (Dashboards, Analytics Chat, Creator Mode) with authentication (Private, Signed) as a cross-cutting axis. Remove the unused vizard page from navigation. Add redirects for moved URLs and update naming conventions in .cursor/rules/namings-rule.mdc. Made-with: Cursor --- .cursor/rules/namings-rule.mdc | 48 +++++++++++- docs-mintlify/docs.json | 33 ++++++-- .../docs/getting-started/embed-analytics.mdx | 4 +- .../embedding/iframe/analytics-chat.mdx | 49 ++++++++++++ .../auth/private.mdx} | 39 +++------- .../auth/signed.mdx} | 64 ++++------------ .../embedding/{ => iframe}/creator-mode.mdx | 32 ++++---- docs-mintlify/embedding/iframe/dashboards.mdx | 76 +++++++++++++++++++ docs-mintlify/embedding/index.mdx | 14 ++-- docs-mintlify/embedding/react-embed-sdk.mdx | 4 +- .../reference/embed-apis/generate-session.mdx | 2 +- docs-mintlify/reference/embed-apis/index.mdx | 2 +- 12 files changed, 256 insertions(+), 111 deletions(-) create mode 100644 docs-mintlify/embedding/iframe/analytics-chat.mdx rename docs-mintlify/embedding/{private-embedding.mdx => iframe/auth/private.mdx} (60%) rename docs-mintlify/embedding/{signed-embedding.mdx => iframe/auth/signed.mdx} (76%) rename docs-mintlify/embedding/{ => iframe}/creator-mode.mdx (70%) create mode 100644 docs-mintlify/embedding/iframe/dashboards.mdx diff --git a/.cursor/rules/namings-rule.mdc b/.cursor/rules/namings-rule.mdc index 59e14a5967b29..1eefc50ed014d 100644 --- a/.cursor/rules/namings-rule.mdc +++ b/.cursor/rules/namings-rule.mdc @@ -45,6 +45,48 @@ Make sure to use correct terms. - Management APIs - Orchestration API - **Embedding** - - Private embedding - - Signed embedding - - Creator Mode + - Iframe embedding (the integration approach where Cube content is embedded via iframes) + - What you can embed: + - Dashboards + - Analytics Chat + - Creator Mode + - Authentication: + - Private embedding (auth mode for internal users with Cube accounts) + - Signed embedding (auth mode for external/customer-facing applications; required for Creator Mode) + - SDK embedding (the integration approach using the React Embed SDK) + - Headless embedding (the integration approach using Cube APIs directly — Embed APIs and Core Data APIs) + +# Embedding Terminology + +When categorizing embedding approaches, use these three parallel terms: + +- **Iframe embedding** — drop-in via iframes; Cube ships the full UI +- **SDK embedding** — via the React Embed SDK; Cube ships components, you compose +- **Headless embedding** — via Embed APIs and Core Data APIs; you build the UI + +Notes: +- Do not use `-based` suffixes (e.g., "iframe-based embedding", "API-based embedding"). Prefer the bare terms above. +- Use **Iframe** (capitalized at sentence start, lowercase mid-sentence). Do not use "iFrame". +- "API-based embedding" is ambiguous because **API** has specific product meaning (Embed APIs, Core Data APIs, Management APIs, Orchestration API). Use **Headless embedding** instead. + +## Iframe embedding axes + +Iframe embedding has two independent axes: + +- **What you embed** (primary axis): Dashboards, Analytics Chat, Creator Mode +- **Authentication** (secondary, cross-cutting axis): Private embedding, Signed embedding + +Compatibility matrix: + +| | Private embedding | Signed embedding | +|------------------|:-----------------:|:----------------:| +| Dashboards | ✓ | ✓ | +| Analytics Chat | ✓ | ✓ | +| Creator Mode | — | ✓ | + +Page naming inside the **Iframe embedding** group: + +- Do not prefix page titles with "Embed" or "Embedding" — it is redundant under the group label. + - Use **Dashboards**, **Analytics Chat**, **Creator Mode** (not "Embed a dashboard", "Embed Analytics Chat", etc.) + - Use **Private embedding**, **Signed embedding** for the auth-mode pages (the word "embedding" is part of the product term itself). + diff --git a/docs-mintlify/docs.json b/docs-mintlify/docs.json index 644b01a679b04..6c8c296d72062 100644 --- a/docs-mintlify/docs.json +++ b/docs-mintlify/docs.json @@ -409,11 +409,22 @@ "group": "Embedding", "pages": [ "embedding/index", - "embedding/private-embedding", - "embedding/signed-embedding", - "embedding/creator-mode", - "embedding/react-embed-sdk", - "embedding/vizard" + "embedding/react-embed-sdk" + ] + }, + { + "group": "Iframe embedding", + "pages": [ + "embedding/iframe/dashboards", + "embedding/iframe/analytics-chat", + "embedding/iframe/creator-mode", + { + "group": "Authentication", + "pages": [ + "embedding/iframe/auth/private", + "embedding/iframe/auth/signed" + ] + } ] }, { @@ -691,5 +702,17 @@ } }, "redirects": [ + { + "source": "/embedding/private-embedding", + "destination": "/embedding/iframe/auth/private" + }, + { + "source": "/embedding/signed-embedding", + "destination": "/embedding/iframe/auth/signed" + }, + { + "source": "/embedding/creator-mode", + "destination": "/embedding/iframe/creator-mode" + } ] } \ No newline at end of file diff --git a/docs-mintlify/docs/getting-started/embed-analytics.mdx b/docs-mintlify/docs/getting-started/embed-analytics.mdx index fa321ecbfe601..6135a1ea09a66 100644 --- a/docs-mintlify/docs/getting-started/embed-analytics.mdx +++ b/docs-mintlify/docs/getting-started/embed-analytics.mdx @@ -21,5 +21,5 @@ If you want complete control over visualizations and user interfaces, you can us [ref-analytics-chat]: /analytics/analytics-chat [ref-chat-api]: /reference/embed-apis/chat-api [ref-core-apis]: /reference/core-data-apis -[ref-private-embedding]: /embedding/private-embedding -[ref-signed-embedding]: /embedding/signed-embedding \ No newline at end of file +[ref-private-embedding]: /embedding/iframe/auth/private +[ref-signed-embedding]: /embedding/iframe/auth/signed \ No newline at end of file diff --git a/docs-mintlify/embedding/iframe/analytics-chat.mdx b/docs-mintlify/embedding/iframe/analytics-chat.mdx new file mode 100644 index 0000000000000..7614c8f3a59bd --- /dev/null +++ b/docs-mintlify/embedding/iframe/analytics-chat.mdx @@ -0,0 +1,49 @@ +--- +title: Analytics Chat +description: Embed Cube Analytics Chat into your applications via iframe. +--- + + + Iframe embedding is available on [Premium and Enterprise plans](https://cube.dev/pricing). + + +Embed [Analytics Chat](/docs/explore-analyze/analytics-chat) into your application using an iframe. Let your users ask questions in plain language and get trusted answers powered by your semantic layer — without leaving your product. + +Analytics Chat can be embedded with either authentication mode: + +- **[Private embedding](/embedding/iframe/auth/private)** — for internal users with Cube accounts +- **[Signed embedding](/embedding/iframe/auth/signed)** — for external/customer-facing applications using server-generated sessions + +## Embed with private embedding + +The embed URL for Analytics Chat is always the same: + +```html + +``` + +Users will be prompted to sign in with their Cube credentials when accessing the embedded chat. See [Private embedding](/embedding/iframe/auth/private) for details on the auth model. + +## Embed with signed embedding + +To embed Analytics Chat for external/customer-facing applications, generate a session on your backend and pass the session ID into the iframe: + +```html + +``` + +See [Signed embedding](/embedding/iframe/auth/signed) for the full session generation flow, API key setup, and a complete working example. + +## Personalize chat with user attributes + +When using signed embedding, you can pass [user attributes](/embedding/iframe/auth/signed#user-attributes) during session generation to personalize chat responses for each user — for example, scoping answers to a specific region, department, or tenant. diff --git a/docs-mintlify/embedding/private-embedding.mdx b/docs-mintlify/embedding/iframe/auth/private.mdx similarity index 60% rename from docs-mintlify/embedding/private-embedding.mdx rename to docs-mintlify/embedding/iframe/auth/private.mdx index 73bbe357e90ee..ac434356fae5c 100644 --- a/docs-mintlify/embedding/private-embedding.mdx +++ b/docs-mintlify/embedding/iframe/auth/private.mdx @@ -1,45 +1,30 @@ --- title: Private embedding -description: Private embedding is available on Premium and Enterprise plans. +description: Authenticate iframe-embedded Cube content with users' existing Cube accounts. --- Private embedding is available on [Premium and Enterprise plans](https://cube.dev/pricing). -Private embedding is designed for **internal use cases** where team members already have Cube accounts. Simply drop an iframe into your internal tools—no API keys or complex setup required. Users will authenticate with their existing Cube credentials when accessing embedded content. +Private embedding is designed for **internal use cases** where team members already have Cube accounts. Simply drop an iframe into your internal tools — no API keys or session generation required. Users authenticate with their existing Cube credentials when accessing embedded content. -## How it works - -To embed Cube content, you simply need to paste an ` -``` + + Private embedding does not support [Creator Mode](/embedding/iframe/creator-mode) — use [Signed embedding](/embedding/iframe/auth/signed) instead. + -### Dashboards - -To embed a dashboard: - -1. Open your dashboard in Cube -2. Click **Share** → **Embed** -3. Copy the generated iframe code - -Share embed dialog +## How it works -Then paste the iframe code into your application. +To embed Cube content with private embedding, paste an ` -``` - -```html - -``` +Use the session ID to embed the dashboard or chat UI in your application. See [Dashboards](/embedding/iframe/dashboards) and [Analytics Chat](/embedding/iframe/analytics-chat) for the full iframe snippets. #### Complete example @@ -155,31 +148,6 @@ Here's a complete HTML example that demonstrates the full flow for embedding a d ``` -## Pre-setting dashboard filters via URL - -You can pre-set dashboard filter values by adding URL parameters in the format -`?f_.=`. The `` and `` -must match the internal names (not display titles) of the semantic view and -dimension configured on the filter widget. If the filter type is omitted, it -defaults to `equals`. - -Example: - -```text -https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID&f_orders_transactions.users_country={"value":"USA"} -``` - -This works on both regular and published (embedded) dashboards. The filter is -only applied if a matching filter widget for that dimension already exists on the -dashboard. - -## Customize dashboard style - -You can customize the appearance of your dashboard — including background, widget -styling, borders, titles, and fonts — using the **Styling** pane in the -Dashboard Builder. Open your dashboard, click **Dashboard Builder** in the -top bar, then click the gear icon to open the **Styling** panel. - ## User attributes User attributes enable row-level security and personalized chat responses by filtering data based on user permissions. The attributes you pass during session generation automatically filter data queries and responses. @@ -215,4 +183,4 @@ For a complete working example of signed embedding, check out the [cube-embeddin You can clone the repository, configure it with your Cube credentials, and run it locally to test embedding functionality or use it as a reference implementation for your own application. [ref-api-keys]: /admin/account-billing/api-keys -[ref-generate-session]: /reference/embed-apis/generate-session \ No newline at end of file +[ref-generate-session]: /reference/embed-apis/generate-session diff --git a/docs-mintlify/embedding/creator-mode.mdx b/docs-mintlify/embedding/iframe/creator-mode.mdx similarity index 70% rename from docs-mintlify/embedding/creator-mode.mdx rename to docs-mintlify/embedding/iframe/creator-mode.mdx index 09fdc8d550b98..92468655ce6c1 100644 --- a/docs-mintlify/embedding/creator-mode.mdx +++ b/docs-mintlify/embedding/iframe/creator-mode.mdx @@ -1,44 +1,46 @@ --- -title: Creator mode -description: Available on the Enterprise plan. +title: Creator Mode +description: Embed the full Cube application so users can build and modify their own dashboards. --- - -Available on the [Enterprise plan](https://cube.dev/pricing). - + Creator Mode is available on the [Enterprise plan](https://cube.dev/pricing). -Creator mode enables you to embed the entire Cube application with workbooks-dashboard functionality. Users will be able to create and modify their dashboards directly within the embedded application. +Creator Mode lets you embed the entire Cube application into your product so users can create and modify their own dashboards directly within the embedded experience. + + + Creator Mode requires [Signed embedding](/embedding/iframe/auth/signed). Private embedding is not supported. + ## How it works -In creator mode, you embed the full Cube application instead of individual dashboards or chat interfaces. This provides users with the complete Cube experience, including the ability to: +In Creator Mode, you embed the full Cube application instead of individual dashboards or chat interfaces. This provides users with the complete Cube experience, including the ability to: - Create new dashboards - Modify existing dashboards - Access all workbook and dashboard functionality - Build custom analytics experiences -To enable creator mode, you need to pass `creatorMode: true`, `tenantId`, and `tenantName` to the [Generate Session API][ref-generate-session] when generating an embed session. The tenant ID is used to scope all content that the user creates to a specific tenant, while the tenant name is a human-readable friendly name displayed in the user interface. +To enable Creator Mode, pass `creatorMode: true`, `tenantId`, and `tenantName` to the [Generate Session API][ref-generate-session] when generating an embed session. The tenant ID is used to scope all content the user creates to a specific tenant; the tenant name is a human-readable label displayed in the user interface. ## Tenant ID and Name -When using creator mode, you must provide both `tenantId` and `tenantName` parameters when generating a session: +When using Creator Mode, you must provide both `tenantId` and `tenantName` parameters when generating a session: - **`tenantId`** – Used to scope all content (dashboards, workbooks, etc.) that users create within the embedded application to a specific tenant. This ensures proper data isolation in multi-tenant scenarios. - **`tenantName`** – A human-readable friendly name for the tenant that will be displayed in the user interface. -## Using creator mode +## Using Creator Mode -To use creator mode and embed an app: +To use Creator Mode and embed the app: 1. **Set the embed type to "App"** in the form 2. **Fill in Deployment ID**, **Tenant ID**, **Tenant Name**, and either **External ID** or **Internal ID** (email) 3. **Click "Generate Session & Embed"** — the request automatically includes `creatorMode: true` for app embeddings 4. The app is embedded at `/embed/d/{deploymentId}/app?session={sessionId}` and displayed in the iframe -Creator mode is enabled automatically when the embed type is "app"; no additional configuration is needed. The tenant ID is required to scope all dashboards and content created by the user to the specific tenant, and the tenant name will be displayed in the user interface. +Creator Mode is enabled automatically when the embed type is "app"; no additional configuration is needed. The tenant ID is required to scope all dashboards and content created by the user to the specific tenant, and the tenant name will be displayed in the user interface. ### Example @@ -87,14 +89,14 @@ Replace `{deploymentId}` with your deployment ID and `{sessionId}` with the sess ## Example application -For a complete working example of embedding, including creator mode, check out the [cube-embedding-demo](https://github.com/cubedevinc/cube-embedding-demo) repository. This demo application provides: +For a complete working example of embedding, including Creator Mode, check out the [cube-embedding-demo](https://github.com/cubedevinc/cube-embedding-demo) repository. This demo application provides: - A full working example of iframe embedding - Implementation of signed iframe embedding with session generation -- Support for creator mode with tenant ID and tenant name +- Support for Creator Mode with tenant ID and tenant name - A React-based UI for testing embedding functionality - Backend server that securely handles API key authentication You can clone the repository, configure it with your Cube credentials, and run it locally to test embedding functionality or use it as a reference implementation for your own application. -[ref-generate-session]: /reference/embed-apis/generate-session \ No newline at end of file +[ref-generate-session]: /reference/embed-apis/generate-session diff --git a/docs-mintlify/embedding/iframe/dashboards.mdx b/docs-mintlify/embedding/iframe/dashboards.mdx new file mode 100644 index 0000000000000..b37d1ca562c49 --- /dev/null +++ b/docs-mintlify/embedding/iframe/dashboards.mdx @@ -0,0 +1,76 @@ +--- +title: Dashboards +description: Embed Cube dashboards into your applications via iframe. +--- + + + Iframe embedding is available on [Premium and Enterprise plans](https://cube.dev/pricing). + + +Embed any [dashboard](/docs/explore-analyze/dashboards) into your application using an iframe. Dashboards can be embedded with either authentication mode: + +- **[Private embedding](/embedding/iframe/auth/private)** — for internal users with Cube accounts (e.g., embedding in Notion, Salesforce, internal tools) +- **[Signed embedding](/embedding/iframe/auth/signed)** — for external/customer-facing applications using server-generated sessions + +## Embed with private embedding + +To embed a dashboard for internal users: + +1. Open your dashboard in Cube +2. Click **Share** → **Embed** +3. Copy the generated iframe code + +Share embed dialog + +Then paste the iframe code into your application: + +```html + +``` + +Users will be prompted to sign in with their Cube credentials when accessing the embedded dashboard. See [Private embedding](/embedding/iframe/auth/private) for details on the auth model and integration examples (Notion, Salesforce). + +## Embed with signed embedding + +To embed a dashboard for external/customer-facing applications, generate a session on your backend and pass the session ID into the iframe: + +```html + +``` + +See [Signed embedding](/embedding/iframe/auth/signed) for the full session generation flow, API key setup, and a complete working example. + +## Pre-set dashboard filters via URL + +You can pre-set dashboard filter values by adding URL parameters in the format +`?f_.=`. The `` and `` +must match the internal names (not display titles) of the semantic view and +dimension configured on the filter widget. If the filter type is omitted, it +defaults to `equals`. + +Example: + +```text +https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID&f_orders_transactions.users_country={"value":"USA"} +``` + +This works on both regular and published (embedded) dashboards. The filter is +only applied if a matching filter widget for that dimension already exists on the +dashboard. + +## Customize dashboard style + +You can customize the appearance of your dashboard — including background, widget +styling, borders, titles, and fonts — using the **Styling** pane in the +Dashboard Builder. Open your dashboard, click **Dashboard Builder** in the +top bar, then click the gear icon to open the **Styling** panel. diff --git a/docs-mintlify/embedding/index.mdx b/docs-mintlify/embedding/index.mdx index b434068aee78c..0ffe4c29ed30f 100644 --- a/docs-mintlify/embedding/index.mdx +++ b/docs-mintlify/embedding/index.mdx @@ -1,11 +1,11 @@ --- -description: Embed AI-powered analytics into your applications using iframes, the React SDK, or API-first approaches. +description: Embed AI-powered analytics into your applications using iframes, the React Embed SDK, or a headless approach. title: Overview --- Cube provides multiple approaches for embedding AI-powered analytics into your applications — from iframe embeds to fully custom embedded analytics experiences built on Cube's APIs. -## Iframe-based embedding +## Iframe embedding Available on [Premium and Enterprise plans](https://cube.dev/pricing). @@ -13,13 +13,13 @@ Cube provides multiple approaches for embedding AI-powered analytics into your a Embed Cube content using iframes for the fastest integration with minimal code. This approach works with any frontend framework and requires no additional dependencies. -Iframe embedding supports [dashboards](/docs/explore-analyze/dashboards), [analytics chat](/docs/explore-analyze/analytics-chat), and the full Cube application in [creator mode](/embedding/creator-mode). +Iframe embedding supports [dashboards](/embedding/iframe/dashboards), [Analytics Chat](/embedding/iframe/analytics-chat), and the full Cube application in [Creator Mode](/embedding/iframe/creator-mode). **Authentication options:** -- **[Private embedding](/embedding/private-embedding)** – For internal use cases where users authenticate with their Cube accounts -- **[Signed embedding](/embedding/signed-embedding)** – For customer-facing applications using secure, server-generated sessions for authentication +- **[Private embedding](/embedding/iframe/auth/private)** – For internal use cases where users authenticate with their Cube accounts +- **[Signed embedding](/embedding/iframe/auth/signed)** – For customer-facing applications using secure, server-generated sessions for authentication -## React component-based embedding +## SDK embedding Available on [Premium and Enterprise plans](https://cube.dev/pricing). @@ -27,7 +27,7 @@ Iframe embedding supports [dashboards](/docs/explore-analyze/dashboards), [analy Embed Cube using the [React Embed SDK](/embedding/react-embed-sdk) for tighter integration with your React applications. Components provide more control over styling, theming, and user interactions. -## API-based embedding +## Headless embedding Build fully custom embedded analytics experiences using Cube APIs directly. This headless approach gives you complete control over data fetching, visualization, and user interface. diff --git a/docs-mintlify/embedding/react-embed-sdk.mdx b/docs-mintlify/embedding/react-embed-sdk.mdx index 9365ddd362092..13f910d29d201 100644 --- a/docs-mintlify/embedding/react-embed-sdk.mdx +++ b/docs-mintlify/embedding/react-embed-sdk.mdx @@ -7,7 +7,7 @@ description: React Embed SDK is currently in public preview. The API may change React Embed SDK is currently in **public preview**. The API may change in future releases. -The React Embed SDK provides React components for embedding Cube analytics directly into your React applications. It offers tighter integration with React's component model, giving you more control over styling, theming, and user interactions compared to iframe-based embedding. +The React Embed SDK provides React components for embedding Cube analytics directly into your React applications. It offers tighter integration with React's component model, giving you more control over styling, theming, and user interactions compared to iframe embedding. ## Installation @@ -43,7 +43,7 @@ function App() { ## Authentication -The React Embed SDK uses the same session-based authentication as [signed embedding](/embedding/signed-embedding). Generate a session using the [Generate Session API](/reference/embed-apis/generate-session) and pass the `sessionId` to the provider. +The React Embed SDK uses the same session-based authentication as [signed embedding](/embedding/iframe/auth/signed). Generate a session using the [Generate Session API](/reference/embed-apis/generate-session) and pass the `sessionId` to the provider. ## Example diff --git a/docs-mintlify/reference/embed-apis/generate-session.mdx b/docs-mintlify/reference/embed-apis/generate-session.mdx index bcb5cf508f34a..d33e3ecd0b8fb 100644 --- a/docs-mintlify/reference/embed-apis/generate-session.mdx +++ b/docs-mintlify/reference/embed-apis/generate-session.mdx @@ -136,4 +136,4 @@ curl -X POST "https://your-account.cubecloud.dev/api/v1/embed/generate-session" Use session ID in [signed embedding][ref-signed-embedding]. [ref-api-keys]: /admin/account-billing/api-keys -[ref-signed-embedding]: /embedding/signed-embedding \ No newline at end of file +[ref-signed-embedding]: /embedding/iframe/auth/signed \ No newline at end of file diff --git a/docs-mintlify/reference/embed-apis/index.mdx b/docs-mintlify/reference/embed-apis/index.mdx index c1c063cecc9ce..648012351d349 100644 --- a/docs-mintlify/reference/embed-apis/index.mdx +++ b/docs-mintlify/reference/embed-apis/index.mdx @@ -20,4 +20,4 @@ Create secure, temporary sessions for embedding Cube content. Use sessions to au [ref-chat-api]: /reference/embed-apis/chat-api [ref-generate-session]: /reference/embed-apis/generate-session -[ref-embedding]: /embedding/signed-embedding \ No newline at end of file +[ref-embedding]: /embedding/iframe/auth/signed \ No newline at end of file From 6a1314a2510c772ba27cb1c7eb00ce7038cf1e0e Mon Sep 17 00:00:00 2001 From: Artyom Keydunov Date: Thu, 23 Apr 2026 21:24:57 -0700 Subject: [PATCH 2/2] docs: add iframe embedding customization page and dashboard styling page Add a Customization page under Iframe embedding documenting dashboard styling and the embedTheme parameters supported by the Generate Session API for Creator Mode embeds. Extract the dashboard Styling reference into its own page under Dashboards so it can be linked from both the Dashboards section and the iframe embedding docs. Made-with: Cursor --- docs-mintlify/docs.json | 4 +- .../explore-analyze/dashboards/styling.mdx | 60 ++++++++++++++++ .../embedding/iframe/customization.mdx | 68 +++++++++++++++++++ docs-mintlify/embedding/iframe/dashboards.mdx | 7 +- 4 files changed, 133 insertions(+), 6 deletions(-) create mode 100644 docs-mintlify/docs/explore-analyze/dashboards/styling.mdx create mode 100644 docs-mintlify/embedding/iframe/customization.mdx diff --git a/docs-mintlify/docs.json b/docs-mintlify/docs.json index 6c8c296d72062..cfa7c96a89904 100644 --- a/docs-mintlify/docs.json +++ b/docs-mintlify/docs.json @@ -115,7 +115,8 @@ "docs/explore-analyze/dashboards/widgets/controls", "docs/explore-analyze/dashboards/widgets/ai-summary" ] - } + }, + "docs/explore-analyze/dashboards/styling" ] }, "docs/explore-analyze/scheduled-refreshes", @@ -418,6 +419,7 @@ "embedding/iframe/dashboards", "embedding/iframe/analytics-chat", "embedding/iframe/creator-mode", + "embedding/iframe/customization", { "group": "Authentication", "pages": [ diff --git a/docs-mintlify/docs/explore-analyze/dashboards/styling.mdx b/docs-mintlify/docs/explore-analyze/dashboards/styling.mdx new file mode 100644 index 0000000000000..d055671f7918b --- /dev/null +++ b/docs-mintlify/docs/explore-analyze/dashboards/styling.mdx @@ -0,0 +1,60 @@ +--- +title: Styling +description: Customize the appearance of a dashboard from the Styling panel in the Dashboard Builder. +--- + +You can customize the appearance of any dashboard — background, padding, widget cards, borders, titles, and fonts — from the **Styling** panel in the Dashboard Builder. + +Styling is **per-dashboard**: settings are saved to the dashboard's configuration and apply equally to the dashboard in Cube and to its [embedded view](/embedding/iframe/dashboards) (both [private](/embedding/iframe/auth/private) and [signed](/embedding/iframe/auth/signed) embedding). + +## Open the Styling panel + +1. Open your dashboard +2. Click **Dashboard Builder** in the top bar +3. Click the gear icon to open the **Styling** panel + +Click **Apply** to preview your changes. Click **Reset** to revert to the defaults. Publish the dashboard for the styling to take effect in embedded views. + +## Options + +All values accept standard CSS — colors as hex (`#1a1a2e`), `rgb()`, or named colors; lengths as CSS units (e.g., `16px`). + +### Background + +Settings that apply to the dashboard canvas as a whole. + +| Option | Description | Example | +|--------------|----------------------------------------------------|-------------| +| Background | Dashboard background color | `#f9f9fb` | +| Padding | Outer padding around the dashboard grid | `16px` | + +### Widgets + +Settings that apply to every widget (chart card) on the dashboard. + +| Option | Description | Example | +|--------------|----------------------------------------------------|-------------| +| Background | Widget card background color | `#ffffff` | +| Padding | Inner padding within each widget | `12px` | + +### Widgets → Borders + +Border styling for widget cards. + +| Option | Description | Example | +|----------|----------------------------------------------------------------------|-------------| +| Color | Border color | `#E1E2E8` | +| Radius | Corner radius | `8px` | +| Style | Border style (`solid`, `dashed`, `dotted`, `double`, `none`) | `solid` | +| Width | Border thickness | `1px` | + +### Widgets → Titles + +Typography for widget titles. + +| Option | Description | Example | +|--------------|------------------------------|---------------| +| Color | Title text color | `#1a1a2e` | +| Font Size | Title font size | `18px` | +| Font Weight | Title font weight | `600` | +| Font Family | Title font family | `system-ui` | diff --git a/docs-mintlify/embedding/iframe/customization.mdx b/docs-mintlify/embedding/iframe/customization.mdx new file mode 100644 index 0000000000000..3d9e0d4cdcb62 --- /dev/null +++ b/docs-mintlify/embedding/iframe/customization.mdx @@ -0,0 +1,68 @@ +--- +title: Customization +description: Customize the appearance of embedded dashboards and the embedded Cube app. +--- + +You can customize the appearance of iframe-embedded Cube content in two ways: + +- **[Dashboard customization](#dashboard-customization)** — style an individual [dashboard](/embedding/iframe/dashboards) using the Styling panel in the Dashboard Builder +- **[App customization](#app-customization)** — pass theme parameters to the [Generate Session API](/reference/embed-apis/generate-session) when embedding the full Cube app in [Creator Mode](/embedding/iframe/creator-mode) + + + Customization options will expand over time. This page documents what is supported today. + + +## Dashboard customization + +Style an individual dashboard from the **Styling** panel in the Dashboard Builder. Settings are saved per-dashboard and apply equally to the dashboard in Cube and to its embedded view. + +See [Dashboards → Styling](/docs/explore-analyze/dashboards/styling) for the full list of options. + +## App customization + +When embedding the full Cube app in [Creator Mode](/embedding/iframe/creator-mode), pass an `embedTheme` object to the [Generate Session API](/reference/embed-apis/generate-session) to customize the appearance of the embedded experience. + +The `embedTheme` is scoped to the embed session — it is applied while the user is viewing the embedded app and reset on the next session generation. + +### Example + +```javascript +const session = await fetch( + "https://your-account.cubecloud.dev/api/v1/embed/generate-session", + { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Api-Key ${API_KEY}`, + }, + body: JSON.stringify({ + deploymentId: DEPLOYMENT_ID, + externalId: "user@example.com", + creatorMode: true, + tenantId: "tenant-123", + tenantName: "Acme Corporation", + embedTheme: { + analyticsChat: { + backgroundColor: "#f4f4f5", + chatInput: { + backgroundColor: "#ffffff", + borderColor: "#e4e4e7", + }, + }, + }, + }), + }, +); +``` + +### Parameters + +The following `embedTheme` parameters are currently supported: + +| Parameter | Type | Description | Example | +|-------------------------------------------------|----------|--------------------------------------------------------|---------------| +| `analyticsChat.backgroundColor` | `string` | Background color of the Analytics Chat panel. | `"#f4f4f5"` | +| `analyticsChat.chatInput.backgroundColor` | `string` | Background color of the chat input field. | `"#ffffff"` | +| `analyticsChat.chatInput.borderColor` | `string` | Border color of the chat input field. | `"#e4e4e7"` | + +All values accept standard CSS color formats (hex, `rgb()`, named colors). diff --git a/docs-mintlify/embedding/iframe/dashboards.mdx b/docs-mintlify/embedding/iframe/dashboards.mdx index b37d1ca562c49..0972370729b5f 100644 --- a/docs-mintlify/embedding/iframe/dashboards.mdx +++ b/docs-mintlify/embedding/iframe/dashboards.mdx @@ -68,9 +68,6 @@ This works on both regular and published (embedded) dashboards. The filter is only applied if a matching filter widget for that dimension already exists on the dashboard. -## Customize dashboard style +## Customize appearance -You can customize the appearance of your dashboard — including background, widget -styling, borders, titles, and fonts — using the **Styling** pane in the -Dashboard Builder. Open your dashboard, click **Dashboard Builder** in the -top bar, then click the gear icon to open the **Styling** panel. +You can style an embedded dashboard — background, padding, widget borders, titles, and fonts — from the **Styling** panel in the Dashboard Builder. See [Dashboards → Styling](/docs/explore-analyze/dashboards/styling) for the full list of options.