Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

utm query params for docs search (#76674)

Benoit Vinay84b27f02a5f6
diff --git a/e2e/test/scenarios/onboarding/command-palette.cy.spec.js b/e2e/test/scenarios/onboarding/command-palette.cy.spec.js
index 17a2817421c..e7e5ce3d78c 100644
--- a/e2e/test/scenarios/onboarding/command-palette.cy.spec.js
+++ b/e2e/test/scenarios/onboarding/command-palette.cy.spec.js
@@ -108,7 +108,9 @@ describe("command palette", () => {
.should("contain.text", "Our analytics")
.should("contain.text", "The best question");
- cy.findByText('Search documentation for "Orders, Count"').should("exist");
+ cy.findByText('Search Metabase\'s docs for "Orders, Count"').should(
+ "exist",
+ );
// Since the command palette list is virtualized, we will search for a few
// to ensure they're reachable
@@ -174,7 +176,7 @@ describe("command palette", () => {
H.pressPageDown();
H.commandPalette()
- .findByRole("option", { name: 'Search documentation for "New"' })
+ .findByRole("option", { name: 'Search Metabase\'s docs for "New"' })
.should("have.attr", "aria-selected", "true");
H.pressPageUp();
@@ -189,7 +191,7 @@ describe("command palette", () => {
H.pressEnd();
H.commandPalette()
- .findByRole("option", { name: 'Search documentation for "New"' })
+ .findByRole("option", { name: 'Search Metabase\'s docs for "New"' })
.should("have.attr", "aria-selected", "true");
H.pressHome();
diff --git a/frontend/src/metabase/palette/components/PaletteResultItem.unit.spec.tsx b/frontend/src/metabase/palette/components/PaletteResultItem.unit.spec.tsx
index baf7f67b630..aab5edee37d 100644
--- a/frontend/src/metabase/palette/components/PaletteResultItem.unit.spec.tsx
+++ b/frontend/src/metabase/palette/components/PaletteResultItem.unit.spec.tsx
@@ -83,10 +83,10 @@ describe("Mouse/keyboard interactions", () => {
pathname: "/",
};
- describe("The 'Search documentation for...' command palette item", () => {
+ describe("The 'Search Metabase's docs for...' command palette item", () => {
const searchDocs: Partial<PaletteActionImpl> = {
id: "search_docs",
- name: 'Search documentation for "hedgehogs"',
+ name: 'Search Metabase\'s docs for "hedgehogs"',
section: "docs",
keywords: "hedgehogs",
icon: "document",
diff --git a/frontend/src/metabase/palette/components/test/PaletteResults/PaletteResults-oss.unit.spec.tsx b/frontend/src/metabase/palette/components/test/PaletteResults/PaletteResults-oss.unit.spec.tsx
index 0e1bedc5d36..3da973a30e3 100644
--- a/frontend/src/metabase/palette/components/test/PaletteResults/PaletteResults-oss.unit.spec.tsx
+++ b/frontend/src/metabase/palette/components/test/PaletteResults/PaletteResults-oss.unit.spec.tsx
@@ -115,7 +115,7 @@ describe("PaletteResults", () => {
await screen.findByRole("option", { name: "Bar Dashboard" }),
).toHaveTextContent("Such Bar. Much Wow.");
expect(
- await screen.findByText('Search documentation for "Bar"'),
+ await screen.findByText('Search Metabase\'s docs for "Bar"'),
).toBeInTheDocument();
});
@@ -151,7 +151,7 @@ describe("PaletteResults", () => {
it("should not provide links to settings pages for non-admins", async () => {
setup({ query: "setu", isAdmin: false });
expect(
- await screen.findByText(`Search documentation for "setu"`),
+ await screen.findByText(`Search Metabase's docs for "setu"`),
).toBeInTheDocument();
expect(screen.queryByText("Admin")).not.toBeInTheDocument();
expect(screen.queryByText("Settings - Setup")).not.toBeInTheDocument();
@@ -166,7 +166,7 @@ describe("PaletteResults", () => {
it("should not provide links to admin pages for non-admins", async () => {
setup({ query: "permi", isAdmin: false });
expect(
- await screen.findByText(`Search documentation for "permi"`),
+ await screen.findByText(`Search Metabase's docs for "permi"`),
).toBeInTheDocument();
expect(screen.queryByText("Admin")).not.toBeInTheDocument();
expect(screen.queryByText("Permissions")).not.toBeInTheDocument();
@@ -184,9 +184,21 @@ describe("PaletteResults", () => {
it("should provide a link to docs with the proper url param", async () => {
setup({ query: "model" });
- expect(
- await screen.findByRole("link", { name: /Search documentation/ }),
- ).toHaveAttribute("href", expect.stringContaining("?query=model"));
+ const docsLink = await screen.findByRole("link", {
+ name: /Search Metabase's docs/,
+ });
+ expect(docsLink).toHaveAttribute(
+ "href",
+ expect.stringContaining("query=model"),
+ );
+ expect(docsLink).toHaveAttribute(
+ "href",
+ expect.stringContaining("utm_medium=command-palette"),
+ );
+ expect(docsLink).toHaveAttribute(
+ "href",
+ expect.stringContaining("utm_campaign=docs-search"),
+ );
// One call is always made to determine if the instance has models inside useCommandPaletteBasicActions
expect(fetchMock.callHistory.calls("path:/api/search").length).toBe(2);
@@ -199,7 +211,7 @@ describe("PaletteResults", () => {
"true",
);
expect(
- await screen.findByLabelText(/Search documentation/),
+ await screen.findByLabelText(/Search Metabase's docs/),
).toHaveAttribute("aria-disabled", "false");
});
});
diff --git a/frontend/src/metabase/palette/constants.ts b/frontend/src/metabase/palette/constants.ts
index 2dd09dbc0c2..132cf3e9869 100644
--- a/frontend/src/metabase/palette/constants.ts
+++ b/frontend/src/metabase/palette/constants.ts
@@ -22,6 +22,21 @@ export const GROUP_LABELS = {
export const ELLIPSIS = "...";
+export const METABASE_DOCS_LABELS = {
+ get section() {
+ // eslint-disable-next-line metabase/no-literal-metabase-strings -- Only shown when showMetabaseLinks is true; links to metabase.com docs.
+ return t`Metabase documentation`;
+ },
+ searchLabel(searchTerm: string) {
+ // eslint-disable-next-line metabase/no-literal-metabase-strings -- Only shown when showMetabaseLinks is true; links to metabase.com docs.
+ return t`Search Metabase's docs for "${searchTerm}"`;
+ },
+ get viewLabel() {
+ // eslint-disable-next-line metabase/no-literal-metabase-strings -- Only shown when showMetabaseLinks is true; links to metabase.com docs.
+ return t`View Metabase documentation`;
+ },
+};
+
type AdminSettingsSections = Record<
string,
{
diff --git a/frontend/src/metabase/palette/hooks/useCommandPalette.tsx b/frontend/src/metabase/palette/hooks/useCommandPalette.tsx
index f05191f1e3e..905422e9304 100644
--- a/frontend/src/metabase/palette/hooks/useCommandPalette.tsx
+++ b/frontend/src/metabase/palette/hooks/useCommandPalette.tsx
@@ -12,11 +12,7 @@ import { useSetting } from "metabase/common/hooks";
import { trackSearchClick } from "metabase/common/search/analytics";
import { useGetIcon } from "metabase/hooks/use-icon";
import { useSelector } from "metabase/redux";
-import {
- getDocsSearchUrl,
- getDocsUrl,
- getSettings,
-} from "metabase/selectors/settings";
+import { getDocsUrl, getSettings } from "metabase/selectors/settings";
import { canAccessSettings, getUserIsAdmin } from "metabase/selectors/user";
import { getShowMetabaseLinks } from "metabase/selectors/whitelabel";
import { Icon, Text } from "metabase/ui";
@@ -30,7 +26,7 @@ import {
isRecentTableItem,
} from "metabase-types/api";
-import { getAdminSettingsSections } from "../constants";
+import { METABASE_DOCS_LABELS, getAdminSettingsSections } from "../constants";
import type { PaletteAction } from "../types";
import { filterRecentItems } from "../utils";
@@ -42,7 +38,6 @@ export const useCommandPalette = ({
locationQuery: Query;
}) => {
const getIcon = useGetIcon();
- const docsUrl = useSelector((state) => getDocsUrl(state, {}));
const showMetabaseLinks = useSelector(getShowMetabaseLinks);
const { isVisible } = useKBar((s) => ({
isVisible: s.visualState !== VisualState.hidden,
@@ -72,6 +67,19 @@ export const useCommandPalette = ({
const hasQuery = searchQuery.length > 0;
+ const docsUrl = useSelector((state) => getDocsUrl(state, {}));
+ const docsSearchUrl = useSelector((state) =>
+ debouncedSearchText
+ ? getDocsUrl(state, {
+ searchQuery: debouncedSearchText,
+ utm: {
+ utm_medium: "command-palette",
+ utm_campaign: "docs-search",
+ },
+ })
+ : null,
+ );
+
const {
currentData: searchResults,
isFetching: isSearchLoading,
@@ -103,15 +111,13 @@ export const useCommandPalette = ({
const settingValues = useSelector(getSettings);
const docsAction = useMemo<PaletteAction[]>(() => {
- const link = debouncedSearchText
- ? getDocsSearchUrl({ query: debouncedSearchText })
- : docsUrl;
+ const link = debouncedSearchText ? docsSearchUrl : docsUrl;
const ret: PaletteAction[] = [
{
id: "search_docs",
name: debouncedSearchText
- ? t`Search documentation for "${debouncedSearchText}"`
- : t`View documentation`,
+ ? METABASE_DOCS_LABELS.searchLabel(debouncedSearchText)
+ : METABASE_DOCS_LABELS.viewLabel,
section: "docs",
// Include search query in keywords so kbar always shows it
keywords: trimmedQuery,
@@ -122,7 +128,7 @@ export const useCommandPalette = ({
},
];
return ret;
- }, [debouncedSearchText, docsUrl, trimmedQuery]);
+ }, [debouncedSearchText, docsSearchUrl, docsUrl, trimmedQuery]);
const showDocsAction = showMetabaseLinks && hasQuery && !disabled;
diff --git a/frontend/src/metabase/palette/utils.ts b/frontend/src/metabase/palette/utils.ts
index df29c0a264a..71c0ee3e8ed 100644
--- a/frontend/src/metabase/palette/utils.ts
+++ b/frontend/src/metabase/palette/utils.ts
@@ -5,6 +5,7 @@ import _ from "underscore";
import type { ColorName } from "metabase/ui/colors/types";
import type { IconName, RecentItem } from "metabase-types/api";
+import { METABASE_DOCS_LABELS } from "./constants";
import type { PaletteActionImpl } from "./types";
export const processResults = (
@@ -20,7 +21,10 @@ export const processResults = (
const search = processSection(t`Results`, groupedResults["search"]);
const recent = processSection(t`Recents`, groupedResults["recent"]);
const admin = processSection(t`Admin`, groupedResults["admin"]);
- const docs = processSection(t`Documentation`, groupedResults["docs"]);
+ const docs = processSection(
+ METABASE_DOCS_LABELS.section,
+ groupedResults["docs"],
+ );
if (!hasSearchTerm) {
return [...recent];
diff --git a/frontend/src/metabase/selectors/selectors.unit.spec.ts b/frontend/src/metabase/selectors/selectors.unit.spec.ts
index dc0b1637e56..0fb0153580f 100644
--- a/frontend/src/metabase/selectors/selectors.unit.spec.ts
+++ b/frontend/src/metabase/selectors/selectors.unit.spec.ts
@@ -136,6 +136,30 @@ describe("getDocsUrl", () => {
"https://www.metabase.com/docs/v0.41/foo/bar.html#baz",
);
});
+
+ it("handles docs site search with utm params", () => {
+ const state = createMockState({
+ settings: createMockSettingsState({
+ "token-features": createMockTokenFeatures({ hosting: false }),
+ }),
+ });
+
+ const url = new URL(
+ getDocsUrl(state, {
+ searchQuery: "kitten meow",
+ utm: {
+ utm_medium: "command-palette",
+ utm_campaign: "docs-search",
+ },
+ }),
+ );
+ expect(url.pathname).toBe("/search");
+ expect(url.searchParams.get("query")).toBe("kitten meow");
+ expect(url.searchParams.get("utm_source")).toBe("product");
+ expect(url.searchParams.get("utm_medium")).toBe("command-palette");
+ expect(url.searchParams.get("utm_campaign")).toBe("docs-search");
+ expect(url.searchParams.get("source_plan")).toBe("oss");
+ });
});
describe("getStoreUrlFromState", () => {
diff --git a/frontend/src/metabase/selectors/settings.ts b/frontend/src/metabase/selectors/settings.ts
index a78985cc66b..353fd37de74 100644
--- a/frontend/src/metabase/selectors/settings.ts
+++ b/frontend/src/metabase/selectors/settings.ts
@@ -120,12 +120,20 @@ export const getUrlWithUtm = createSelector(
interface DocsUrlProps {
page?: string;
anchor?: string;
+ searchQuery?: string;
utm?: UtmProps;
}
export const getDocsUrl = (state: State, props: DocsUrlProps) => {
- const version = getSetting(state, "version");
- const url = getDocsUrlForVersion(version, props.page, props.anchor);
+ const url = props.searchQuery
+ ? `https://www.metabase.com/search?${new URLSearchParams({
+ query: props.searchQuery,
+ })}`
+ : getDocsUrlForVersion(
+ getSetting(state, "version"),
+ props.page,
+ props.anchor,
+ );
if (!props.utm) {
return url;
@@ -134,9 +142,6 @@ export const getDocsUrl = (state: State, props: DocsUrlProps) => {
return getUrlWithUtm(state, { url, ...props.utm });
};
-export const getDocsSearchUrl = (query: Record<string, string>) =>
- `https://www.metabase.com/search?${new URLSearchParams(query)}`;
-
export const getDocsUrlForVersion = (
version: Version | undefined,
page = "",