Skip to content

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

GRO-536 replace ad hoc metaplow functions with @metabase/track alpha (#76618)

Brad Anderson69c375625379
diff --git a/bun.lock b/bun.lock
index 36be39f108d..8176028e0ef 100644
--- a/bun.lock
+++ b/bun.lock
@@ -38,6 +38,7 @@
"@mantine/core": "8.3.18",
"@mantine/dates": "8.3.18",
"@mantine/hooks": "8.3.18",
+ "@metabase/track": "^1.0.0-alpha.1",
"@modelcontextprotocol/ext-apps": "^1.3.2",
"@popperjs/core": "^2.11.8",
"@react-oauth/google": "^0.11.1",
@@ -1199,6 +1200,8 @@
"@mdx-js/react": ["@mdx-js/[email protected]", "", { "dependencies": { "@types/mdx": "^2.0.0" } }, "sha512-QjHtSaoameoalGnKDT3FoIl4+9RwyTmo9ZJGBdLOks/YOiWHoRDI3PUwEzOE7kEmGcV3AFcp9K6dYu9rEuKLAQ=="],
+ "@metabase/track": ["@metabase/[email protected]", "", { "peerDependencies": { "typescript": "^5" } }, "sha512-LPpoNCyBoqUX1TNAdHQMswJETC6bPs7YNpKQp17n5+mCpeDcbP40o+V1DulVsOSWIbwg/RWX770d1s4ec7kPlw=="],
+
"@microsoft/api-extractor": ["@microsoft/[email protected]", "", { "dependencies": { "@microsoft/api-extractor-model": "7.33.8", "@microsoft/tsdoc": "~0.16.0", "@microsoft/tsdoc-config": "~0.18.1", "@rushstack/node-core-library": "5.23.1", "@rushstack/rig-package": "0.7.3", "@rushstack/terminal": "0.24.0", "@rushstack/ts-command-line": "5.3.9", "diff": "~8.0.2", "minimatch": "10.2.3", "resolve": "~1.22.1", "semver": "~7.7.4", "source-map": "~0.6.1", "typescript": "5.9.3" }, "bin": { "api-extractor": "bin/api-extractor" } }, "sha512-yK6OycD46gIzLRpj6ueVUWPk1ACSpkN1LBo05gY1qPTylbWyUCanXfH7+VgkI5LJrJoRSQR5F04XuCffCXLOBw=="],
"@microsoft/api-extractor-model": ["@microsoft/[email protected]", "", { "dependencies": { "@microsoft/tsdoc": "~0.16.0", "@microsoft/tsdoc-config": "~0.18.1", "@rushstack/node-core-library": "5.23.1" } }, "sha512-aIcoQggPyer3B6Ze3usz0YWC/oBwUHfRH5ETUsr+oT2BRA6SfTJl7IKPcPZkX4UR+PohowzW4uMxsvjrn8vm+w=="],
diff --git a/frontend/src/embedding-sdk-bundle/analytics/tracker.ts b/frontend/src/embedding-sdk-bundle/analytics/tracker.ts
index ad74291ce78..87d20559e64 100644
--- a/frontend/src/embedding-sdk-bundle/analytics/tracker.ts
+++ b/frontend/src/embedding-sdk-bundle/analytics/tracker.ts
@@ -13,6 +13,7 @@ import type { SdkStore } from "embedding-sdk-bundle/store/types";
import type { MetabaseAuthConfig } from "embedding-sdk-bundle/types/auth-config";
import { getSdkPackageVersion } from "embedding-sdk-shared/lib/get-build-info";
import { isEmbeddingEajs } from "metabase/embedding-sdk/config";
+import { initMetaplow } from "metabase/utils/metaplow";
export function deriveAuthMethod(
authConfig: MetabaseAuthConfig,
@@ -40,6 +41,12 @@ export function useInitSdkTracker(
if (isEmbeddingEajs() || !isTrackingEnabled) {
return;
}
+ initMetaplow({
+ // Via frontend/src/embedding-sdk-bundle/analytics/snowplow.ts
+ // Omits userId — unlike the main-app tracker, SDK component usage is tracked at instance granularity;
+ // the analytics-uuid already identifies the account.
+ getUserId: () => undefined,
+ });
const authMethod = deriveAuthMethod(authConfig);
const wasJustInitialized = initSdkTracker({
diff --git a/frontend/src/metabase/app.js b/frontend/src/metabase/app.js
index 3ac3239d291..e3a1003a2f3 100644
--- a/frontend/src/metabase/app.js
+++ b/frontend/src/metabase/app.js
@@ -72,10 +72,7 @@ function _init(reducers, getRoutes, callback) {
createSnowplowTracker(() => getUserId(store.getState()));
initMetaplow({
- beforeSend: (_type, payload) => ({
- ...payload,
- data: { ...payload.data, user_id: getUserId(store.getState()) },
- }),
+ getUserId: () => getUserId(store.getState()),
});
// Initialize distributed tracing if enabled via MB_TRACING_ENABLED.
diff --git a/frontend/src/metabase/utils/metaplow.ts b/frontend/src/metabase/utils/metaplow.ts
index e1ace3d2c50..17fb64dc8c8 100644
--- a/frontend/src/metabase/utils/metaplow.ts
+++ b/frontend/src/metabase/utils/metaplow.ts
@@ -1,23 +1,12 @@
+import { init, track } from "@metabase/track";
+import { isObject } from "underscore";
+
import Settings from "metabase/utils/settings";
const METAPLOW_WEBSITE_ID = "23eefa30-4c4f-490e-aa4f-084cd23b1561";
const anonymizedHostname = "anonymous.metabase.com";
const anonymizedOrigin = `http://${anonymizedHostname}`;
-type MetaplowPayload = {
- website: string;
- url: string;
- id: string;
- referrer: string;
- title: string;
- hostname: string;
- screen: string;
- language: string;
- tag: string;
- name: string;
- data?: Record<string, unknown>;
-};
-
const getSanitizedUrl = (url: string) => {
const parsed = new URL(url, window.location.origin);
const pathWithoutSlug = parsed.pathname.replace(
@@ -27,72 +16,60 @@ const getSanitizedUrl = (url: string) => {
return anonymizedOrigin + pathWithoutSlug;
};
-function getBasePayload(url: string): Omit<MetaplowPayload, "name" | "data"> {
- return {
- website: METAPLOW_WEBSITE_ID,
- url: getSanitizedUrl(url),
- id: Settings.get("analytics-uuid") ?? "",
- referrer: "",
- title: "",
- hostname: anonymizedHostname,
- screen: `${window.screen.width}x${window.screen.height}`,
- language: navigator.language,
- tag: "metabase-instance",
- };
+interface MetaplowConfig {
+ getUserId: () => number | undefined;
}
-async function send(payload: MetaplowPayload): Promise<unknown> {
+export function initMetaplow(config: MetaplowConfig): void {
const metaplowUrl = Settings.get("metaplow-url");
if (!metaplowUrl) {
return;
}
+ const hostUrl = metaplowUrl.replace(/\/send$/, "");
- const headers: Record<string, string> = {
- "Content-Type": "application/json",
- };
-
- return fetch(metaplowUrl, {
- method: "POST",
- headers,
- body: JSON.stringify({ type: "event", payload }),
- });
-}
-
-interface MetaplowConfig {
- beforeSend: (
- type: string,
- payload: MetaplowPayload,
- ) => MetaplowPayload | void;
-}
+ init({
+ website: METAPLOW_WEBSITE_ID,
+ hostUrl,
+ tag: "metabase-instance",
+ beforeSend: (type, originalPayload) => {
+ let payload = originalPayload as Record<string, unknown>;
-let _config: MetaplowConfig = {
- beforeSend: (_type, payload) => payload,
-};
+ // Replace default pageview behavior with our own custom pageview tracking
+ const isAutoPageView = type === "event" && !payload.name;
+ if (isAutoPageView) {
+ return;
+ }
+ if (payload.name === "pageview" && isObject(payload.data)) {
+ payload = { ...payload, url: payload.data.url };
+ delete (payload.data as Record<string, unknown>).url;
+ }
-export function initMetaplow(config: Partial<MetaplowConfig>): void {
- _config = { ..._config, ...config };
+ return {
+ ...payload,
+ url:
+ "url" in payload && typeof payload.url === "string"
+ ? getSanitizedUrl(payload.url)
+ : "",
+ id: Settings.get("analytics-uuid") ?? "",
+ referrer: "",
+ title: "",
+ hostname: anonymizedHostname,
+ data: {
+ ...(payload.data as Record<string, unknown> | undefined),
+ user_id: config.getUserId(),
+ },
+ };
+ },
+ });
}
export function trackMetaplowEvent(
- name: MetaplowPayload["name"],
- data: MetaplowPayload["data"] = {},
-): void {
- const payload = _config.beforeSend("event", {
- ...getBasePayload(window.location.href),
- name,
- data,
- });
- if (payload) {
- send(payload).catch(() => undefined);
- }
+ name: string,
+ data: Record<string, unknown> = {},
+) {
+ return track(name, data);
}
export function trackMetaplowPageView(url: string) {
- const payload = _config.beforeSend("event", {
- ...getBasePayload(url),
- name: "pageview",
- });
- if (payload) {
- send(payload).catch(() => undefined);
- }
+ return track("pageview", { url });
}
diff --git a/frontend/src/metabase/utils/metaplow.unit.spec.ts b/frontend/src/metabase/utils/metaplow.unit.spec.ts
index e6fa0ac8e4b..3be83923e86 100644
--- a/frontend/src/metabase/utils/metaplow.unit.spec.ts
+++ b/frontend/src/metabase/utils/metaplow.unit.spec.ts
@@ -1,3 +1,5 @@
+import { reset } from "@metabase/track";
+
import Settings from "metabase/utils/settings";
import {
@@ -10,6 +12,11 @@ const METAPLOW_URL = "https://metaplow.example.com/api/send";
const METAPLOW_WEBSITE_ID = "23eefa30-4c4f-490e-aa4f-084cd23b1561";
const ANON_ORIGIN = "http://anonymous.metabase.com";
+const setup = async ({ userId }: { userId?: number } = {}) => {
+ initMetaplow({ getUserId: () => userId });
+ await Promise.resolve();
+};
+
describe("metaplow", () => {
let fetchSpy: jest.SpyInstance;
@@ -23,6 +30,7 @@ describe("metaplow", () => {
afterEach(() => {
fetchSpy.mockRestore();
Settings.set("metaplow-url", null);
+ reset();
});
const getSentPayload = () => {
@@ -37,44 +45,29 @@ describe("metaplow", () => {
};
describe("initMetaplow", () => {
- describe("beforeSend", () => {
- afterEach(() => {
- initMetaplow({ beforeSend: (_type, payload) => payload });
- });
+ describe("getUserId", () => {
+ it("injects the user_id into the event data", async () => {
+ initMetaplow({ getUserId: () => 123 });
- it("can modify the payload before it's sent", () => {
- initMetaplow({
- beforeSend: (_type, payload) => ({
- ...payload,
- data: { ...payload.data, user_id: 123 },
- }),
- });
-
- trackMetaplowEvent("button_clicked");
+ await trackMetaplowEvent("button_clicked");
const { payload } = getSentPayload();
expect(payload.data.user_id).toBe(123);
});
-
- it("suppresses the fetch call when a falsy value is returned", () => {
- initMetaplow({ beforeSend: () => undefined });
-
- trackMetaplowEvent("button_clicked");
-
- expect(fetchSpy).not.toHaveBeenCalled();
- });
});
});
describe("trackMetaplowEvent", () => {
- it("does not call fetch when metaplow-url is not set", () => {
+ it("does not call fetch when metaplow-url is not set", async () => {
Settings.set("metaplow-url", null);
- trackMetaplowEvent("button_clicked");
+ await setup();
+ await trackMetaplowEvent("button_clicked");
expect(fetchSpy).not.toHaveBeenCalled();
});
- it("sends an event with the given name and default empty data", () => {
- trackMetaplowEvent("button_clicked");
+ it("sends an event with the given name and default empty data", async () => {
+ await setup();
+ await trackMetaplowEvent("button_clicked");
const body = getSentPayload();
expect(body.type).toBe("event");
@@ -91,15 +84,17 @@ describe("metaplow", () => {
);
});
- it("forwards the data payload", () => {
- trackMetaplowEvent("button_clicked", { foo: "bar", count: 3 });
+ it("forwards the data payload", async () => {
+ await setup();
+ await trackMetaplowEvent("button_clicked", { foo: "bar", count: 3 });
const { payload } = getSentPayload();
expect(payload.data).toEqual({ foo: "bar", count: 3 });
});
- it("includes screen and language from the browser", () => {
- trackMetaplowEvent("button_clicked");
+ it("includes screen and language from the browser", async () => {
+ await setup();
+ await trackMetaplowEvent("button_clicked");
const { payload } = getSentPayload();
expect(payload.screen).toBe(
@@ -108,8 +103,9 @@ describe("metaplow", () => {
expect(payload.language).toBe(navigator.language);
});
- it("uses an anonymized hostname in the url", () => {
- trackMetaplowEvent("button_clicked");
+ it("uses an anonymized hostname in the url", async () => {
+ await setup();
+ await trackMetaplowEvent("button_clicked");
const { payload } = getSentPayload();
expect(payload.url.startsWith(ANON_ORIGIN)).toBe(true);
@@ -119,11 +115,13 @@ describe("metaplow", () => {
describe("trackMetaplowPageView", () => {
it("does not call fetch when metaplow-url is not set", async () => {
Settings.set("metaplow-url", null);
+ await setup();
await trackMetaplowPageView("/question/42-my-question");
expect(fetchSpy).not.toHaveBeenCalled();
});
it('sends an event with name "pageview"', async () => {
+ await setup();
await trackMetaplowPageView("/dashboard/1");
const { payload } = getSentPayload();
@@ -132,6 +130,7 @@ describe("metaplow", () => {
});
it("strips slugs from /:id-slug paths", async () => {
+ await setup();
await trackMetaplowPageView("/question/42-my-favorite-question");
const { payload } = getSentPayload();
@@ -139,6 +138,7 @@ describe("metaplow", () => {
});
it("anonymizes absolute URLs by replacing the origin", async () => {
+ await setup();
await trackMetaplowPageView(
"https://my-company.metabaseapp.com/collection/5-secrets",
);
@@ -148,6 +148,7 @@ describe("metaplow", () => {
});
it("preserves paths without a numeric slug prefix", async () => {
+ await setup();
await trackMetaplowPageView("/admin/settings/general");
const { payload } = getSentPayload();
diff --git a/jest.esm-packages.js b/jest.esm-packages.js
index 8c5b9a63eeb..54f2ac7cac9 100644
--- a/jest.esm-packages.js
+++ b/jest.esm-packages.js
@@ -5,6 +5,7 @@
* This list is used by both jest.config.js and jest.tz.unit.conf.js
*/
const esmPackages = [
+ "@metabase\\+track",
"bail",
"ccount",
"character-entities.*",
diff --git a/package.json b/package.json
index 77dfd997455..5572d542ad8 100644
--- a/package.json
+++ b/package.json
@@ -47,6 +47,7 @@
"@mantine/core": "8.3.18",
"@mantine/dates": "8.3.18",
"@mantine/hooks": "8.3.18",
+ "@metabase/track": "^1.0.0-alpha.1",
"@modelcontextprotocol/ext-apps": "^1.3.2",
"@popperjs/core": "^2.11.8",
"@react-oauth/google": "^0.11.1",