Analytics configuration is the responsibility of the host application when running in widget mode (#3089)

* Support for analytics configuration via URL parameters in widget mode

Adds:

- posthogApiHost
- posthogApiKey
- rageshakeSubmitUrl
- sentryDsn
- sentryEnvironment

Deprecate analyticsId and use posthogUserId instead

* Partial test coverage

* Simplify tests

* More tests

* Lint

* Split embedded only parameters into own section for clarity

* Update docs/url-params.md

* Update docs/url-params.md

* Update vite.config.js

Author: hughns

docs/url-params.md

@@ -105,7 +105,15 @@ export interface UrlParams {
   /**
    * The Posthog analytics ID. It is only available if the user has given consent for sharing telemetry in element web.
    */
-  analyticsID: string | null;
+  posthogUserId: string | null;
+  /**
+   * The Posthog API host. This is only used in the embedded package of Element Call.
+   */
+  posthogApiHost: string | null;
+  /**
+   * The Posthog API key. This is only used in the embedded package of Element Call.
+   */
+  posthogApiKey: string | null;
   /**
    * Whether the app is allowed to use fallback STUN servers for ICE in case the
    * user's homeserver doesn't provide any.
@@ -155,6 +163,20 @@ export interface UrlParams {
    * If it was a Join Call button, it would be `join_existing`.
    */
   intent: string | null;
+
+  /**
+   * The rageshake submit URL. This is only used in the embedded package of Element Call.
+   */
+  rageshakeSubmitUrl: string | null;
+
+  /**
+   * The Sentry DSN. This is only used in the embedded package of Element Call.
+   */
+  sentryDsn: string | null;
+  /**
+   * The Sentry environment. This is only used in the embedded package of Element Call.
+   */
+  sentryEnvironment: string | null;
 }
 
 // This is here as a stopgap, but what would be far nicer is a function that
@@ -257,7 +279,6 @@ export const getUrlParams = (
     lang: parser.getParam("lang"),
     fonts: parser.getAllParams("font"),
     fontScale: Number.isNaN(fontScale) ? null : fontScale,
-    analyticsID: parser.getParam("analyticsID"),
     allowIceFallback: parser.getFlagParam("allowIceFallback"),
     perParticipantE2EE: parser.getFlagParam("perParticipantE2EE"),
     skipLobby: parser.getFlagParam(
@@ -271,6 +292,13 @@ export const getUrlParams = (
     viaServers: !isWidget ? parser.getParam("viaServers") : null,
     homeserver: !isWidget ? parser.getParam("homeserver") : null,
     intent,
+    posthogApiHost: parser.getParam("posthogApiHost"),
+    posthogApiKey: parser.getParam("posthogApiKey"),
+    posthogUserId:
+      parser.getParam("posthogUserId") ?? parser.getParam("analyticsID"),
+    rageshakeSubmitUrl: parser.getParam("rageshakeSubmitUrl"),
+    sentryDsn: parser.getParam("sentryDsn"),
+    sentryEnvironment: parser.getParam("sentryEnvironment"),
   };
 };
 

src/UrlParams.ts

@@ -0,0 +1,91 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import {
+  expect,
+  describe,
+  it,
+  vi,
+  beforeEach,
+  beforeAll,
+  afterAll,
+} from "vitest";
+
+import { PosthogAnalytics } from "./PosthogAnalytics";
+import { mockConfig } from "../utils/test";
+
+describe("PosthogAnalytics", () => {
+  describe("embedded package", () => {
+    beforeAll(() => {
+      vi.stubEnv("VITE_PACKAGE", "embedded");
+    });
+
+    beforeEach(() => {
+      mockConfig({});
+      window.location.hash = "#";
+      PosthogAnalytics.resetInstance();
+    });
+
+    afterAll(() => {
+      vi.unstubAllEnvs();
+    });
+
+    it("does not create instance without config value or URL params", () => {
+      expect(PosthogAnalytics.instance.isEnabled()).toBe(false);
+    });
+
+    it("ignores config value and does not create instance", () => {
+      mockConfig({
+        posthog: {
+          api_host: "https://api.example.com.localhost",
+          api_key: "api_key",
+        },
+      });
+      expect(PosthogAnalytics.instance.isEnabled()).toBe(false);
+    });
+
+    it("uses URL params if both set", () => {
+      window.location.hash = `#?posthogApiHost=${encodeURIComponent("https://url.example.com.localhost")}&posthogApiKey=api_key`;
+      expect(PosthogAnalytics.instance.isEnabled()).toBe(true);
+    });
+  });
+
+  describe("full package", () => {
+    beforeAll(() => {
+      vi.stubEnv("VITE_PACKAGE", "full");
+    });
+
+    beforeEach(() => {
+      mockConfig({});
+      window.location.hash = "#";
+      PosthogAnalytics.resetInstance();
+    });
+
+    afterAll(() => {
+      vi.unstubAllEnvs();
+    });
+
+    it("does not create instance without config value", () => {
+      expect(PosthogAnalytics.instance.isEnabled()).toBe(false);
+    });
+
+    it("ignores URL params and does not create instance", () => {
+      window.location.hash = `#?posthogApiHost=${encodeURIComponent("https://url.example.com.localhost")}&posthogApiKey=api_key`;
+      expect(PosthogAnalytics.instance.isEnabled()).toBe(false);
+    });
+
+    it("creates instance with config value", () => {
+      mockConfig({
+        posthog: {
+          api_host: "https://api.example.com.localhost",
+          api_key: "api_key",
+        },
+      });
+      expect(PosthogAnalytics.instance.isEnabled()).toBe(true);
+    });
+  });
+});

src/analytics/PosthogAnalytics.test.ts

@@ -71,11 +71,6 @@ interface PlatformProperties {
   cryptoVersion?: string;
 }
 
-interface PosthogSettings {
-  project_api_key?: string;
-  api_host?: string;
-}
-
 export class PosthogAnalytics {
   /* Wrapper for Posthog analytics.
    * 3 modes of anonymity are supported, governed by this.anonymity
@@ -113,24 +108,27 @@ export class PosthogAnalytics {
     return this.internalInstance;
   }
 
-  private constructor(private readonly posthog: PostHog) {
-    const posthogConfig: PosthogSettings = {
-      project_api_key: Config.get().posthog?.api_key,
-      api_host: Config.get().posthog?.api_host,
-    };
+  public static resetInstance(): void {
+    // Reset the singleton instance
+    this.internalInstance = null;
+  }
 
-    if (posthogConfig.project_api_key && posthogConfig.api_host) {
-      if (
-        PosthogAnalytics.getPlatformProperties().matrixBackend === "embedded"
-      ) {
-        const { analyticsID } = getUrlParams();
-        // if the embedding platform (element web) already got approval to communicating with posthog
-        // element call can also send events to posthog
-        optInAnalytics.setValue(Boolean(analyticsID));
-      }
+  private constructor(private readonly posthog: PostHog) {
+    let apiKey: string | undefined;
+    let apiHost: string | undefined;
+    if (import.meta.env.VITE_PACKAGE === "embedded") {
+      // for the embedded package we always use the values from the URL as the widget host is responsible for analytics configuration
+      apiKey = getUrlParams().posthogApiKey ?? undefined;
+      apiHost = getUrlParams().posthogApiHost ?? undefined;
+    } else if (import.meta.env.VITE_PACKAGE === "full") {
+      // in full package it is the server responsible for the analytics
+      apiKey = Config.get().posthog?.api_key;
+      apiHost = Config.get().posthog?.api_host;
+    }
 
-      this.posthog.init(posthogConfig.project_api_key, {
-        api_host: posthogConfig.api_host,
+    if (apiKey && apiHost) {
+      this.posthog.init(apiKey, {
+        api_host: apiHost,
         autocapture: false,
         mask_all_text: true,
         mask_all_element_attributes: true,
@@ -274,7 +272,7 @@ export class PosthogAnalytics {
     const client: MatrixClient = window.matrixclient;
     let accountAnalyticsId: string | null;
     if (widget) {
-      accountAnalyticsId = getUrlParams().analyticsID;
+      accountAnalyticsId = getUrlParams().posthogUserId;
     } else {
       const accountData = await client.getAccountDataFromServer(
         PosthogAnalytics.ANALYTICS_EVENT_TYPE,

src/analytics/PosthogAnalytics.ts

@@ -8,28 +8,31 @@ Please see LICENSE in the repository root for full details.
 export interface ConfigOptions {
   /**
    * The Posthog endpoint to which analytics data will be sent.
+   * This is only used in the full package of Element Call.
    */
   posthog?: {
     api_key: string;
     api_host: string;
   };
   /**
    * The Sentry endpoint to which crash data will be sent.
+   * This is only used in the full package of Element Call.
    */
   sentry?: {
     DSN: string;
     environment: string;
   };
   /**
    * The rageshake server to which feedback and debug logs will be sent.
+   * This is only used in the full package of Element Call.
    */
   rageshake?: {
     submit_url: string;
   };
 
   /**
    * Sets the URL to send opentelemetry data to. If unset, opentelemetry will
-   * be disabled.
+   * be disabled. This is only used in the full package of Element Call.
    */
   opentelemetry?: {
     collector_url: string;