Emit screen views as a well-formed app://<bundle id>/<screen> URL (#71)

* Emit screen views as a well-formed app://<bundle id>/<screen> URL

page_url was app://<screen>, which is not a valid URL: the screen name lands
in the authority slot and there is no path at all. Every URL parser therefore
returns an empty path, which is why the ingestion pipeline had to reconstruct
both origin and page_path by hand instead of using the URL functions it
already applies to web events.

Now app://com.acme.wallet/Home — bundle id as the authority, screen as the
path, mirroring https://host/path. domainWithoutWWW() yields the bundle id and
path() yields the screen, with no mobile-specific handling.

The bundle id is also the right authority for the same reason a hostname is:
stable and globally unique. A display name is neither — renaming an app would
split its history, and two apps sharing a name would merge.

Falls back to an empty authority (app:///Home) when no bundle id is available,
which still parses to a correct path; the pipeline resolves origin from
context there. Leading slashes in the screen name are stripped so a
router-style name does not produce a doubled separator.

getDeviceInfo() is now memoised. Screen events need the bundle id and
generateContext needs the same values for every event, so without it each
screen view would cost two native bridge round-trips; with it, zero after the
first event.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Use the configured bundle id for the screen URL, not just the detected one

generateContext lets options.app.bundleId override whatever the native
modules report, but the screen URL read getDeviceInfo() directly — so an
explicitly configured bundle id was ignored and every screen URL silently
fell back to the authority-less form.

Caught by running the example app: it configures
app.bundleId = "com.formo.analytics.demo" and got "app:///Wallet". On React
Native Web that is the only way to get a bundle id at all, since neither
react-native-device-info nor expo-application resolves one there.

Extracted resolveAppBundleId() so the URL and context.app_bundle_id cannot
disagree, and added tests for both precedence orders.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: yosriady

src/__tests__/lifecycleWire.integration.test.ts

@@ -240,10 +240,12 @@ describe("lifecycle events on the wire", () => {
     await analytics.screen("Wallet");
     await analytics.flush();
 
+    // Well-formed: bundle id in the authority, screen in the path, so the
+    // Tinybird pipe parses both with plain URL functions.
     expect(sent[0]).toMatchObject({
       type: "page",
       channel: "mobile",
-      context: expect.objectContaining({ page_url: "app://Wallet" }),
+      context: expect.objectContaining({ page_url: "app://com.test.app/Wallet" }),
     });
   });
 

src/__tests__/screenEvent.test.ts

@@ -1,35 +1,77 @@
-import { EventFactory } from "../lib/event/EventFactory";
+import { EventFactory, buildScreenUrl } from "../lib/event/EventFactory";
 import { initStorageManager } from "../lib/storage";
 
 /**
- * Mobile screen views are emitted as type="page" with page_url `app://<name>`.
- * The ingestion pipeline (P-2070) owns the interpretation: it derives `origin`
- * from the app identifier in context (app_name / app_bundle_id) and `page_path`
- * by stripping the app:// scheme. So the SDK emits the screen name as-is and
- * must NOT encode an app host in the URL — doing so would leak the host into the
- * backend-derived page_path.
+ * Mobile screen views are emitted as type="page" with
+ * page_url = `app://<bundle id>/<screen>`.
+ *
+ * The shape is the point: it is a well-formed URL, so the bundle id sits in the
+ * authority slot and the screen in the path — exactly like `https://<host>/<path>`
+ * on web. A standard URL parser therefore yields origin and page_path directly,
+ * with no mobile-specific reconstruction downstream.
+ *
+ * The previous form, `app://<screen>`, was malformed: the screen name occupied
+ * the authority and there was no path at all, so parsers returned an empty path
+ * and the pipeline had to rebuild both fields by hand.
+ *
+ * jest.setup mocks react-native-device-info with getBundleId() -> "com.test.app".
  */
+describe("buildScreenUrl", () => {
+  it("puts the bundle id in the authority and the screen in the path", () => {
+    expect(buildScreenUrl("com.acme.wallet", "Home")).toBe(
+      "app://com.acme.wallet/Home",
+    );
+  });
+
+  it("does not double the separator for router-style names", () => {
+    expect(buildScreenUrl("com.acme.wallet", "/tabs/leaderboard")).toBe(
+      "app://com.acme.wallet/tabs/leaderboard",
+    );
+    expect(buildScreenUrl("com.acme.wallet", "///deep")).toBe(
+      "app://com.acme.wallet/deep",
+    );
+  });
+
+  it("preserves nested screen paths", () => {
+    expect(buildScreenUrl("com.acme.wallet", "tabs/leaderboard")).toBe(
+      "app://com.acme.wallet/tabs/leaderboard",
+    );
+  });
+
+  it("omits the authority when there is no bundle id, keeping the path parseable", () => {
+    // app:///Home still yields path "/Home"; the pipeline resolves origin from
+    // context in this case rather than from the URL.
+    expect(buildScreenUrl("", "Home")).toBe("app:///Home");
+  });
+
+  it("handles an empty screen name as the app root", () => {
+    expect(buildScreenUrl("com.acme.wallet", "")).toBe("app://com.acme.wallet/");
+  });
+});
+
 describe("generateScreenEvent page_url", () => {
   beforeEach(() => initStorageManager("screen-test-key"));
 
-  it("emits the screen name as app://<name>", async () => {
+  it("emits app://<bundle id>/<screen>", async () => {
     const factory = new EventFactory();
     const evt = await factory.generateScreenEvent("Home");
-    expect(evt.context?.page_url).toBe("app://Home");
+    expect(evt.context?.page_url).toBe("app://com.test.app/Home");
     expect(evt.context?.page_title).toBe("Home");
   });
 
-  it("passes router-style paths through unchanged", async () => {
+  it("normalises router-style paths into the URL path", async () => {
     const factory = new EventFactory();
     const evt = await factory.generateScreenEvent("/tabs/leaderboard");
-    expect(evt.context?.page_url).toBe("app:///tabs/leaderboard");
+    expect(evt.context?.page_url).toBe("app://com.test.app/tabs/leaderboard");
   });
 
-  it("does NOT encode the app bundle id into the URL (backend owns origin)", async () => {
-    const factory = new EventFactory({ app: { bundleId: "com.formo.test" } });
+  it("keeps the screen name out of the authority", async () => {
+    // The regression the well-formed shape exists to prevent: with the screen
+    // in the authority slot, URL parsers report an empty path.
+    const factory = new EventFactory();
     const evt = await factory.generateScreenEvent("Wallet");
-    expect(evt.context?.page_url).toBe("app://Wallet");
-    expect(String(evt.context?.page_url)).not.toContain("com.formo.test");
+    expect(evt.context?.page_url).not.toBe("app://Wallet");
+    expect(String(evt.context?.page_url)).toContain("/Wallet");
   });
 
   it("keeps user-supplied context (spread last)", async () => {
@@ -39,4 +81,48 @@ describe("generateScreenEvent page_url", () => {
     });
     expect(evt.context?.page_url).toBe("app://Custom");
   });
+
+  it("resolves device info once across repeated screen events", async () => {
+    // getDeviceInfo() is memoised because it crosses the native bridge and its
+    // values are static. Screen events now depend on it for the bundle id, and
+    // generateContext needs it for every event too — without the memo each
+    // screen view would cost two round-trips instead of zero.
+    const factory = new EventFactory();
+    const resolve = jest.spyOn(
+      factory as unknown as { resolveDeviceInfo: () => Promise<unknown> },
+      "resolveDeviceInfo",
+    );
+
+    await factory.generateScreenEvent("Home");
+    await factory.generateScreenEvent("Wallet");
+    await factory.generateScreenEvent("Settings");
+
+    expect(resolve).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("generateScreenEvent bundle id resolution", () => {
+  beforeEach(() => initStorageManager("screen-bundle-key"));
+
+  it("prefers an explicitly configured options.app.bundleId", async () => {
+    // generateContext lets options.app.bundleId override the native modules, so
+    // the URL has to use the same precedence. Reading device info alone would
+    // ignore the configuration — and on React Native Web nothing else resolves a
+    // bundle id, so every screen URL would lose its authority.
+    const factory = new EventFactory({ app: { bundleId: "com.configured.app" } });
+    const evt = await factory.generateScreenEvent("Wallet");
+
+    expect(evt.context?.page_url).toBe("app://com.configured.app/Wallet");
+    // The URL authority and the context field must not disagree.
+    expect(evt.context?.app_bundle_id).toBe("com.configured.app");
+  });
+
+  it("falls back to the detected bundle id when none is configured", async () => {
+    const factory = new EventFactory();
+    const evt = await factory.generateScreenEvent("Wallet");
+
+    expect(evt.context?.page_url).toBe(
+      `app://${evt.context?.app_bundle_id}/Wallet`,
+    );
+  });
 });

src/lib/event/EventFactory.ts

@@ -128,6 +128,38 @@ export function getSessionId(): string {
  * device breakdowns downstream. Unknown means "mobile", the safe default for a
  * React Native app.
  */
+interface DeviceInfoResult {
+  os_name: string;
+  os_version: string;
+  device_model: string;
+  device_manufacturer: string;
+  device_name: string;
+  device_type: string;
+  user_agent: string;
+  app_name: string;
+  app_version: string;
+  app_build: string;
+  app_bundle_id: string;
+}
+
+/**
+ * Compose a screen view's `page_url` as `app://<bundle id>/<screen>`.
+ *
+ * Well-formed on purpose: the bundle id occupies the authority slot and the
+ * screen the path, so a standard URL parser yields both without any
+ * mobile-specific handling — the same shape as `https://<host>/<path>`.
+ *
+ * @param bundleId Application bundle id, e.g. "com.acme.wallet". When empty the
+ *   authority is omitted (`app:///<screen>`), which still parses to a correct
+ *   path; the pipeline resolves origin from context in that case.
+ * @param name Screen name. Leading slashes are stripped so a router-style name
+ *   ("/tabs/leaderboard") does not produce a doubled separator.
+ */
+export function buildScreenUrl(bundleId: string, name: string): string {
+  const screen = (name ?? "").replace(/^\/+/, "");
+  return `app://${bundleId ?? ""}/${screen}`;
+}
+
 export function resolveExpoDeviceType(
   deviceType: number | null | undefined,
   tabletEnumValue: number | null | undefined,
@@ -165,6 +197,8 @@ export function synthesizeUserAgent(info: {
  */
 class EventFactory implements IEventFactory {
   private options?: Options;
+  /** Memoised device/app identity — see getDeviceInfo(). */
+  private deviceInfoPromise?: Promise<DeviceInfoResult>;
 
   constructor(options?: Options) {
     this.options = options;
@@ -288,19 +322,32 @@ class EventFactory implements IEventFactory {
    * Get device information
    * Supports both react-native-device-info (bare RN) and expo-device/expo-application (Expo Go)
    */
-  private async getDeviceInfo(): Promise<{
-    os_name: string;
-    os_version: string;
-    device_model: string;
-    device_manufacturer: string;
-    device_name: string;
-    device_type: string;
-    user_agent: string;
-    app_name: string;
-    app_version: string;
-    app_build: string;
-    app_bundle_id: string;
-  }> {
+  /**
+   * The app bundle id as it will appear in context.
+   *
+   * Must mirror generateContext's precedence: an explicitly configured
+   * `options.app.bundleId` overrides whatever the native modules report. Reading
+   * getDeviceInfo() alone would ignore that configuration and silently fall back
+   * to the authority-less URL form — and on React Native Web, where neither
+   * react-native-device-info nor expo-application resolves a bundle id, that is
+   * the ONLY value available.
+   */
+  private async resolveAppBundleId(): Promise<string> {
+    return (
+      this.options?.app?.bundleId || (await this.getDeviceInfo()).app_bundle_id || ""
+    );
+  }
+
+  private async getDeviceInfo(): Promise<DeviceInfoResult> {
+    // Device and app identity do not change for the lifetime of the process,
+    // and resolving them crosses the native bridge. Memoise the promise so
+    // every event after the first is free, and so callers that need only the
+    // app identifier (screen events) can ask without paying twice.
+    this.deviceInfoPromise ??= this.resolveDeviceInfo();
+    return this.deviceInfoPromise;
+  }
+
+  private async resolveDeviceInfo(): Promise<DeviceInfoResult> {
     // Try react-native-device-info first (bare RN and Expo dev builds)
     if (DeviceInfo) {
       try {
@@ -509,15 +556,28 @@ class EventFactory implements IEventFactory {
     const props = { ...(properties ?? {}), name, ...(category && { category }) };
 
     // Map screen name to page-equivalent context fields so mobile screens flow
-    // through the same analytics as web page views. The screen name is emitted
-    // as-is in the app:// URL; the ingestion pipeline derives `origin` (from the
-    // app identifier in context — app_name / app_bundle_id) and `page_path` (by
-    // stripping the app:// scheme), so the SDK deliberately does NOT encode a
-    // host here (see backend mobile page-event handling, P-2070).
+    // through the same analytics as web page views.
+    //
+    // The URL is app://<bundle id>/<screen>, which is a WELL-FORMED URL: the
+    // bundle id is the authority and the screen is the path, exactly mirroring
+    // https://<host>/<path> on web. That is what lets the ingestion pipeline
+    // parse it with the same URL functions it uses for web — the authority
+    // becomes `origin` and the path becomes `page_path`, with no mobile
+    // special-casing.
+    //
+    // The earlier form was app://<screen>, which is malformed: the screen name
+    // lands in the authority slot and there is no path at all, so a URL parser
+    // yields an empty path and the pipeline had to reconstruct both fields by
+    // hand. The bundle id is also the right choice of authority because, like a
+    // hostname, it is stable and globally unique — a display name is neither.
+    //
+    // Falls back to an empty authority (app:///<screen>) when the bundle id is
+    // unavailable, which keeps the path parseable and lets the pipeline resolve
+    // origin from context instead.
     // User-supplied context values take precedence (spread last).
     const screenContext: IFormoEventContext = {
       page_title: name,
-      page_url: `app://${name}`,
+      page_url: buildScreenUrl(await this.resolveAppBundleId(), name),
       ...(context ?? {}),
     };