@formo/analytics-react-native 0.1.4 → 1.0.0

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@formo/analytics-react-native",
-  "version": "0.1.4",
+  "version": "1.0.0",
   "description": "Formo Analytics SDK for React Native - Track wallet events and user analytics in mobile dApps",
-  "packageManager": "pnpm@10.27.0",
+  "packageManager": "pnpm@11.1.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/getformo/sdk-react-native.git"
   },
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
-  "types": "lib/typescript/index.d.ts",
+  "types": "lib/typescript/commonjs/index.d.ts",
   "react-native": "src/index.ts",
   "source": "src/index.ts",
   "files": [
@@ -21,9 +21,14 @@
   ],
   "exports": {
     ".": {
-      "import": "./lib/module/index.js",
-      "require": "./lib/commonjs/index.js",
-      "types": "./lib/typescript/index.d.ts"
+      "import": {
+        "types": "./lib/typescript/module/index.d.ts",
+        "default": "./lib/module/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/index.d.ts",
+        "default": "./lib/commonjs/index.js"
+      }
     }
   },
   "private": false,
@@ -63,6 +68,7 @@
     "react": ">=18.0.0",
     "react-native": ">=0.70.0",
     "react-native-device-info": ">=10.0.0",
+    "react-native-play-install-referrer": ">=1.1.8",
     "wagmi": ">=2.0.0"
   },
   "peerDependenciesMeta": {
@@ -81,66 +87,55 @@
     "react-native-device-info": {
       "optional": true
     },
+    "react-native-play-install-referrer": {
+      "optional": true
+    },
     "wagmi": {
       "optional": true
     }
   },
   "dependencies": {
-    "@react-native-community/netinfo": "^11.5.1",
+    "@react-native-community/netinfo": "12.0.1",
     "ethereum-cryptography": "3.2.0"
   },
   "devDependencies": {
-    "@babel/preset-env": "^7.29.0",
+    "@babel/preset-env": "^7.29.5",
     "@babel/preset-react": "^7.28.5",
     "@babel/preset-typescript": "^7.28.5",
     "@react-native-async-storage/async-storage": "^1.21.0",
-    "@react-native/babel-preset": "^0.77.0",
-    "@types/jest": "^29.5.12",
-    "@types/react": "^18.0.25",
-    "@typescript-eslint/eslint-plugin": "^8.57.2",
-    "@typescript-eslint/parser": "^8.57.2",
-    "babel-jest": "^29.7.0",
-    "eslint": "^10.1.0",
-    "expo-application": "^6.0.0",
-    "expo-device": "^7.0.0",
-    "jest": "^29.7.0",
-    "react": "^18.3.1",
-    "react-native": "^0.77.0",
-    "react-native-builder-bob": "^0.23.0",
+    "@react-native/babel-preset": "^0.85.3",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.2.14",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "babel-jest": "^30.4.1",
+    "eslint": "^10.3.0",
+    "expo-application": "^55.0.15",
+    "expo-device": "^55.0.17",
+    "jest": "^30.4.1",
+    "react": "^19.2.6",
+    "react-native": "^0.85.3",
+    "react-native-builder-bob": "^0.41.0",
     "react-native-device-info": "^14.0.0",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.57.2"
-  },
-  "pnpm": {
-    "overrides": {
-      "@react-native-community/cli": ">=17.0.1",
-      "@react-native-community/cli-server-api": ">=17.0.1",
-      "@xmldom/xmldom": ">=0.8.12",
-      "brace-expansion@1": ">=1.1.13 <2",
-      "brace-expansion@2": ">=2.0.3 <3",
-      "fast-xml-parser": ">=4.5.5",
-      "minimatch@3": ">=3.1.5 <4",
-      "minimatch@5": ">=5.1.9 <6",
-      "minimatch@9": ">=9.0.9 <10",
-      "minimatch@10": ">=10.2.4",
-      "node-forge": ">=1.4.0",
-      "picomatch@2": ">=2.3.2 <3",
-      "picomatch@3": ">=3.0.2 <4",
-      "picomatch@4": ">=4.0.4",
-      "semver@5": ">=7.7.4",
-      "semver@6": ">=7.7.4",
-      "tar": ">=7.5.13",
-      "undici": ">=6.24.1 <7",
-      "yaml@1": ">=1.10.3 <2",
-      "yaml@2": ">=2.8.3 <3"
-    }
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.3"
   },
   "react-native-builder-bob": {
     "source": "src",
     "output": "lib",
     "targets": [
-      "commonjs",
-      "module",
+      [
+        "commonjs",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
       [
         "typescript",
         {

package/src/FormoAnalytics.ts

@@ -8,6 +8,8 @@ import {
   EVENTS_API_HOST,
   EventType,
   LOCAL_ANONYMOUS_ID_KEY,
+  LOCAL_SESSION_ID_KEY,
+  LOCAL_SESSION_LAST_ACTIVITY_KEY,
   SESSION_USER_ID_KEY,
   CONSENT_OPT_OUT_KEY,
   TEventType,
@@ -35,8 +37,10 @@ import {
   TrackingOptions,
   TransactionStatus,
 } from "./types";
-import { toChecksumAddress, getValidAddress } from "./utils";
-import { parseTrafficSource, storeTrafficSource } from "./utils/trafficSource";
+import { validateAddress } from "./utils";
+import { parseTrafficSource, updateStoredTrafficSource } from "./utils/trafficSource";
+import { captureInstallReferrer } from "./lib/installReferrer";
+import { Linking, EmitterSubscription } from "react-native";
 
 export class FormoAnalytics implements IFormoAnalytics {
   private session: FormoAnalyticsSession;
@@ -44,6 +48,7 @@ export class FormoAnalytics implements IFormoAnalytics {
   private eventQueue: EventQueue;
   private wagmiHandler?: WagmiEventHandler;
   private lifecycleManager?: AppLifecycleManager;
+  private linkingSubscription?: EmitterSubscription;
 
   config: Config;
   currentChainId?: ChainID;
@@ -128,6 +133,34 @@ export class FormoAnalytics implements IFormoAnalytics {
 
     const analytics = new FormoAnalytics(writeKey, options);
 
+    // Capture attribution BEFORE lifecycle tracking so the first
+    // Application Installed/Opened events carry utm_*/ref/referrer.
+    //
+    // Both are awaited so the stored traffic source is populated before
+    // lifecycle fires — that's what lets Application Installed report the
+    // web-to-mobile referrer (e.g. referrer=example.com). Deep-link initial URL
+    // is a fast native bridge call; the Android Play Install Referrer is a fast
+    // one-shot native call (and no-ops instantly when the native module or the
+    // platform isn't Android), so awaiting it does not meaningfully delay init.
+    if (analytics.isAttributionEnabled("deeplinks")) {
+      try {
+        await analytics.startDeepLinkCapture();
+      } catch (error) {
+        logger.error("FormoAnalytics: Failed to initialize deep link capture", error);
+      }
+    }
+
+    if (analytics.isAttributionEnabled("installReferrer")) {
+      try {
+        await captureInstallReferrer({
+          customRefParams: analytics.options.referral?.queryParams,
+          pathPattern: analytics.options.referral?.pathPattern,
+        });
+      } catch (error) {
+        logger.debug("FormoAnalytics: install referrer capture failed", error);
+      }
+    }
+
     // Initialize lifecycle tracking if enabled
     // Wrapped in try-catch so a transient storage failure doesn't prevent SDK init
     if (analytics.isAutocaptureEnabled("lifecycle")) {
@@ -147,6 +180,25 @@ export class FormoAnalytics implements IFormoAnalytics {
     return analytics;
   }
 
+  /**
+   * Hook into React Native's Linking API to auto-capture traffic source from
+   * the launch URL and any subsequent deep-link opens. Awaits the initial URL
+   * so attribution is in storage before the first lifecycle event fires.
+   */
+  private async startDeepLinkCapture(): Promise<void> {
+    try {
+      const url = await Linking.getInitialURL();
+      if (url) this.setTrafficSourceFromUrl(url);
+    } catch (error) {
+      logger.debug("FormoAnalytics: Linking.getInitialURL failed", error);
+    }
+
+    // Runtime deep links (foreground opens, universal links).
+    this.linkingSubscription = Linking.addEventListener("url", (event) => {
+      if (event?.url) this.setTrafficSourceFromUrl(event.url);
+    });
+  }
+
   /**
    * Track a screen view (mobile equivalent of page view)
    */
@@ -195,7 +247,10 @@ export class FormoAnalytics implements IFormoAnalytics {
       this.options.referral?.queryParams,
       this.options.referral?.pathPattern
     );
-    storeTrafficSource(trafficSource);
+    // Per-field merge: incoming non-empty fields win, empty fields preserve
+    // stored values. A non-marketing deep link (e.g. "myapp://home") with only
+    // a referrer will not destroy previously captured utm_*/ref attribution.
+    updateStoredTrafficSource(trafficSource);
     logger.debug("Traffic source set from URL:", trafficSource);
   }
 
@@ -205,6 +260,8 @@ export class FormoAnalytics implements IFormoAnalytics {
   public reset(): void {
     this.currentUserId = undefined;
     storage().remove(LOCAL_ANONYMOUS_ID_KEY);
+    storage().remove(LOCAL_SESSION_ID_KEY);
+    storage().remove(LOCAL_SESSION_LAST_ACTIVITY_KEY);
     storage().remove(SESSION_USER_ID_KEY);
     this.session.clear();
   }
@@ -220,6 +277,11 @@ export class FormoAnalytics implements IFormoAnalytics {
       this.lifecycleManager = undefined;
     }
 
+    if (this.linkingSubscription) {
+      this.linkingSubscription.remove();
+      this.linkingSubscription = undefined;
+    }
+
     if (this.wagmiHandler) {
       this.wagmiHandler.cleanup();
       this.wagmiHandler = undefined;
@@ -250,8 +312,8 @@ export class FormoAnalytics implements IFormoAnalytics {
       return;
     }
 
-    const checksummedAddress = this.validateAndChecksumAddress(address);
-    if (!checksummedAddress) {
+    const validatedAddress = this.validateAndChecksumAddress(address, chainId);
+    if (!validatedAddress) {
       logger.warn(`Connect: Invalid address provided ("${address}")`);
       return;
     }
@@ -259,14 +321,14 @@ export class FormoAnalytics implements IFormoAnalytics {
     // Track event before updating state so connect events TO excluded chains are tracked
     await this.trackEvent(
       EventType.CONNECT,
-      { chainId, address: checksummedAddress },
+      { chainId, address: validatedAddress },
       properties,
       context,
       callback
     );
 
     this.currentChainId = chainId;
-    this.currentAddress = checksummedAddress;
+    this.currentAddress = validatedAddress;
   }
 
   /**
@@ -345,13 +407,11 @@ export class FormoAnalytics implements IFormoAnalytics {
       chainId,
       address,
       message,
-      signatureHash,
     }: {
       status: SignatureStatus;
       chainId?: ChainID;
       address: Address;
       message: string;
-      signatureHash?: string;
     },
     properties?: IFormoEventProperties,
     context?: IFormoEventContext,
@@ -368,7 +428,6 @@ export class FormoAnalytics implements IFormoAnalytics {
         ...(chainId !== undefined && chainId !== null && { chainId }),
         address,
         message,
-        ...(signatureHash && { signatureHash }),
       },
       properties,
       context,
@@ -458,6 +517,8 @@ export class FormoAnalytics implements IFormoAnalytics {
           return;
         }
         this.currentAddress = validAddress;
+        // Note: validateAddress returns Solana addresses unchanged (Base58, case-sensitive)
+        // and EVM addresses checksummed.
       } else {
         this.currentAddress = undefined;
       }
@@ -566,10 +627,19 @@ export class FormoAnalytics implements IFormoAnalytics {
   }
 
   /**
-   * Check if autocapture is enabled for event type
+   * Check if autocapture is enabled for a given event type.
+   * Applies only to event-generating behaviors (wallet events, lifecycle
+   * events). Attribution is controlled separately via `options.attribution`
+   * because it enriches events rather than generating them.
    */
   public isAutocaptureEnabled(
-    eventType: "connect" | "disconnect" | "signature" | "transaction" | "chain" | "lifecycle"
+    eventType:
+      | "connect"
+      | "disconnect"
+      | "signature"
+      | "transaction"
+      | "chain"
+      | "lifecycle"
   ): boolean {
     if (this.options.autocapture === undefined) {
       return true;
@@ -590,6 +660,32 @@ export class FormoAnalytics implements IFormoAnalytics {
     return true;
   }
 
+  /**
+   * Check if an attribution source is enabled. Attribution is not an event
+   * type — it decorates every tracked event with `utm_*`, `ref`, and
+   * `referrer` context fields.
+   */
+  public isAttributionEnabled(
+    source: "deeplinks" | "installReferrer"
+  ): boolean {
+    if (this.options.attribution === undefined) {
+      return true;
+    }
+
+    if (typeof this.options.attribution === "boolean") {
+      return this.options.attribution;
+    }
+
+    if (
+      this.options.attribution !== null &&
+      typeof this.options.attribution === "object"
+    ) {
+      return this.options.attribution[source] !== false;
+    }
+
+    return true;
+  }
+
   /**
    * Internal method to track events
    * This is the single enforcement point for shouldTrack() - all public tracking
@@ -669,11 +765,17 @@ export class FormoAnalytics implements IFormoAnalytics {
   }
 
   /**
-   * Validate and checksum address
+   * Validate and normalize an address for the given chain.
+   *
+   * EVM addresses are returned in EIP-55 checksum format.
+   * Solana addresses are returned as-is (Base58 is case-sensitive).
+   * When chainId is omitted, EVM is tried first with Solana as fallback.
    */
-  private validateAndChecksumAddress(address: string): Address | undefined {
-    const validAddress = getValidAddress(address);
-    return validAddress ? toChecksumAddress(validAddress) : undefined;
+  private validateAndChecksumAddress(
+    address: string,
+    chainId?: ChainID
+  ): Address | undefined {
+    return validateAddress(address, chainId);
   }
 
   /**

package/src/constants/events.ts

@@ -24,3 +24,7 @@ export type TEventChannel = Lowercase<EventChannel>;
 // React Native SDK uses mobile channel
 export const CHANNEL: TEventChannel = "mobile";
 export const VERSION = "0";
+
+// Session inactivity timeout (30 min), matching the GA4/Segment default. A new
+// session_id is minted once the gap since the last tracked event exceeds this.
+export const SESSION_TIMEOUT_MS = 30 * 60 * 1000;

package/src/constants/storage.ts

@@ -5,6 +5,13 @@ export const STORAGE_PREFIX = "formo_rn_";
 export const LOCAL_ANONYMOUS_ID_KEY = "anonymous_id";
 export const LOCAL_APP_VERSION_KEY = "app_version";
 export const LOCAL_APP_BUILD_KEY = "app_build";
+// Session identifier + last-activity marker. Persisted so a session survives an
+// app restart, but expires after SESSION_TIMEOUT_MS of inactivity (see EventFactory).
+export const LOCAL_SESSION_ID_KEY = "session_id";
+export const LOCAL_SESSION_LAST_ACTIVITY_KEY = "session_last_activity";
+// One-shot flag: set once the Android Play Install Referrer attribution has
+// been fetched, so we never call the native API again.
+export const LOCAL_INSTALL_REFERRER_RESOLVED_KEY = "install_referrer_resolved";
 
 // Session storage keys (cleared on app restart)
 export const SESSION_USER_ID_KEY = "user_id";

package/src/lib/event/EventFactory.ts

@@ -25,7 +25,15 @@ try {
 } catch {
   // Not available
 }
-import { COUNTRY_LIST, LOCAL_ANONYMOUS_ID_KEY, CHANNEL, VERSION } from "../../constants";
+import {
+  COUNTRY_LIST,
+  LOCAL_ANONYMOUS_ID_KEY,
+  LOCAL_SESSION_ID_KEY,
+  LOCAL_SESSION_LAST_ACTIVITY_KEY,
+  SESSION_TIMEOUT_MS,
+  CHANNEL,
+  VERSION,
+} from "../../constants";
 import {
   Address,
   APIEvent,
@@ -39,8 +47,7 @@ import {
   TransactionStatus,
 } from "../../types";
 import {
-  toChecksumAddress,
-  getValidAddress,
+  validateAddress,
   toSnakeCase,
   mergeDeepRight,
   getStoredTrafficSource,
@@ -66,6 +73,73 @@ function generateAnonymousId(key: string): string {
   return newId;
 }
 
+/**
+ * Get the current session id, or start a new one.
+ *
+ * A session persists across app restarts but expires after SESSION_TIMEOUT_MS of
+ * inactivity, at which point a fresh id is minted. Every call refreshes the
+ * last-activity marker.
+ *
+ * The mobile SDK owns its session_id rather than letting ingestion derive one.
+ * The events-gateway authorizer computes
+ * `hash(dailySalt + domain + sourceIp + userAgent)` — a design built for the
+ * web, where all three inputs carry real entropy. For a native app they all
+ * degenerate at once: there is no Origin header (so `domain` is the constant
+ * "unknown"), the HTTP User-Agent is the client library's (`okhttp/…`,
+ * `CFNetwork/… Darwin/…`) and is near-identical across users on the same app
+ * build, and carrier CGNAT puts many users behind one IP — so unrelated users
+ * collapse into a single session. Ingestion honours a body-provided session_id
+ * (`obj?.session_id || session_id` in handlerV0), which is the path used here.
+ */
+export function getSessionId(): string {
+  const now = Date.now();
+  const existingId = storage().get(LOCAL_SESSION_ID_KEY);
+  const lastActivityRaw = storage().get(LOCAL_SESSION_LAST_ACTIVITY_KEY);
+  const lastActivity = lastActivityRaw ? parseInt(lastActivityRaw, 10) : 0;
+
+  const isExpired =
+    !existingId || !lastActivity || now - lastActivity > SESSION_TIMEOUT_MS;
+  const sessionId = isExpired ? generateUUID() : existingId;
+
+  storage().set(LOCAL_SESSION_ID_KEY, sessionId);
+  storage().set(LOCAL_SESSION_LAST_ACTIVITY_KEY, String(now));
+
+  return sessionId;
+}
+
+/**
+ * Build a representative User-Agent string from structured device info.
+ *
+ * The ingestion pipeline classifies device / os / browser purely from the
+ * user_agent string; a mobile event with an empty UA is bucketed as "unknown".
+ * Platforms without a native UA (e.g. Expo, where DeviceInfo.getUserAgent() is
+ * unavailable) would otherwise report device=os=unknown. We synthesize a UA
+ * containing the tokens the classifier keys off (iphone/ipad/android + version)
+ * so mobile device and OS resolve correctly. Returns "" for unknown platforms.
+ */
+export function synthesizeUserAgent(info: {
+  os_name: string;
+  os_version: string;
+  device_model: string;
+  device_type: string;
+}): string {
+  const os = (info.os_name || "").toLowerCase();
+  const version = info.os_version || "";
+  const model = info.device_model || "";
+  const isTablet = info.device_type === "tablet";
+
+  if (os === "ios" || os === "ipados") {
+    const device = isTablet ? "iPad" : "iPhone";
+    const osVersion = version.replace(/\./g, "_");
+    return `Mozilla/5.0 (${device}; CPU ${device} OS ${osVersion} like Mac OS X) FormoAnalytics/ReactNative`;
+  }
+  if (os === "android") {
+    const formFactor = isTablet ? "Tablet" : "Mobile";
+    return `Mozilla/5.0 (Linux; Android ${version}; ${model}) ${formFactor} FormoAnalytics/ReactNative`;
+  }
+  return "";
+}
+
 /**
  * Event factory for React Native
  * Creates event payloads with mobile-specific context
@@ -219,14 +293,24 @@ class EventFactory implements IEventFactory {
           DeviceInfo.isTablet(),
         ]);
 
+        const device_type = isTablet ? "tablet" : "mobile";
+        const os_version = DeviceInfo.getSystemVersion();
         return {
           os_name: Platform.OS,
-          os_version: DeviceInfo.getSystemVersion(),
+          os_version,
           device_model: model,
           device_manufacturer: manufacturer,
           device_name: deviceName,
-          device_type: isTablet ? "tablet" : "mobile",
-          user_agent: userAgent,
+          device_type,
+          // Prefer the native UA; fall back to a synthesized one if unavailable.
+          user_agent:
+            userAgent ||
+            synthesizeUserAgent({
+              os_name: Platform.OS,
+              os_version,
+              device_model: model,
+              device_type,
+            }),
           app_name: DeviceInfo.getApplicationName(),
           app_version: DeviceInfo.getVersion(),
           app_build: DeviceInfo.getBuildNumber(),
@@ -241,14 +325,25 @@ class EventFactory implements IEventFactory {
     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";
         return {
-          os_name: ExpoDevice?.osName || Platform.OS,
-          os_version: ExpoDevice?.osVersion || String(Platform.Version),
-          device_model: ExpoDevice?.modelName || "Unknown",
+          os_name,
+          os_version,
+          device_model,
           device_manufacturer: ExpoDevice?.manufacturer || "Unknown",
           device_name: ExpoDevice?.deviceName || "Unknown Device",
-          device_type: isTablet ? "tablet" : "mobile",
-          user_agent: "",
+          device_type,
+          // Expo exposes no native UA; synthesize one so the pipeline can
+          // classify device/os (both are derived from the UA string).
+          user_agent: synthesizeUserAgent({
+            os_name,
+            os_version,
+            device_model,
+            device_type,
+          }),
           app_name: ExpoApplication?.applicationName || "",
           app_version: ExpoApplication?.nativeApplicationVersion || "",
           app_build: ExpoApplication?.nativeBuildVersion || "",
@@ -261,14 +356,21 @@ class EventFactory implements IEventFactory {
 
     // Final fallback - minimal info from Platform
     logger.debug("No device info modules available, using Platform defaults");
+    const os_name = Platform.OS;
+    const os_version = String(Platform.Version);
     return {
-      os_name: Platform.OS,
-      os_version: String(Platform.Version),
+      os_name,
+      os_version,
       device_model: "Unknown",
       device_manufacturer: "Unknown",
       device_name: "Unknown Device",
       device_type: "mobile",
-      user_agent: "",
+      user_agent: synthesizeUserAgent({
+        os_name,
+        os_version,
+        device_model: "Unknown",
+        device_type: "mobile",
+      }),
       app_name: "",
       app_version: "",
       app_build: "",
@@ -335,14 +437,14 @@ class EventFactory implements IEventFactory {
     };
 
     commonEventData.anonymous_id = generateAnonymousId(LOCAL_ANONYMOUS_ID_KEY);
+    commonEventData.session_id = getSessionId();
 
     // Handle address - convert undefined to null for consistency
-    const validAddress = getValidAddress(formoEvent.address);
-    if (validAddress) {
-      commonEventData.address = toChecksumAddress(validAddress);
-    } else {
-      commonEventData.address = null;
-    }
+    // Try EVM first, then Solana fallback (chainId is not always present here).
+    const validAddress = formoEvent.address
+      ? validateAddress(formoEvent.address)
+      : undefined;
+    commonEventData.address = validAddress ?? null;
 
     const processedEvent = mergeDeepRight(
       formoEvent as Record<string, unknown>,
@@ -385,8 +487,12 @@ class EventFactory implements IEventFactory {
   ): Promise<IFormoEvent> {
     const props = { ...(properties ?? {}), name, ...(category && { category }) };
 
-    // Map screen name to page-equivalent context fields for Tinybird compatibility.
-    // page_path is omitted — Tinybird derives it from page_url via path().
+    // 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).
     // User-supplied context values take precedence (spread last).
     const screenContext: IFormoEventContext = {
       page_title: name,
@@ -501,7 +607,6 @@ class EventFactory implements IEventFactory {
     chainId: ChainID | undefined,
     address: Address,
     message: string,
-    signatureHash?: string,
     properties?: IFormoEventProperties,
     context?: IFormoEventContext
   ): Promise<IFormoEvent> {
@@ -510,7 +615,6 @@ class EventFactory implements IEventFactory {
         status,
         ...(chainId !== undefined && chainId !== null && { chainId }),
         message,
-        ...(signatureHash && { signatureHash }),
         ...properties,
       },
       address,
@@ -648,7 +752,6 @@ class EventFactory implements IEventFactory {
           event.chainId,
           event.address,
           event.message,
-          event.signatureHash,
           event.properties,
           event.context
         );
@@ -680,10 +783,7 @@ class EventFactory implements IEventFactory {
 
     // Set address if not already set by the specific event generator
     if (formoEvent.address === undefined || formoEvent.address === null) {
-      const validAddress = getValidAddress(address);
-      formoEvent.address = validAddress
-        ? toChecksumAddress(validAddress)
-        : null;
+      formoEvent.address = address ? validateAddress(address) ?? null : null;
     }
     formoEvent.user_id = userId || null;