@formo/analytics-react-native 1.0.0 → 1.0.2

package/src/lib/crash/index.ts

@@ -0,0 +1,145 @@
+/**
+ * JavaScript crash reporting.
+ *
+ * Emits the Segment-spec `Application Crashed` event for unhandled JS errors by
+ * wrapping React Native's global error handler.
+ *
+ * Scope: JavaScript errors only. A native crash (a Swift/Kotlin exception, an
+ * OOM kill, a watchdog termination) never reaches the JS runtime, so it cannot
+ * be observed from here — that needs a native crash reporter.
+ */
+
+import { LIFECYCLE_EVENT } from "../../constants/events";
+import { logger } from "../logger";
+
+/** RN's global handler signature. */
+type ErrorHandler = (error: Error, isFatal?: boolean) => void;
+
+interface ErrorUtilsLike {
+  getGlobalHandler?: () => ErrorHandler | undefined;
+  setGlobalHandler?: (handler: ErrorHandler) => void;
+}
+
+/** Interface for the analytics instance to avoid circular deps */
+interface IAnalyticsInstance {
+  track(event: string, properties?: Record<string, unknown>): Promise<void>;
+  flush(): Promise<void>;
+}
+
+/** Stack traces can be long; cap them so one crash can't dominate a batch. */
+const MAX_STACK_LENGTH = 4000;
+
+function getErrorUtils(): ErrorUtilsLike | undefined {
+  // ErrorUtils is a React Native global, not an importable module. It is absent
+  // under plain Node (unit tests, SSR), hence the guarded lookup.
+  return (globalThis as { ErrorUtils?: ErrorUtilsLike }).ErrorUtils;
+}
+
+export class CrashReporter {
+  private analytics: IAnalyticsInstance;
+  private previousHandler: ErrorHandler | undefined;
+  private installedHandler: ErrorHandler | undefined;
+  private started = false;
+
+  constructor(analytics: IAnalyticsInstance) {
+    this.analytics = analytics;
+  }
+
+  /**
+   * Install the global error handler.
+   *
+   * The previous handler is always called afterwards — React Native's default
+   * handler is what shows the redbox in dev and terminates the app on a fatal
+   * error in production, and a customer's crash reporter (Sentry, Bugsnag) may
+   * also be in the chain. Swallowing it would break both.
+   */
+  start(): void {
+    if (this.started) return;
+
+    const errorUtils = getErrorUtils();
+    if (!errorUtils?.setGlobalHandler || !errorUtils?.getGlobalHandler) {
+      logger.debug(
+        "CrashReporter: ErrorUtils unavailable, skipping crash tracking",
+      );
+      return;
+    }
+
+    // Captured in the closure, NOT read from `this` at crash time. If another
+    // reporter wraps us afterwards our handler stays reachable through its
+    // chain, and cleanup() clearing the field would otherwise sever the chain
+    // at the moment it matters: A.start, B.start, A.cleanup, crash — B calls
+    // our handler, which would then forward to `undefined` and the real
+    // RN/default handler would never run.
+    const previousHandler = errorUtils.getGlobalHandler();
+    this.previousHandler = previousHandler;
+
+    const handler: ErrorHandler = (error, isFatal) => {
+      // Nothing in here may throw: this runs while the app is already failing,
+      // and an exception would replace the real crash with ours.
+      //
+      // `started` is checked so a cleaned-up reporter still FORWARDS (keeping
+      // the chain intact) but no longer reports — otherwise the sequence above
+      // would emit a duplicate Application Crashed from the stopped instance.
+      if (this.started) {
+        try {
+          this.report(error, isFatal);
+        } catch (reportingError) {
+          logger.debug("CrashReporter: failed to report crash", reportingError);
+        }
+      }
+
+      previousHandler?.(error, isFatal);
+    };
+
+    this.installedHandler = handler;
+    errorUtils.setGlobalHandler(handler);
+    this.started = true;
+    logger.info("CrashReporter: Started");
+  }
+
+  private report(error: Error, isFatal?: boolean): void {
+    const stack = typeof error?.stack === "string" ? error.stack : "";
+
+    // Fire and forget. On a fatal error the process is about to die, so the
+    // flush is a best effort — the queue also flushes on background and on the
+    // next launch's retry, which is where most fatal crashes are actually
+    // recovered from.
+    void this.analytics
+      .track(LIFECYCLE_EVENT.APPLICATION_CRASHED, {
+        message: error?.message ?? String(error),
+        name: error?.name ?? "Error",
+        stack: stack.slice(0, MAX_STACK_LENGTH),
+        stack_truncated: stack.length > MAX_STACK_LENGTH,
+        fatal: Boolean(isFatal),
+      })
+      .then(() => this.analytics.flush())
+      .catch((trackError) => {
+        logger.debug("CrashReporter: failed to send crash event", trackError);
+      });
+  }
+
+  /**
+   * Restore the previous handler.
+   *
+   * Only restores if ours is still the installed handler — if something else
+   * wrapped us afterwards, replacing the chain would unhook that too.
+   */
+  cleanup(): void {
+    if (!this.started) return;
+
+    const errorUtils = getErrorUtils();
+    if (
+      errorUtils?.getGlobalHandler?.() === this.installedHandler &&
+      errorUtils?.setGlobalHandler &&
+      this.previousHandler
+    ) {
+      errorUtils.setGlobalHandler(this.previousHandler);
+    }
+
+    // previousHandler is deliberately NOT cleared: if another reporter wrapped
+    // us, our installed handler is still in its chain and must keep forwarding.
+    this.started = false;
+    this.installedHandler = undefined;
+    logger.info("CrashReporter: Cleaned up");
+  }
+}

package/src/lib/event/EventFactory.ts

@@ -117,6 +117,70 @@ export function getSessionId(): string {
  * containing the tokens the classifier keys off (iphone/ipad/android + version)
  * so mobile device and OS resolve correctly. Returns "" for unknown platforms.
  */
+/**
+ * Resolve `device_type` from expo-device's `deviceType` enum.
+ *
+ * Extracted and guarded because the Expo branch of getDeviceInfo() runs when
+ * EITHER expo-device or expo-application is installed, so `deviceType` may be
+ * undefined. A bare `deviceType === DeviceType.TABLET` is then
+ * `undefined === undefined` — true — and every device reports as a tablet,
+ * which also flips the synthesized user agent to iPad/Tablet and corrupts
+ * 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(/^\/+/, "")
+    // Percent-encode the characters that would otherwise change the URL's
+    // STRUCTURE rather than its path. '?' starts a query and '#' a fragment, so
+    // screen("Checkout?coupon=X") would parse with pathname "/Checkout" and the
+    // rest silently dropped from the screen name. '/' is deliberately NOT
+    // encoded — router-style names like "/tabs/leaderboard" are meant to be
+    // path segments.
+    // '%' FIRST, so the transform stays injective. Without it a screen literally
+    // named "Checkout%3Fx" and one named "Checkout?x" both produce
+    // ".../Checkout%3Fx" and two distinct screens merge in the analytics.
+    .replace(/%/g, "%25")
+    .replace(/\?/g, "%3F")
+    .replace(/#/g, "%23");
+  return `app://${bundleId ?? ""}/${screen}`;
+}
+
+export function resolveExpoDeviceType(
+  deviceType: number | null | undefined,
+  tabletEnumValue: number | null | undefined,
+): "tablet" | "mobile" {
+  if (deviceType == null || tabletEnumValue == null) return "mobile";
+  return deviceType === tabletEnumValue ? "tablet" : "mobile";
+}
+
 export function synthesizeUserAgent(info: {
   os_name: string;
   os_version: string;
@@ -146,6 +210,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;
@@ -269,19 +335,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 {
@@ -324,11 +403,13 @@ class EventFactory implements IEventFactory {
     // Fall back to Expo modules (Expo Go)
     if (ExpoDevice || ExpoApplication) {
       try {
-        const isTablet = ExpoDevice?.deviceType === ExpoDevice?.DeviceType?.TABLET;
         const os_name = ExpoDevice?.osName || Platform.OS;
         const os_version = ExpoDevice?.osVersion || String(Platform.Version);
         const device_model = ExpoDevice?.modelName || "Unknown";
-        const device_type = isTablet ? "tablet" : "mobile";
+        const device_type = resolveExpoDeviceType(
+          ExpoDevice?.deviceType,
+          ExpoDevice?.DeviceType?.TABLET,
+        );
         return {
           os_name,
           os_version,
@@ -488,15 +569,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 ?? {}),
     };
 

package/src/lib/lifecycle/index.ts

@@ -6,8 +6,15 @@
  * - Application Updated (version/build changed)
  * - Application Opened (every cold start + foreground return)
  * - Application Backgrounded (app goes to background)
+ * - Application Foregrounded (foreground return; opt-in, see AutocaptureOptions)
  *
  * Detection is JS-side using AsyncStorage (no native modules required).
+ *
+ * The remaining spec events live outside this manager because they are not
+ * AppState-driven: `Deep Link Opened` is emitted from the Linking hook in
+ * FormoAnalytics, `Application Crashed` from lib/crash, and the push
+ * notification events from explicit FormoAnalytics methods (the SDK cannot
+ * observe push delivery without a native module).
  */
 
 import { AppState, AppStateStatus, Linking } from "react-native";
@@ -18,6 +25,7 @@ import {
   LOCAL_APP_BUILD_KEY,
 } from "../../constants/storage";
 import { getStoredTrafficSource } from "../../utils/trafficSource";
+import { LIFECYCLE_EVENT } from "../../constants/events";
 
 /** Interface for the analytics instance to avoid circular deps */
 interface IAnalyticsInstance {
@@ -75,6 +83,7 @@ export class AppLifecycleManager {
   private appStateSubscription: { remove: () => void } | null = null;
   private lastAppState: AppStateStatus = AppState.currentState;
   private appVersionInfo: AppVersionInfo = { version: "", build: "" };
+  private trackForegrounded = false;
 
   constructor(analytics: IAnalyticsInstance) {
     this.analytics = analytics;
@@ -85,8 +94,10 @@ export class AppLifecycleManager {
    * Detects install/update, fires Application Opened, and sets up AppState listener.
    */
   async start(
-    appOptions?: { version?: string; build?: string }
+    appOptions?: { version?: string; build?: string },
+    options?: { trackForegrounded?: boolean }
   ): Promise<void> {
+    this.trackForegrounded = options?.trackForegrounded ?? false;
     this.appVersionInfo = await resolveAppVersionInfo(appOptions);
 
     // Detect install vs update
@@ -103,7 +114,7 @@ export class AppLifecycleManager {
       // Linking not available
     }
 
-    await this.analytics.track("Application Opened", {
+    await this.analytics.track(LIFECYCLE_EVENT.APPLICATION_OPENED, {
       version: this.appVersionInfo.version,
       build: this.appVersionInfo.build,
       from_background: false,
@@ -151,7 +162,7 @@ export class AppLifecycleManager {
         Object.entries(trafficSource).filter(([, value]) => Boolean(value))
       );
       logger.info("AppLifecycleManager: Application Installed");
-      await this.analytics.track("Application Installed", {
+      await this.analytics.track(LIFECYCLE_EVENT.APPLICATION_INSTALLED, {
         version,
         build,
         ...attribution,
@@ -159,7 +170,7 @@ export class AppLifecycleManager {
     } else if (previousVersion !== version || previousBuild !== build) {
       // Version or build changed — update
       logger.info("AppLifecycleManager: Application Updated");
-      await this.analytics.track("Application Updated", {
+      await this.analytics.track(LIFECYCLE_EVENT.APPLICATION_UPDATED, {
         version,
         build,
         previous_version: previousVersion || "",
@@ -186,7 +197,7 @@ export class AppLifecycleManager {
     if (nextAppState === "active" && this.lastAppState === "background") {
       // Returning from background
       this.analytics
-        .track("Application Opened", {
+        .track(LIFECYCLE_EVENT.APPLICATION_OPENED, {
           version: this.appVersionInfo.version,
           build: this.appVersionInfo.build,
           from_background: true,
@@ -194,12 +205,30 @@ export class AppLifecycleManager {
         .catch((error) => {
           logger.error("AppLifecycleManager: Error tracking Application Opened", error);
         });
+
+      // The Segment spec's dedicated name for this same transition. Opt-in,
+      // because emitting it alongside Application Opened doubles foreground
+      // volume for no extra information — it exists for consumers that key on
+      // the spec name rather than on `from_background`.
+      if (this.trackForegrounded) {
+        this.analytics
+          .track(LIFECYCLE_EVENT.APPLICATION_FOREGROUNDED, {
+            version: this.appVersionInfo.version,
+            build: this.appVersionInfo.build,
+          })
+          .catch((error) => {
+            logger.error(
+              "AppLifecycleManager: Error tracking Application Foregrounded",
+              error
+            );
+          });
+      }
     }
 
     if (nextAppState === "background" && this.lastAppState === "active") {
       // Going to background
       this.analytics
-        .track("Application Backgrounded", {
+        .track(LIFECYCLE_EVENT.APPLICATION_BACKGROUNDED, {
           version: this.appVersionInfo.version,
           build: this.appVersionInfo.build,
         })

package/src/types/base.ts

@@ -95,6 +95,13 @@ export interface IFormoAnalytics {
     callback?: (...args: unknown[]) => void
   ): Promise<void>;
 
+  // Push notification lifecycle events. Not autocaptured: push delivery is
+  // invisible to JavaScript without a native module, so the host app forwards
+  // these from its own push handler.
+  pushNotificationReceived(properties?: IFormoEventProperties): Promise<void>;
+  pushNotificationTapped(properties?: IFormoEventProperties): Promise<void>;
+  pushNotificationBounced(properties?: IFormoEventProperties): Promise<void>;
+
   // Event flushing
   flush(): Promise<void>;
 
@@ -158,6 +165,46 @@ export interface AutocaptureOptions {
    * @default true
    */
   lifecycle?: boolean;
+
+  /**
+   * Emit `Application Foregrounded` on every background → active transition,
+   * in addition to the `Application Opened` (with `from_background: true`) that
+   * already fires there.
+   *
+   * Off by default because it doubles foreground event volume and adds no
+   * information: `Application Opened` with `from_background: true` already
+   * marks the same transition. Enable it if you consume the Segment spec's
+   * `Application Foregrounded` name directly — e.g. when migrating dashboards
+   * or destinations from Segment or RudderStack. Requires `lifecycle`.
+   * @default false
+   */
+  foregrounded?: boolean;
+
+  /**
+   * Track `Deep Link Opened` when the app is launched or resumed via a deep
+   * link or universal link, with the `url` property.
+   *
+   * Independent of `attribution.deeplinks`, which controls whether the link's
+   * UTM/referral parameters are parsed into event context. This option is only
+   * about emitting the event; the SDK still needs `attribution.deeplinks` to
+   * observe links at all.
+   * @default true
+   */
+  deepLinks?: boolean;
+
+  /**
+   * Track `Application Crashed` on unhandled JavaScript errors, with the error
+   * message, stack, and whether React Native considered it fatal.
+   *
+   * Off by default because enabling it installs a global error handler
+   * (`ErrorUtils.setGlobalHandler`). The previous handler is always invoked
+   * afterwards, so React Native's redbox and any crash reporter you already use
+   * keep working — but installing one implicitly on an SDK upgrade is a
+   * surprise, so it is opt-in. Covers JS errors only: native crashes need a
+   * native crash reporter.
+   * @default false
+   */
+  crashes?: boolean;
 }
 
 /**

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated by scripts/update-version.js during npm version
 // Do not edit manually - it will be overwritten
-export const version = '1.0.0';
+export const version = '1.0.2';