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
feat(embed-js): better error message when useExistingUserSession fails (#63125)
Phoomparin Mano3fddbec54e20
diff --git a/e2e/test/scenarios/embedding/sdk-iframe-embedding/authentication.cy.spec.ts b/e2e/test/scenarios/embedding/sdk-iframe-embedding/authentication.cy.spec.tsindex 0afcf0c5844..8f76dc43d40 100644--- a/e2e/test/scenarios/embedding/sdk-iframe-embedding/authentication.cy.spec.ts+++ b/e2e/test/scenarios/embedding/sdk-iframe-embedding/authentication.cy.spec.ts@@ -48,6 +48,37 @@ describe("scenarios > embedding > sdk iframe embedding > authentication", () =>assertDashboardLoaded(frame);});+ it("cannot use existing user session when there is no session", () => {+ H.prepareSdkIframeEmbedTest({ enabledAuthMethods: [], signOut: true });++ const frame = H.loadSdkIframeEmbedTestPage({+ elements: [+ {+ component: "metabase-dashboard",+ attributes: { dashboardId: ORDERS_DASHBOARD_ID },+ },+ ],++ metabaseConfig: { useExistingUserSession: true },+ });++ frame.within(() => {+ cy.findByTestId("sdk-error-container", { timeout: 10_000 }).should(+ "contain",+ /Failed to authenticate using an existing Metabase user session./,+ );++ cy.findByRole("link", { name: "Read more." })+ .should("have.attr", "href")+ .and(+ "include",+ "https://www.metabase.com/docs/latest/embedding/embedded-analytics-js#use-existing-user-session-to-test-embeds",+ );++ cy.findByTestId("sdk-error-container").should("be.visible");+ });+ });+it("cannot use existing user session when useExistingUserSession is false", () => {H.prepareSdkIframeEmbedTest({ enabledAuthMethods: [], signOut: false });diff --git a/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/PublicComponentWrapper.tsx b/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/PublicComponentWrapper.tsxindex 148031fab29..ceb331824da 100644--- a/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/PublicComponentWrapper.tsx+++ b/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/PublicComponentWrapper.tsx@@ -31,7 +31,9 @@ export const PublicComponentWrapper = forwardRef<}if (loginStatus.status === "error") {- content = <SdkError message={loginStatus.error.message} />;+ content = (+ <SdkError message={loginStatus.error.message} error={loginStatus.error} />+ );}// The SDK components should not load if there is a license error.diff --git a/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/SdkError.tsx b/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/SdkError.tsxindex 0bcd5637e23..aa87cdd4480 100644--- a/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/SdkError.tsx+++ b/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/SdkError.tsx@@ -1,17 +1,20 @@import { useDisclosure } from "@mantine/hooks";-import type { CSSProperties, PropsWithChildren } from "react";+import { type CSSProperties, type PropsWithChildren, useMemo } from "react";import { jt, t } from "ttag";+import { ERROR_DOC_LINKS } from "embedding-sdk-bundle/errors";+import type { MetabaseErrorCode } from "embedding-sdk-bundle/errors/error-code";import { useSdkSelector } from "embedding-sdk-bundle/store";import { getErrorComponent } from "embedding-sdk-bundle/store/selectors";import type { SdkErrorComponentProps } from "embedding-sdk-bundle/types";import Alert from "metabase/common/components/Alert";import { EMBEDDING_SDK_PORTAL_ROOT_ELEMENT_ID } from "metabase/embedding-sdk/config";import { color } from "metabase/lib/colors";-import { Box, Center, Code, Flex, Portal } from "metabase/ui";+import { Anchor, Box, Center, Code, Flex, Portal } from "metabase/ui";export const SdkError = ({message,+ error,type = "relative",withCloseButton = false,}: Omit<SdkErrorComponentProps, "onClose">) => {@@ -19,6 +22,27 @@ export const SdkError = ({const CustomError = useSdkSelector(getErrorComponent);+ const errorMessage = useMemo(() => {+ if (error && "code" in error && typeof error.code === "string") {+ const docsLink = ERROR_DOC_LINKS[error.code as MetabaseErrorCode];++ if (docsLink) {+ return (+ <span>+ {error.message || message}{" "}+ <Anchor+ href={docsLink}+ target="_blank"+ rel="noopener noreferrer"+ >{t`Read more.`}</Anchor>+ </span>+ );+ }+ }++ return message;+ }, [message, error]);+if (!visible) {return null;}@@ -33,7 +57,7 @@ export const SdkError = ({<Center h="100%" w="100%" mx="auto" data-testid="sdk-error-container"><ErrorMessageComponenttype={type}- message={message}+ message={errorMessage}{...(withCloseButton && {onClose: handleBannerClose,})}diff --git a/enterprise/frontend/src/embedding-sdk-bundle/errors/base.ts b/enterprise/frontend/src/embedding-sdk-bundle/errors/base.tsindex eb2c61849b6..e3ab7948cc0 100644--- a/enterprise/frontend/src/embedding-sdk-bundle/errors/base.ts+++ b/enterprise/frontend/src/embedding-sdk-bundle/errors/base.ts@@ -1,4 +1,6 @@-export class MetabaseError<C extends string, P> extends Error {+import type { MetabaseErrorCode } from "./error-code";++export class MetabaseError<C extends MetabaseErrorCode, P> extends Error {public readonly code: C;public readonly params?: P;diff --git a/enterprise/frontend/src/embedding-sdk-bundle/errors/error-code.ts b/enterprise/frontend/src/embedding-sdk-bundle/errors/error-code.tsnew file mode 100644index 00000000000..ceecd6e1ac1--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-bundle/errors/error-code.ts@@ -0,0 +1,17 @@+export type MetabaseErrorCode =+ | "EXISTING_USER_SESSION_FAILED"+ | "SDK_VERSION_INCOMPATIBLE"+ | "INVALID_SESSION_OBJECT"+ | "INVALID_SESSION_SCHEMA"+ | "BACKEND_ERROR_STATUS"+ | "CUSTOM_FETCH_ERROR"+ | "DEFAULT_ENDPOINT_ERROR"+ | "CANNOT_FETCH_JWT_TOKEN"+ | "SAML_POPUP_BLOCKED"+ | "SAML_POPUP_CLOSED"+ | "SAML_TIMEOUT"+ | "USER_FETCH_FAILED"+ | "CANNOT_CONNECT_TO_INSTANCE"+ | "INVALID_AUTH_METHOD"+ | "AUTH_TIMEOUT"+ | "EMBED_TAG_ERROR";diff --git a/enterprise/frontend/src/embedding-sdk-bundle/errors/error-docs-links.ts b/enterprise/frontend/src/embedding-sdk-bundle/errors/error-docs-links.tsnew file mode 100644index 00000000000..9395d087b94--- /dev/null+++ b/enterprise/frontend/src/embedding-sdk-bundle/errors/error-docs-links.ts@@ -0,0 +1,14 @@+import type { MetabaseErrorCode } from "./error-code";++type ErrorDocLinks = Partial<Record<MetabaseErrorCode, string>>;++/**+ * Provide documentation links for each error codes.+ * Custom fields get removed when serializing errors, so+ * we need to store doc urls separately.+ **/+export const ERROR_DOC_LINKS: ErrorDocLinks = {+ EXISTING_USER_SESSION_FAILED:+ // eslint-disable-next-line no-unconditional-metabase-links-render -- error documentation link+ "https://www.metabase.com/docs/latest/embedding/embedded-analytics-js#use-existing-user-session-to-test-embeds",+};diff --git a/enterprise/frontend/src/embedding-sdk-bundle/errors/generic.ts b/enterprise/frontend/src/embedding-sdk-bundle/errors/generic.tsindex e3c1773a837..7c9c425d70b 100644--- a/enterprise/frontend/src/embedding-sdk-bundle/errors/generic.ts+++ b/enterprise/frontend/src/embedding-sdk-bundle/errors/generic.ts@@ -42,3 +42,11 @@ export function AUTH_TIMEOUT() {"Authentication has not been completed in time.",);}++export function EXISTING_USER_SESSION_FAILED() {+ return new MetabaseError(+ "EXISTING_USER_SESSION_FAILED",+ // eslint-disable-next-line no-literal-metabase-strings -- developer-facing error message explaining authentication failure+ "Failed to authenticate using an existing Metabase user session.",+ );+}diff --git a/enterprise/frontend/src/embedding-sdk-bundle/errors/index.ts b/enterprise/frontend/src/embedding-sdk-bundle/errors/index.tsindex e66dfc3f2bf..b8add82f3d3 100644--- a/enterprise/frontend/src/embedding-sdk-bundle/errors/index.ts+++ b/enterprise/frontend/src/embedding-sdk-bundle/errors/index.ts@@ -3,3 +3,4 @@ export * from "./jwt";export * from "./version";export * from "./saml";export * from "./generic";+export * from "./error-docs-links";diff --git a/enterprise/frontend/src/embedding-sdk-bundle/store/auth/auth.ts b/enterprise/frontend/src/embedding-sdk-bundle/store/auth/auth.tsindex ae8d9091a1b..50cdfb1b3a6 100644--- a/enterprise/frontend/src/embedding-sdk-bundle/store/auth/auth.ts+++ b/enterprise/frontend/src/embedding-sdk-bundle/store/auth/auth.ts@@ -80,6 +80,10 @@ export const initAuth = createAsyncThunk(]);if (!user.payload) {+ if (EMBEDDING_SDK_IFRAME_EMBEDDING_CONFIG.useExistingUserSession) {+ throw MetabaseError.EXISTING_USER_SESSION_FAILED();+ }+throw MetabaseError.USER_FETCH_FAILED();}if (!siteSettings.payload) {diff --git a/enterprise/frontend/src/embedding-sdk-bundle/types/ui.ts b/enterprise/frontend/src/embedding-sdk-bundle/types/ui.tsindex f82a6aeac5a..344dd0a1141 100644--- a/enterprise/frontend/src/embedding-sdk-bundle/types/ui.ts+++ b/enterprise/frontend/src/embedding-sdk-bundle/types/ui.ts@@ -12,6 +12,7 @@ export type { MetabaseFontFamily } from "metabase/embedding-sdk/theme/fonts";export type SdkErrorComponentProps = {type?: "relative" | "fixed";message: ReactNode;+ error?: Error;withCloseButton?: boolean;onClose?: () => void;};@@ -19,4 +20,5 @@ export type SdkErrorComponentProps = {export type SdkErrorComponent = ({type,message,+ error,}: SdkErrorComponentProps) => JSX.Element;diff --git a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/components/SdkIframeEmbedRoute.tsx b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/components/SdkIframeEmbedRoute.tsxindex a66589bce02..7644115667b 100644--- a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/components/SdkIframeEmbedRoute.tsx+++ b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/components/SdkIframeEmbedRoute.tsx@@ -1,6 +1,8 @@import type { ReactNode } from "react";import { P, match } from "ts-pattern";+import { PublicComponentStylesWrapper } from "embedding-sdk-bundle/components/private/PublicComponentStylesWrapper";+import { SdkError } from "embedding-sdk-bundle/components/private/PublicComponentWrapper";import { SdkBreadcrumbsProvider } from "embedding-sdk-bundle/components/private/SdkBreadcrumbs";import { ComponentProvider } from "embedding-sdk-bundle/components/public/ComponentProvider";import { SdkQuestion } from "embedding-sdk-bundle/components/public/SdkQuestion";@@ -9,7 +11,8 @@ import {InteractiveDashboard,StaticDashboard,} from "embedding-sdk-bundle/components/public/dashboard";-import { getSdkStore } from "embedding-sdk-bundle/store";+import { getSdkStore, useSdkSelector } from "embedding-sdk-bundle/store";+import { getLoginStatus } from "embedding-sdk-bundle/store/selectors";import type { MetabaseAuthConfig } from "embedding-sdk-package";import { EMBEDDING_SDK_IFRAME_EMBEDDING_CONFIG } from "metabase/embedding-sdk/config";import { createTracker } from "metabase/lib/analytics-untyped";@@ -92,6 +95,18 @@ const SdkIframeEmbedView = ({settings: SdkIframeEmbedSettings;}): ReactNode => {const rerenderKey = useParamRerenderKey(settings);+ const loginStatus = useSdkSelector(getLoginStatus);++ if (loginStatus?.status === "error") {+ return (+ <PublicComponentStylesWrapper>+ <SdkError+ error={loginStatus.error}+ message={loginStatus.error.message}+ />+ </PublicComponentStylesWrapper>+ );+ }return match(settings).with(diff --git a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/embed.ts b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/embed.tsindex 01c985cceeb..08462fd5f46 100644--- a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/embed.ts+++ b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/embed.ts@@ -93,7 +93,7 @@ if (typeof window !== "undefined") {}const raiseError = (message: string) => {- throw new MetabaseError("EMBED_ERROR", message);+ throw new MetabaseError("EMBED_TAG_ERROR", message);};function assertFieldCanBeUpdated(diff --git a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/types/embed.ts b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/types/embed.tsindex 3d2d02500a8..7452aa18726 100644--- a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/types/embed.ts+++ b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/types/embed.ts@@ -1,4 +1,5 @@import type { MetabaseError } from "embedding-sdk-bundle/errors";+import type { MetabaseErrorCode } from "embedding-sdk-bundle/errors/error-code";import type { MetabaseAuthMethod } from "embedding-sdk-bundle/types";import type { MetabaseEmbeddingSessionToken } from "embedding-sdk-bundle/types/refresh-token";import type {@@ -33,7 +34,7 @@ export type SdkIframeEmbedMessage =| {type: "metabase.embed.reportAuthenticationError";data: {- error: MetabaseError<string, unknown>;+ error: MetabaseError<MetabaseErrorCode, unknown>;};}| {