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: customization - config (#83030)
Michael Eby6f4dad4d7a1d
diff --git a/docs/embedding/components.md b/docs/embedding/components.mdindex ddf651227ee..249f5af2a14 100644--- a/docs/embedding/components.md+++ b/docs/embedding/components.md@@ -53,7 +53,8 @@ Web components cover the components above. A few features are React-only, becaus## Further reading- [Appearance](./appearance.md)-- [Modular embedding SDK config](./sdk/config.md), for the `MetabaseProvider` props+- [Configure your embeds](./config.md)+- [Config reference](./config-reference.md), for `defineMetabaseConfig()` settings and `MetabaseProvider` props- [Modular embedding parameters](./parameters.md)- [Custom visualizations in embeds](./custom-visualizations.md)- [Translating embeds](./translations.md)diff --git a/docs/embedding/config-reference.md b/docs/embedding/config-reference.mdnew file mode 100644index 00000000000..35ea90ea8c1--- /dev/null+++ b/docs/embedding/config-reference.md@@ -0,0 +1,45 @@+---+title: Config reference+summary: "Reference for the page-level config settings for web components, and the props you can pass to the React SDK's MetabaseProvider."+---++# Config reference++Reference material for the config that every modular embed on a page shares: the `defineMetabaseConfig()` settings for web components, and the `MetabaseProvider` props for the React SDK.++For how to set all this up, check out [Configure your embeds](./config.md).++## Web component `defineMetabaseConfig()` settings++Every web component on the page uses these settings. For the SDK, see [`MetabaseProvider` props](#react-sdk-metabaseprovider-props).++{% include_file "{{ dirname }}/eajs/snippets/MetabaseConfig.md" snippet="properties" %}++## React SDK `MetabaseProvider` props++{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %}++`MetabaseProvider` provides the [configuration](./config.md#configure-the-react-sdk) that every Metabase component inside it uses.++- [Component](./sdk/api/MetabaseProvider.html)+- [Props](./sdk/api/MetabaseProviderProps.html)++{% include_file "{{ dirname }}/sdk/api/snippets/MetabaseProviderProps.md" snippet="properties" %}++## React SDK `eventHandlers`++{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %}++The `eventHandlers` prop on `MetabaseProvider` maps event types to handler functions. See [Handle embed events](./config.md#handle-embed-events-react-sdk-only).++- [Type](./sdk/api/SdkEventHandlersConfig.html)++{% include_file "{{ dirname }}/sdk/api/snippets/SdkEventHandlersConfig.md" snippet="properties" %}++## Further reading++- [Configure your embeds](./config.md)+- [Appearance](./appearance.md)+- [Authentication](./authentication.md)+- [Guest embedding](./guest-embedding.md)+- [Modular embedding components](./components.md)diff --git a/docs/embedding/config.md b/docs/embedding/config.mdnew file mode 100644index 00000000000..5b28acbe308--- /dev/null+++ b/docs/embedding/config.md@@ -0,0 +1,247 @@+---+title: Configure your embeds+summary: "Set the configuration that all modular embeds on a page share, including your Metabase URL, language, and authentication mode, with web components or the React SDK."+redirect_from:+ - /docs/latest/embedding/sdk/config+---++# Configure your embeds++Every modular embed on a page shares one configuration. How you configure your embeds depends on which embedding method you use:++- **[Web components](#configure-web-components)**: call `defineMetabaseConfig()` once per page. All Metabase components on the page use that config.+- **[React SDK](#configure-the-react-sdk)**: pass your config as props to `MetabaseProvider`. All Metabase components inside the provider use that config.++Settings for one embed, like a dashboard's ID, go on the component. Settings for every embed, like your Metabase URL or theme, go in the shared configuration.++## Configure web components++To configure web components, add a script tag to your page that loads `embed.js` from your Metabase, then call `defineMetabaseConfig()`:++```html+<!-- embed.js defines <metabase-dashboard> and other elements -->+<script defer src="https://your-metabase.example.com/app/embed.js"></script>+<script>+ function defineMetabaseConfig(config) {+ window.metabaseConfig = config;+ }+</script>++<script>+ defineMetabaseConfig({+ instanceUrl: "https://your-metabase.example.com",+ });+</script>++<metabase-dashboard dashboard-id="1"></metabase-dashboard>+```++`instanceUrl`, the URL of your Metabase, is the only required setting.++For the full list of settings, see [web component settings](./config-reference.md#web-component-definemetabaseconfig-settings).++## Configure the React SDK++{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %}++To configure the [React SDK](./sdk/introduction.md), pass your config as props to `MetabaseProvider`. The only required prop is `authConfig`, which you create with `defineMetabaseAuthConfig()`:++```tsx+{% include_file "{{ dirname }}/sdk/snippets/config/config-base.tsx" %}+```++For the full list of props, see [`MetabaseProvider` props](./config-reference.md#react-sdk-metabaseprovider-props).++## Set how your embeds authenticate++Your config determines how every embed on the page authenticates:++- **[Guest embeds](./introduction.md#components-with-guest-authentication)**: view-only. Your server signs a token for each embed, so people don't need Metabase accounts. See [Configure a guest embed](#configure-a-guest-embed).+- **[SSO embeds](./introduction.md#components-with-sso-authentication)**: the default. Your app signs each person in to their own Metabase account, so their permissions apply. See [Configure an SSO embed](#configure-an-sso-embed).++You can only use one type of authentication per page. To pick one, check out [SSO or guest embeds](./introduction.md#comparison-between-sso-and-guest-authentication).++### Configure a guest embed++To configure guest embeds, set `isGuest: true`, which tells the components to authenticate with a signed JWT instead of a Metabase session. Where the setting goes depends on how you're embedding.++With web components, add `isGuest` to the page-level config. You can also add `guestEmbedProviderUri`, which points to the endpoint in your app that signs the tokens:++```html+<script>+ defineMetabaseConfig({+ instanceUrl: "https://your-metabase.example.com",+ isGuest: true,+ guestEmbedProviderUri: "/api/metabase-guest-token",+ });+</script>+```++The embed calls the endpoint for a token on load, and again when the current token expires. Without `guestEmbedProviderUri`, your server must generate a token for each component and set the token in that component's `token` attribute when building the page.++With the SDK, add `isGuest` to your auth config, and pass each component a token that your server signs. The SDK doesn't support `guestEmbedProviderUri`.++```tsx+{% include_file "{{ dirname }}/sdk/snippets/config/config-with-guest-auth.tsx" snippet="example" %}+```++Either way, you'll need to publish each item you want to embed. For publishing and the server-side code, see [guest embedding](./guest-embedding.md).++### Configure an SSO embed++Embeds use SSO unless you set `isGuest`, so there's no setting to turn SSO on. You'll need to [set up SSO in your Metabase and your app](./authentication.md).++To customize how embeds fetch the JWT, set `fetchRequestToken` in `defineMetabaseConfig()` (web components) or `defineMetabaseAuthConfig()` (SDK). See [customizing JWT authentication](./authentication.md#customizing-jwt-authentication).++### Preview embeds during development++To preview embeds without setting up authentication, use your own Metabase session or an API key. Both are for development only.++- **Use your existing session (web components only)**: in `defineMetabaseConfig()`, set `useExistingUserSession: true`. The embed renders using your Metabase session. Only supported in Google Chrome.+- **Use an API key**: set `apiKey` in `defineMetabaseConfig()` (web components) or `defineMetabaseAuthConfig()` (SDK). Only works on localhost. See [authenticating locally with API keys](./authentication.md#authenticating-locally-with-api-keys).++## Set the language++To set the display language for every embed, add a `locale` with an ISO language code. The locale defaults to your Metabase instance's locale.++Setting a locale translates Metabase's UI, like menus and filter widgets. It doesn't translate content you create, like dashboard names and filter labels. To translate your content, upload a [translation dictionary](./translations.md).++- [Web component](#web-component-locale)+- [React SDK](#react-sdk-locale)++### Web component locale++Add `locale` to the page-level config:++```html+<script>+ defineMetabaseConfig({+ instanceUrl: "https://your-metabase.example.com",+ locale: "de",+ });+</script>+```++### React SDK locale++Pass `locale` to `MetabaseProvider`:++```tsx+{% include_file "{{ dirname }}/sdk/snippets/config/config-with-locale.tsx" snippet="example" %}+```++## Set a theme++To customize colors and fonts for every embed, add a `theme` object. The theme object is the same for web components and the SDK. For all the theme options, see [Appearance](./appearance.md).++- [Web component](#web-component-theme)+- [React SDK](#react-sdk-theme)++### Web component theme++Add `theme` to the page-level config:++```html+<script>+ defineMetabaseConfig({+ instanceUrl: "https://your-metabase.example.com",+ theme: {+ colors: {+ brand: "#509EE3",+ },+ },+ });+</script>+```++### React SDK theme++Create a theme with `defineMetabaseTheme()` and pass it to `MetabaseProvider`:++```tsx+{% include_file "{{ dirname }}/sdk/snippets/config/config-with-theme.tsx" snippet="example" %}+```++## Configure plugins++To customize the behavior of embedded components, add plugins with `pluginsConfig`. Plugins you set in the shared config apply to every embed.++- [Web component](#web-component-plugins)+- [React SDK](#react-sdk-plugins)++### Web component plugins++Web components support one plugin, [`handleLink`](./sdk/plugins.md#handlelink), which customizes what happens when people click a link in an embed. Add `pluginsConfig` to the page-level config:++```html+<script>+ defineMetabaseConfig({+ instanceUrl: "https://your-metabase.example.com",+ pluginsConfig: {+ handleLink: (urlString) => {+ const url = new URL(urlString, window.location.origin);+ if (url.origin === window.location.origin) {+ // Handle the link yourself, like with your app's router+ return { handled: true };+ }+ return { handled: false }; // Open the link in a new tab+ },+ },+ });+</script>+```++### React SDK plugins++Pass `pluginsConfig` to `MetabaseProvider`:++```tsx+{% include_file "{{ dirname }}/sdk/snippets/config/config-with-plugins.tsx" snippet="example" %}+```++SDK components also take their own `plugins` prop, which overrides the global config.++For available plugins and their APIs, see [plugins](./sdk/plugins.md).++## Allow custom visualizations++To render [custom visualizations](../questions/visualizations/custom.md) in your embeds, add the `allowedCustomVisualizations` allowlist to `defineMetabaseConfig()` (web components) or pass it to `MetabaseProvider` (SDK).++Custom visualizations require SSO. Guest embeds ignore the allowlist and show the default visualization instead.++For examples and the naming rules, see [custom visualizations in embeds](./custom-visualizations.md).++## Handle embed events (React SDK only)++To run your own code when embeds load, like sending analytics events, pass an `eventHandlers` object to `MetabaseProvider`. There's no web component equivalent.++```tsx+{% include_file "{{ dirname }}/sdk/snippets/config/config-with-event-handlers.tsx" snippet="example" %}+```++`onDashboardLoad` fires when a dashboard loads with all visible cards and their content.++For the full list of handlers, see [`eventHandlers`](./config-reference.md#react-sdk-eventhandlers).++## Customize loading and error states (React SDK only)++To replace the SDK's default loading and error screens, pass `loaderComponent` and `errorComponent` to `MetabaseProvider`. There's no web component equivalent. See [Customize loading, error, and empty states](./sdk/loading-and-errors.md).++## Reload a component (React SDK only)++Metabase components don't detect your app's data changes. To reload an embed after your app's data changes, change the component's `key` prop:++```tsx+{% include_file "{{ dirname }}/sdk/snippets/config/reload-metabase-provider.tsx" snippet="example" %}+```++## Further reading++- [Config reference](./config-reference.md)+- [Appearance](./appearance.md)+- [Authentication](./authentication.md)+- [Guest embedding](./guest-embedding.md)+- [Translating embeds](./translations.md)+- [Custom visualizations in embeds](./custom-visualizations.md)+- [Modular embedding components](./components.md)+- [Modular embedding SDK](./sdk/introduction.md)diff --git a/docs/embedding/custom-visualizations.md b/docs/embedding/custom-visualizations.mdindex f8d64eb64a1..451d7a01427 100644--- a/docs/embedding/custom-visualizations.md+++ b/docs/embedding/custom-visualizations.md@@ -35,7 +35,7 @@ Where the allowlist goes depends on how you're embedding:### Web components allowlist for custom visualizations-`allowedCustomVisualizations` is a [page-level config](./modular-embedding.md#page-level-config), not an attribute on `<metabase-dashboard>` or `<metabase-question>`. The allowlist applies to every component on the page.+`allowedCustomVisualizations` is a [page-level config](./config.md#configure-web-components), not an attribute on `<metabase-dashboard>` or `<metabase-question>`. The allowlist applies to every component on the page.Add `allowedCustomVisualizations` to `defineMetabaseConfig()`:diff --git a/docs/embedding/eajs/snippets/MetabaseConfig.md b/docs/embedding/eajs/snippets/MetabaseConfig.mdnew file mode 100644index 00000000000..110d1aa76a4--- /dev/null+++ b/docs/embedding/eajs/snippets/MetabaseConfig.md@@ -0,0 +1,25 @@+Settings for `defineMetabaseConfig()`.++Page-level configuration shared by every web component on the page.++## Properties++<!-- [<snippet properties>] -->++| Property | Type | Description |+| :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| <a id="allowedcustomvisualizations"></a> `allowedCustomVisualizations` | `` `custom:${string}` ``[] | The custom visualizations that components on the page can load, each prefixed with `custom:`, like `["custom:Calendar Heatmap"]`. Not available in guest embeds. See [Custom visualizations in embeds](https://www.metabase.com/docs/latest/embedding/custom-visualizations).<br>---<br>Optional |+| <a id="apikey"></a> `apiKey` | `string` | Development only. An API key from your Metabase, which embeds use to render on localhost. See [Preview embeds during development](https://www.metabase.com/docs/latest/embedding/config#preview-embeds-during-development).<br>---<br>Optional |+| <a id="fetchrequesttoken"></a> `fetchRequestToken` | () => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<\{ `jwt`: `string`; \}\> | SSO embeds with JWT only. A function that fetches the JWT for embeds. See [Customizing JWT authentication](https://www.metabase.com/docs/latest/embedding/authentication#customizing-jwt-authentication).<br>---<br>Optional |+| <a id="guestembedprovideruri"></a> `guestEmbedProviderUri` | `string` | Guest embeds only. Your app's endpoint that signs guest tokens. The embed calls this endpoint for a token on load, and again when the current token expires. The endpoint should return `{ jwt: string }`. See [Configure a guest embed](https://www.metabase.com/docs/latest/embedding/config#configure-a-guest-embed).<br>---<br>Optional |+| <a id="instanceurl"></a> `instanceUrl` | `string` | The URL of your Metabase, like `https://youlooknicetoday.metabaseapp.com`. |+| <a id="isguest"></a> `isGuest` | `boolean` | Whether the components authenticate as guest embeds, with a signed JWT instead of a Metabase session. See [Configure a guest embed](https://www.metabase.com/docs/latest/embedding/config#configure-a-guest-embed).<br>---<br>Optional<br>Default: `false` |+| <a id="jwtprovideruri"></a> `jwtProviderUri` | `string` | SSO embeds with JWT only. The URL of your JWT provider. When set, embeds use JWT and skip the request that discovers the SSO method.<br>---<br>Optional |+| <a id="locale"></a> `locale` | `string` | The display language for every embed, as an ISO language code like `en` or `de`. Defaults to your Metabase instance's locale. See [Set the language](https://www.metabase.com/docs/latest/embedding/config#set-the-language).<br>---<br>Optional |+| <a id="pluginsconfig"></a> `pluginsConfig` | \{ `handleLink`: (`url`: `string`) => \{ `handled`: `boolean`; \}; \} | Plugins that customize component behavior. Web components support `handleLink`, for customizing what happens when people click a link. See [Web component plugins](https://www.metabase.com/docs/latest/embedding/config#web-component-plugins).<br>---<br>Optional |+| `pluginsConfig.handleLink` | (`url`: `string`) => \{ `handled`: `boolean`; \} | Called when people click a link in an embed. Return `{ handled: true }` to handle the link yourself, or `{ handled: false }` to open the link in a new tab.<br>---<br>Optional |+| <a id="preferredauthmethod"></a> `preferredAuthMethod` | `string` | SSO embeds only. Which SSO method to use. If you've set up both SAML and JWT, embeds default to SAML. See [Authentication](https://www.metabase.com/docs/latest/embedding/authentication#if-both-saml-and-jwt-are-enabled-modular-embedding-will-default-to-saml).<br>---<br>Optional<br>Possible values: `"jwt"`, `"saml"` |+| <a id="theme"></a> `theme` | `object` | Colors, fonts, and per-component appearance overrides. See [Appearance](https://www.metabase.com/docs/latest/embedding/appearance).<br>---<br>Optional |+| <a id="useexistingusersession"></a> `useExistingUserSession` | `boolean` | Development only. Whether to render embeds with your own Metabase session. Only supported in Google Chrome. See [Preview embeds during development](https://www.metabase.com/docs/latest/embedding/config#preview-embeds-during-development).<br>---<br>Optional<br>Default: `false` |++<!-- [<endsnippet properties>] -->diff --git a/docs/embedding/eajs/snippets/index.md b/docs/embedding/eajs/snippets/index.mdindex e39147cb73e..cc0e2f9a8f8 100644--- a/docs/embedding/eajs/snippets/index.md+++ b/docs/embedding/eajs/snippets/index.md@@ -7,6 +7,7 @@ This is the source of truth for all attributes accepted by modular embedding com| Interface | Description || :------------------------------------------------------------ | :------------------------------------------------------- || [MetabaseBrowserAttributes](MetabaseBrowserAttributes.md) | Attributes for the `<metabase-browser>` web component. |+| [MetabaseConfig](MetabaseConfig.md) | Settings for `defineMetabaseConfig()`. || [MetabaseDashboardAttributes](MetabaseDashboardAttributes.md) | Attributes for the `<metabase-dashboard>` web component. || [MetabaseMetabotAttributes](MetabaseMetabotAttributes.md) | Attributes for the `<metabase-metabot>` web component. || [MetabaseQuestionAttributes](MetabaseQuestionAttributes.md) | Attributes for the `<metabase-question>` web component. |diff --git a/docs/embedding/modular-embedding.md b/docs/embedding/modular-embedding.mdindex 83aba0ab060..15d9ddc399b 100644--- a/docs/embedding/modular-embedding.md+++ b/docs/embedding/modular-embedding.md@@ -184,21 +184,7 @@ See [Modular embedding parameters](./parameters.md#pass-parameter-values-to-embe## Page-level config-To define the configuration that applies to every embed on the page, use the `defineMetabaseConfig()` function. Its parameters include:--- `instanceUrl: "https://your-metabase-url"` (required): the URL of your Metabase instance, like `https://youlooknicetoday.metabaseapp.com`--- `theme: {...}` (optional): [appearance options for the embeds](./appearance.md).--- `useExistingUserSession: true|false` (optional, for development only) - lets you preview the embed locally using your Metabase admin account session. Only supported in Google Chrome.--- `apiKey: mb_YourAPIKey` (optional, for development only) - another way to preview embeds locally using an API key.--- `fetchRequestToken: () => Promise<{ jwt: string }>` (optional) - you can customize how the SDK fetches the refresh token for JWT authentication by specifying the `fetchRequestToken` function. See [customizing JWT authentication](./authentication.md#customizing-jwt-authentication).--- `pluginsConfig` : plugins to customize the behavior of embedded components. Use the `handleLink` function to customize what happens when people click a link in your embedded questions and dashboards. For details on the `handleLink` API, including code examples, see [`handleLink` plugin](./sdk/plugins.md#handlelink).--- `allowedCustomVisualizations: ["custom:Calendar Heatmap"]` (optional): the [custom visualizations](./custom-visualizations.md) that the components on the page are allowed to load. Not available in guest embeds.+To define the configuration that applies to every embed on the page, like the URL of your Metabase, the authentication mode, and the theme, use the `defineMetabaseConfig()` function. See [Configure your embeds](./config.md). For the full list of settings, see the [config reference](./config-reference.md#web-component-definemetabaseconfig-settings).## Authenticationdiff --git a/docs/embedding/sdk/api/MetabaseProvider.html b/docs/embedding/sdk/api/MetabaseProvider.htmlindex ed528a9f341..0486e237ced 100644--- a/docs/embedding/sdk/api/MetabaseProvider.html+++ b/docs/embedding/sdk/api/MetabaseProvider.html@@ -17,7 +17,7 @@ listed plugins are loaded. Omit or pass <code>[]</code> to disable.</p></div></li><li class="tsd-parameter"><h5 id="classname"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">className</span><span class="tsd-signature-symbol">?: </span><span class="tsd-signature-type">string</span></h5><div class="tsd-comment tsd-typography"><p>A custom class name to be added to the root element.</p></div><div class="tsd-comment tsd-typography"><div class="tsd-tag-deprecated"><h4 class="tsd-anchor-link" id="deprecated">Deprecated<a href="#deprecated" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>This prop is not used anymore.</p></div></div></li><li class="tsd-parameter"><h5 id="errorcomponent"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">errorComponent</span><span class="tsd-signature-symbol">?: </span><a href="SdkErrorComponent.html" class="tsd-signature-type tsd-kind-type-alias">SdkErrorComponent</a></h5><div class="tsd-comment tsd-typography"><p>A custom error component to display when the SDK encounters an error.</p>-</div></li><li class="tsd-parameter"><h5 id="eventhandlers"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">eventHandlers</span><span class="tsd-signature-symbol">?: </span><a href="SdkEventHandlersConfig.html" class="tsd-signature-type tsd-kind-type-alias">SdkEventHandlersConfig</a></h5><div class="tsd-comment tsd-typography"><p>See <a href="https://www.metabase.com/docs/latest/embedding/sdk/config#global-event-handlers">Global event handlers</a>.</p>+</div></li><li class="tsd-parameter"><h5 id="eventhandlers"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">eventHandlers</span><span class="tsd-signature-symbol">?: </span><a href="SdkEventHandlersConfig.html" class="tsd-signature-type tsd-kind-type-alias">SdkEventHandlersConfig</a></h5><div class="tsd-comment tsd-typography"><p>See <a href="https://www.metabase.com/docs/latest/embedding/config#handle-embed-events-react-sdk-only">Handle embed events</a>.</p></div></li><li class="tsd-parameter"><h5 id="loadercomponent"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">loaderComponent</span><span class="tsd-signature-symbol">?: </span><a href="https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0b728411cd1dfb4bd26992bb35a73cf8edaa22e7/types/react/index.d.ts#L104" class="tsd-signature-type external" target="_blank">ComponentType</a><span class="tsd-signature-symbol"><</span><span class="tsd-signature-symbol">{</span> <span class="tsd-kind-property">label</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">></span></h5><div class="tsd-comment tsd-typography"><p>A custom loader component to display while the SDK is loading.</p><p>The component receives an optional <code>label</code> prop that can be used to display a loading message.</p></div></li><li class="tsd-parameter"><h5 id="locale"><code class="tsd-tag">Optional</code><span class="tsd-kind-property">locale</span><span class="tsd-signature-symbol">?: </span><span class="tsd-signature-type">string</span></h5><div class="tsd-comment tsd-typography"><p>Defines the display language. Accepts an ISO language code such as <code>en</code> or <code>de</code>.diff --git a/docs/embedding/sdk/api/MetabaseProviderProps.html b/docs/embedding/sdk/api/MetabaseProviderProps.htmlindex c1715e92a73..a86fcd0f873 100644--- a/docs/embedding/sdk/api/MetabaseProviderProps.html+++ b/docs/embedding/sdk/api/MetabaseProviderProps.html@@ -28,7 +28,7 @@ listed plugins are loaded. Omit or pass <code>[]</code> to disable.</p></div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="classname"><code class="tsd-tag">Optional</code><span class="deprecated">class<wbr/>Name</span><a href="#classname" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">className</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span></div><div class="tsd-comment tsd-typography"><p>A custom class name to be added to the root element.</p></div><div class="tsd-comment tsd-typography"><div class="tsd-tag-deprecated"><h4 class="tsd-anchor-link" id="deprecated">Deprecated<a href="#deprecated" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>This prop is not used anymore.</p></div></div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="errorcomponent"><code class="tsd-tag">Optional</code><span>error<wbr/>Component</span><a href="#errorcomponent" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">errorComponent</span><span class="tsd-signature-symbol">?:</span> <a href="SdkErrorComponent.html" class="tsd-signature-type tsd-kind-type-alias">SdkErrorComponent</a></div><div class="tsd-comment tsd-typography"><p>A custom error component to display when the SDK encounters an error.</p>-</div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="eventhandlers"><code class="tsd-tag">Optional</code><span>event<wbr/>Handlers</span><a href="#eventhandlers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">eventHandlers</span><span class="tsd-signature-symbol">?:</span> <a href="SdkEventHandlersConfig.html" class="tsd-signature-type tsd-kind-type-alias">SdkEventHandlersConfig</a></div><div class="tsd-comment tsd-typography"><p>See <a href="https://www.metabase.com/docs/latest/embedding/sdk/config#global-event-handlers">Global event handlers</a>.</p>+</div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="eventhandlers"><code class="tsd-tag">Optional</code><span>event<wbr/>Handlers</span><a href="#eventhandlers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">eventHandlers</span><span class="tsd-signature-symbol">?:</span> <a href="SdkEventHandlersConfig.html" class="tsd-signature-type tsd-kind-type-alias">SdkEventHandlersConfig</a></div><div class="tsd-comment tsd-typography"><p>See <a href="https://www.metabase.com/docs/latest/embedding/config#handle-embed-events-react-sdk-only">Handle embed events</a>.</p></div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="loadercomponent"><code class="tsd-tag">Optional</code><span>loader<wbr/>Component</span><a href="#loadercomponent" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">loaderComponent</span><span class="tsd-signature-symbol">?:</span> <a href="https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0b728411cd1dfb4bd26992bb35a73cf8edaa22e7/types/react/index.d.ts#L104" class="tsd-signature-type external" target="_blank">ComponentType</a><span class="tsd-signature-symbol"><</span><span class="tsd-signature-symbol">{</span> <span class="tsd-kind-property">label</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">></span></div><div class="tsd-comment tsd-typography"><p>A custom loader component to display while the SDK is loading.</p><p>The component receives an optional <code>label</code> prop that can be used to display a loading message.</p></div></section><section class="tsd-panel tsd-member"><h3 class="tsd-anchor-link" id="locale"><code class="tsd-tag">Optional</code><span>locale</span><a href="#locale" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><div class="tsd-signature"><span class="tsd-kind-property">locale</span><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span></div><div class="tsd-comment tsd-typography"><p>Defines the display language. Accepts an ISO language code such as <code>en</code> or <code>de</code>.diff --git a/docs/embedding/sdk/api/snippets/MetabaseProviderProps.md b/docs/embedding/sdk/api/snippets/MetabaseProviderProps.mdindex 795bf09264f..a30217d82cb 100644--- a/docs/embedding/sdk/api/snippets/MetabaseProviderProps.md+++ b/docs/embedding/sdk/api/snippets/MetabaseProviderProps.md@@ -12,7 +12,7 @@| <a id="children"></a> `children` | [`ReactNode`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0b728411cd1dfb4bd26992bb35a73cf8edaa22e7/types/react/index.d.ts#L478) | The children of the MetabaseProvider component. || <a id="classname"></a> ~~`className?`~~ | `string` | A custom class name to be added to the root element. **Deprecated** This prop is not used anymore. || <a id="errorcomponent"></a> `errorComponent?` | [`SdkErrorComponent`](./api/SdkErrorComponent.md) | A custom error component to display when the SDK encounters an error. |-| <a id="eventhandlers"></a> `eventHandlers?` | [`SdkEventHandlersConfig`](./api/SdkEventHandlersConfig.md) | See [Global event handlers](https://www.metabase.com/docs/latest/embedding/sdk/config#global-event-handlers). |+| <a id="eventhandlers"></a> `eventHandlers?` | [`SdkEventHandlersConfig`](./api/SdkEventHandlersConfig.md) | See [Handle embed events](https://www.metabase.com/docs/latest/embedding/config#handle-embed-events-react-sdk-only). || <a id="loadercomponent"></a> `loaderComponent?` | [`ComponentType`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0b728411cd1dfb4bd26992bb35a73cf8edaa22e7/types/react/index.d.ts#L104)\<\{ `label?`: `string`; \}\> | A custom loader component to display while the SDK is loading. The component receives an optional `label` prop that can be used to display a loading message. || <a id="locale"></a> `locale?` | `string` | Defines the display language. Accepts an ISO language code such as `en` or `de`. Defaults to the instance locale. || <a id="pluginsconfig"></a> `pluginsConfig?` | [`MetabaseGlobalPluginsConfig`](./api/MetabaseGlobalPluginsConfig.md) | See [Plugins](https://www.metabase.com/docs/latest/embedding/sdk/plugins). |diff --git a/docs/embedding/sdk/config.md b/docs/embedding/sdk/config.mddeleted file mode 100644index 0438f4bed2c..00000000000--- a/docs/embedding/sdk/config.md+++ /dev/null@@ -1,71 +0,0 @@-----title: Modular embedding SDK - config-summary: Configure the Metabase modular embedding SDK with MetabaseProvider, set up authentication, handle global events, and reload embedded components.------# Modular embedding SDK - config--{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true %}--## Passing a configuration object to `MetabaseProvider`--To use the SDK in your app, you need to import the `MetabaseProvider` component and provide it with an `authConfig` object.--### `MetabaseProvider`--A component that configures the SDK and provides the Metabase SDK's context and theme.--To pass a theme, use `defineMetabaseTheme`. See [Reuse a saved theme in the SDK](../appearance.md#reuse-a-saved-theme-in-the-sdk).--#### API Reference--- [Component](./api/MetabaseProvider.html)-- [Props](./api/MetabaseProviderProps.html)--#### Example--```typescript-{% include_file "{{ dirname }}/snippets/config/config-base.tsx" %}-```--#### Props--{% include_file "{{ dirname }}/api/snippets/MetabaseProviderProps.md" snippet="properties" %}--## Custom visualizations--The SDK can render [custom visualizations](../../questions/visualizations/custom.md) that you allowlist with the `allowedCustomVisualizations` prop on `MetabaseProvider`. See [Custom visualizations in embeds](../custom-visualizations.md).--## Loading and error components--The `loaderComponent` and `errorComponent` props swap the SDK's default loading and error screens for your own React components. See [Customize loading, error, and empty states](./loading-and-errors.md).--## Global event handlers--You can listen for events by defining the `eventHandlers` prop for `MetabaseProvider`.--### `SdkEventHandlersConfig`--Accepts an object where each key is an event type and the corresponding value is the event handler function.--#### API Reference--- [Type](./api/SdkEventHandlersConfig.html)--#### Example--```typescript-{% include_file "{{ dirname }}/snippets/config/config-with-event-handlers.tsx" snippet="example" %}-```--#### Props--{% include_file "{{ dirname }}/api/snippets/SdkEventHandlersConfig.md" snippet="properties" %}--## Reloading Metabase components--In case you need to reload a Metabase component, for example, your users modify your application data and that data is used to render a question in Metabase. If you embed this question and want to force Metabase to reload the question to show the latest data, you can do so by using the `key` prop to force a component to reload.--```typescript-{% include_file "{{ dirname }}/snippets/config/reload-metabase-provider.tsx" snippet="example" %}-```diff --git a/docs/embedding/sdk/introduction.md b/docs/embedding/sdk/introduction.mdindex 0c210c751ba..9ecde17f109 100644--- a/docs/embedding/sdk/introduction.md+++ b/docs/embedding/sdk/introduction.md@@ -112,7 +112,7 @@ Start with one of the quickstarts, then see these pages for more info on compone- [Embed a collection browser](../browser.md)- [Custom visualizations](../custom-visualizations.md)- [Plugins](./plugins.md)-- [Config](./config.md)+- [Configure your embeds](../config.md)- [Customize loading, error, and empty states](./loading-and-errors.md)- [Versioning](./version.md)- [Notes on Next.js](./next-js.md)diff --git a/docs/embedding/sdk/loading-and-errors.md b/docs/embedding/sdk/loading-and-errors.mdindex 32c5f0d4475..3fb94a31f42 100644--- a/docs/embedding/sdk/loading-and-errors.md+++ b/docs/embedding/sdk/loading-and-errors.md@@ -47,5 +47,5 @@ Unlike `loaderComponent` and `errorComponent`, these are [plugins](./plugins.md)- [Modular embedding SDK plugins](./plugins.md)- [Appearance](../appearance.md)-- [Modular embedding SDK config](./config.md)+- [Configure your embeds](../config.md)- [Modular embedding components](../components.md)diff --git a/docs/embedding/sdk/plugins.md b/docs/embedding/sdk/plugins.mdindex 885449093f8..a6bc2260c0c 100644--- a/docs/embedding/sdk/plugins.md+++ b/docs/embedding/sdk/plugins.md@@ -52,7 +52,7 @@ By default, links open in a new tab. Use `handleLink` to intercept link clicksThe function receives a URL string. Return `{ handled: true }` to prevent default navigation, or `{ handled: false }` to open the link in a new tab.-The plugin `handleLink` can only be used [globally](#plugin-scope) on provider level. `handleLink` is also available in [modular embedding](../modular-embedding.md#page-level-config) via `pluginsConfig` in `defineMetabaseConfig`, with the same API.+The plugin `handleLink` can only be used [globally](#plugin-scope) on provider level. `handleLink` is also available in [web components](../config.md#web-component-plugins) via `pluginsConfig` in `defineMetabaseConfig`, with the same API.To create clickable links in your table columns, set the column's formatting to [display as link](../../data-modeling/metadata/formatting.md#display-as).diff --git a/docs/embedding/sdk/snippets/config/config-base.tsx b/docs/embedding/sdk/snippets/config/config-base.tsxindex e81bfb552c8..3abdd007718 100644--- a/docs/embedding/sdk/snippets/config/config-base.tsx+++ b/docs/embedding/sdk/snippets/config/config-base.tsx@@ -1,37 +1,19 @@import React from "react";import {MetabaseProvider,+ StaticDashboard,defineMetabaseAuthConfig,- defineMetabaseTheme,} from "@metabase/embedding-sdk-react";-// Configure authenticationconst authConfig = defineMetabaseAuthConfig({- metabaseInstanceUrl: "https://metabase.example.com", // Required: Your Metabase instance URL-});--// See the "Customizing appearance" section for more information-const theme = defineMetabaseTheme({- // Optional: Specify a font to use from the set of fonts supported by Metabase- fontFamily: "Lato",-- // Optional: Match your application's color scheme- colors: {- brand: "#9B5966",- "text-primary": "#4C5773",- "text-secondary": "#696E7B",- "text-tertiary": "#949AAB",- },+ metabaseInstanceUrl: "https://your-metabase.example.com", // Required});export default function App() {return (- <MetabaseProvider- authConfig={authConfig}- theme={theme}- className="optional-class"- >- Hello World!+ <MetabaseProvider authConfig={authConfig}>+ {/* Metabase components go here */}+ <StaticDashboard dashboardId={1} /></MetabaseProvider>);}diff --git a/docs/embedding/sdk/snippets/config/config-with-event-handlers.tsx b/docs/embedding/sdk/snippets/config/config-with-event-handlers.tsxindex 9e52d579c59..7b71ef81da2 100644--- a/docs/embedding/sdk/snippets/config/config-with-event-handlers.tsx+++ b/docs/embedding/sdk/snippets/config/config-with-event-handlers.tsx@@ -1,23 +1,20 @@import type { PropsWithChildren } from "react";import {+ type MetabaseAuthConfig,MetabaseProvider,type SdkDashboardLoadEvent,- defineMetabaseAuthConfig,} from "@metabase/embedding-sdk-react";-const authConfig = defineMetabaseAuthConfig({- metabaseInstanceUrl: "",-});+const authConfig = {} as MetabaseAuthConfig;const Example = ({ children }: PropsWithChildren) => {// [<snippet example>]const handleDashboardLoad: SdkDashboardLoadEvent = (dashboard) => {- /* do whatever you need to do - e.g. send analytics events, show notifications */+ // Send analytics events, show notifications, etc.};const eventHandlers = {onDashboardLoad: handleDashboardLoad,- onDashboardLoadWithoutCards: handleDashboardLoad,};return (diff --git a/docs/embedding/sdk/snippets/config/config-with-guest-auth.tsx b/docs/embedding/sdk/snippets/config/config-with-guest-auth.tsxnew file mode 100644index 00000000000..f0cb799b4cd--- /dev/null+++ b/docs/embedding/sdk/snippets/config/config-with-guest-auth.tsx@@ -0,0 +1,23 @@+import {+ MetabaseProvider,+ StaticDashboard,+ defineMetabaseAuthConfig,+} from "@metabase/embedding-sdk-react";++// [<snippet example>]+// A JWT that your server signs with your Metabase embedding secret key.+const token = "YOUR_SIGNED_JWT";++const authConfig = defineMetabaseAuthConfig({+ metabaseInstanceUrl: "https://your-metabase.example.com",+ isGuest: true,+});++export default function App() {+ return (+ <MetabaseProvider authConfig={authConfig}>+ <StaticDashboard token={token} />+ </MetabaseProvider>+ );+}+// [<endsnippet example>]diff --git a/docs/embedding/sdk/snippets/config/config-with-locale.tsx b/docs/embedding/sdk/snippets/config/config-with-locale.tsxnew file mode 100644index 00000000000..dd5a263edfd--- /dev/null+++ b/docs/embedding/sdk/snippets/config/config-with-locale.tsx@@ -0,0 +1,15 @@+import type { PropsWithChildren } from "react";+import {+ type MetabaseAuthConfig,+ MetabaseProvider,+} from "@metabase/embedding-sdk-react";++const authConfig = {} as MetabaseAuthConfig;++const Example = ({ children }: PropsWithChildren) => (+ // [<snippet example>]+ <MetabaseProvider authConfig={authConfig} locale="de">+ {children}+ </MetabaseProvider>+ // [<endsnippet example>]+);diff --git a/docs/embedding/sdk/snippets/config/config-with-plugins.tsx b/docs/embedding/sdk/snippets/config/config-with-plugins.tsxnew file mode 100644index 00000000000..91c6f1e074e--- /dev/null+++ b/docs/embedding/sdk/snippets/config/config-with-plugins.tsx@@ -0,0 +1,21 @@+import type { PropsWithChildren } from "react";+import {+ type MetabaseAuthConfig,+ MetabaseProvider,+} from "@metabase/embedding-sdk-react";++const authConfig = {} as MetabaseAuthConfig;++const Example = ({ children }: PropsWithChildren) => (+ // [<snippet example>]+ <MetabaseProvider+ authConfig={authConfig}+ pluginsConfig={{+ // Return the default actions, plus any custom actions you add+ mapQuestionClickActions: (clickActions) => clickActions,+ }}+ >+ {children}+ </MetabaseProvider>+ // [<endsnippet example>]+);diff --git a/docs/embedding/sdk/snippets/config/config-with-theme.tsx b/docs/embedding/sdk/snippets/config/config-with-theme.tsxnew file mode 100644index 00000000000..6be1df0c206--- /dev/null+++ b/docs/embedding/sdk/snippets/config/config-with-theme.tsx@@ -0,0 +1,24 @@+import type { PropsWithChildren } from "react";+import {+ type MetabaseAuthConfig,+ MetabaseProvider,+ defineMetabaseTheme,+} from "@metabase/embedding-sdk-react";++const authConfig = {} as MetabaseAuthConfig;++const Example = ({ children }: PropsWithChildren) => {+ // [<snippet example>]+ const theme = defineMetabaseTheme({+ colors: {+ brand: "#509EE3",+ },+ });++ return (+ <MetabaseProvider authConfig={authConfig} theme={theme}>+ {children}+ </MetabaseProvider>+ );+ // [<endsnippet example>]+};diff --git a/docs/embedding/sdk/snippets/config/reload-metabase-provider.tsx b/docs/embedding/sdk/snippets/config/reload-metabase-provider.tsxindex 6c9e3a8cf2a..41e2a72dd06 100644--- a/docs/embedding/sdk/snippets/config/reload-metabase-provider.tsx+++ b/docs/embedding/sdk/snippets/config/reload-metabase-provider.tsx@@ -1,37 +1,27 @@-import { useEffect, useState } from "react";+import { useState } from "react";import { InteractiveQuestion } from "@metabase/embedding-sdk-react";-import { isEqual } from "underscore";const yourQuestionId = 1;+const order = {};++const api = {+ saveOrder: async (order: unknown) => {},+};const Example = () => {// [<snippet example>]- // Inside your application component- const [data, setData] = useState({});- // This is used to force reloading Metabase components- const [counter, setCounter] = useState(0);+ const [dataVersion, setDataVersion] = useState(0);- // This ensures we only change the `data` reference when it's actually changed- const handleDataChange = newData => {- setData(prevData => {- if (isEqual(prevData, newData)) {- return prevData;- }-- return newData;- });+ const saveOrder = async (order) => {+ await api.saveOrder(order); // Your app changes its data...+ setDataVersion((v) => v + 1); // ...then changes the key, reloading the embed.};- useEffect(() => {- /**- * When you set `data` as the `useEffect` hook's dependency, it will trigger the effect- * and increment the counter which is used in a Metabase component's `key` prop, forcing it to reload.- */- if (data) {- setCounter(counter => counter + 1);- }- }, [data]);-- return <InteractiveQuestion key={counter} questionId={yourQuestionId} />;+ return (+ <>+ <button onClick={() => saveOrder(order)}>Save order</button>+ <InteractiveQuestion key={dataVersion} questionId={yourQuestionId} />+ </>+ );// [<endsnippet example>]};diff --git a/docs/embedding/start.md b/docs/embedding/start.mdindex 0ce3651a833..d64658164af 100644--- a/docs/embedding/start.md+++ b/docs/embedding/start.md@@ -62,6 +62,14 @@ Every `<metabase-browser>` attribute and the `CollectionBrowser` props.Embed an AI chat with web components or the React SDK, so people can ask questions of their data in natural language.+### [Configure your embeds](./config.md)++Set the configuration that every embed on a page shares, like your Metabase URL, authentication, language, and theme, with web components or the React SDK.++### [Config reference](./config-reference.md)++Every `defineMetabaseConfig()` setting for web components, and the `MetabaseProvider` props for the React SDK.+### [Guest embedding](./guest-embedding.md)Guest embedding is a secure way to embed charts and dashboards. Guest embeds are view-only; people won't be able to drill-through charts and tables.diff --git a/docs/util/data/nav.yml b/docs/util/data/nav.ymlindex 9c86a9134ba..b7b2cfd1321 100644--- a/docs/util/data/nav.yml+++ b/docs/util/data/nav.yml@@ -280,6 +280,10 @@ categories:url: "embedding/ai-chat"- name: "Filters and parameters"url: "embedding/parameters"+ - name: "Config"+ url: "embedding/config"+ - name: "Config reference"+ url: "embedding/config-reference"- name: "Appearance"url: "embedding/appearance"- name: "Custom visualizations"@@ -302,8 +306,6 @@ categories:url: "embedding/sdk/loading-and-errors"- name: "Configuration"pages:- - name: "Provider config"- url: "embedding/sdk/config"- name: "Working with Next.js"url: "embedding/sdk/next-js"- name: "Versioning"diff --git a/frontend/src/embedding-sdk-bundle/types/metabase-provider.ts b/frontend/src/embedding-sdk-bundle/types/metabase-provider.tsindex 6a4b7299d1c..43b4d75cf2e 100644--- a/frontend/src/embedding-sdk-bundle/types/metabase-provider.ts+++ b/frontend/src/embedding-sdk-bundle/types/metabase-provider.ts@@ -40,7 +40,7 @@ export interface MetabaseProviderProps {pluginsConfig?: MetabaseGlobalPluginsConfig;/**- * See [Global event handlers](https://www.metabase.com/docs/latest/embedding/sdk/config#global-event-handlers).+ * See [Handle embed events](https://www.metabase.com/docs/latest/embedding/config#handle-embed-events-react-sdk-only).*/eventHandlers?: SdkEventHandlersConfig;diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk/constants.ts b/frontend/src/metabase/embedding/embedding-iframe-sdk/constants.tsindex 18a406e22d1..64950638131 100644--- a/frontend/src/metabase/embedding/embedding-iframe-sdk/constants.ts+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk/constants.ts@@ -7,6 +7,7 @@ import type {SdkIframeEmbedBaseSettings,SdkIframeEmbedSettingKey,} from "./types/embed";+import type { MetabaseConfig } from "./types/modular-embedding";/*** The timeout to wait for a session token from the embed.js script.@@ -30,7 +31,8 @@ export const ALLOWED_EMBED_SETTING_KEYS_MAP = {"pluginsConfig","guestEmbedProviderUri","allowedCustomVisualizations",- ] satisfies (keyof SdkIframeEmbedBaseSettings)[],+ // Every allowed setting must be documented in `MetabaseConfig`+ ] satisfies (keyof SdkIframeEmbedBaseSettings & keyof MetabaseConfig)[],dashboard: ["dashboardId","autoRefreshInterval",diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts b/frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.tsindex 3e18d6f5546..792a907cb30 100644--- a/frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts@@ -337,6 +337,105 @@ export interface MetabaseMetabotAttributes {"target-collection"?: number | string;}+/**+ * Settings for `defineMetabaseConfig()`.+ *+ * Page-level configuration shared by every web component on the page.+ */+export interface MetabaseConfig {+ /**+ * The URL of your Metabase, like `https://youlooknicetoday.metabaseapp.com`.+ */+ instanceUrl: string;++ /**+ * Whether the components authenticate as guest embeds, with a signed JWT+ * instead of a Metabase session. See+ * [Configure a guest embed](https://www.metabase.com/docs/latest/embedding/config#configure-a-guest-embed).+ *+ * @defaultValue false+ */+ isGuest?: boolean;++ /**+ * Guest embeds only. Your app's endpoint that signs guest tokens. The embed+ * calls this endpoint for a token on load, and again when the current token+ * expires. The endpoint should return `{ jwt: string }`. See+ * [Configure a guest embed](https://www.metabase.com/docs/latest/embedding/config#configure-a-guest-embed).+ */+ guestEmbedProviderUri?: string;++ /**+ * The display language for every embed, as an ISO language code like `en`+ * or `de`. Defaults to your Metabase instance's locale. See+ * [Set the language](https://www.metabase.com/docs/latest/embedding/config#set-the-language).+ */+ locale?: string;++ /**+ * Colors, fonts, and per-component appearance overrides. See+ * [Appearance](https://www.metabase.com/docs/latest/embedding/appearance).+ */+ theme?: object;++ /**+ * Plugins that customize component behavior. Web components support+ * `handleLink`, for customizing what happens when people click a link.+ * See [Web component plugins](https://www.metabase.com/docs/latest/embedding/config#web-component-plugins).+ */+ pluginsConfig?: {+ /**+ * Called when people click a link in an embed. Return `{ handled: true }`+ * to handle the link yourself, or `{ handled: false }` to open the link+ * in a new tab.+ */+ handleLink?: (url: string) => { handled: boolean };+ };++ /**+ * The custom visualizations that components on the page can load, each+ * prefixed with `custom:`, like `["custom:Calendar Heatmap"]`. Not available+ * in guest embeds. See+ * [Custom visualizations in embeds](https://www.metabase.com/docs/latest/embedding/custom-visualizations).+ */+ allowedCustomVisualizations?: `custom:${string}`[];++ /**+ * SSO embeds only. Which SSO method to use. If you've set up both SAML and+ * JWT, embeds default to SAML. See+ * [Authentication](https://www.metabase.com/docs/latest/embedding/authentication#if-both-saml-and-jwt-are-enabled-modular-embedding-will-default-to-saml).+ */+ preferredAuthMethod?: "jwt" | "saml";++ /**+ * SSO embeds with JWT only. The URL of your JWT provider. When set, embeds+ * use JWT and skip the request that discovers the SSO method.+ */+ jwtProviderUri?: string;++ /**+ * SSO embeds with JWT only. A function that fetches the JWT for embeds. See+ * [Customizing JWT authentication](https://www.metabase.com/docs/latest/embedding/authentication#customizing-jwt-authentication).+ */+ fetchRequestToken?: () => Promise<{ jwt: string }>;++ /**+ * Development only. Whether to render embeds with your own Metabase+ * session. Only supported in Google Chrome. See+ * [Preview embeds during development](https://www.metabase.com/docs/latest/embedding/config#preview-embeds-during-development).+ *+ * @defaultValue false+ */+ useExistingUserSession?: boolean;++ /**+ * Development only. An API key from your Metabase, which embeds use to+ * render on localhost. See+ * [Preview embeds during development](https://www.metabase.com/docs/latest/embedding/config#preview-embeds-during-development).+ */+ apiKey?: string;+}+/*** Used to enforce types in frontend/src/metabase/embedding/embedding-iframe-sdk/embed.ts*