@formo/analytics-react-native 0.1.4 → 1.0.0

package/src/lib/event/EventQueue.ts

@@ -168,6 +168,20 @@ export class EventQueue implements IEventQueue {
       `Event enqueued: ${getActionDescriptor(event.type, event.properties)}`
     );
 
+    // Per-event detail line for debugging (only prints when debug logging is on).
+    const ctx = (event.context ?? {}) as Record<string, unknown>;
+    logger.debug(
+      "Event detail:",
+      JSON.stringify({
+        type: event.type,
+        event: event.event,
+        session_id: event.session_id,
+        anonymous_id: event.anonymous_id,
+        user_agent: ctx.user_agent,
+        page_url: ctx.page_url,
+      })
+    );
+
     const hasReachedFlushAt = this.queue.length >= this.flushAt;
     const hasReachedQueueSize =
       this.queue.reduce(

package/src/lib/event/types.ts

@@ -66,7 +66,6 @@ export interface IEventFactory {
     chainId: ChainID | undefined,
     address: Address,
     message: string,
-    signatureHash?: string,
     properties?: IFormoEventProperties,
     context?: IFormoEventContext
   ): Promise<IFormoEvent>;

package/src/lib/installReferrer/index.ts

@@ -0,0 +1,225 @@
+/**
+ * Install Referrer / attribution capture (Android)
+ *
+ * Populates the existing traffic source fields (utm_source, utm_medium,
+ * utm_campaign, utm_term, utm_content, ref, referrer) from the Google Play
+ * Install Referrer on first launch. This is what enables web-to-mobile
+ * attribution: a user who tapped a link on example.com before installing shows
+ * up with that referrer on their first events (see P-2207).
+ *
+ * - Android: Google Play Install Referrer API via react-native-play-install-referrer
+ *   (optional peer dep). Returns a URL-encoded query string like
+ *   "utm_source=example.com&utm_campaign=spring_sale&..." which we parse with
+ *   parseTrafficSource.
+ *
+ * - iOS: NOT supported. Apple exposes no install-referrer API, so an install
+ *   cannot be attributed to a referring website from the SDK. Doing so requires
+ *   a third-party attribution service (Branch/AppsFlyer) or fingerprint
+ *   matching — out of scope. On iOS this capture is a no-op.
+ *
+ * The native module is lazy-required and capture silently no-ops when it is not
+ * installed (keeps Expo Go and minimal integrations working).
+ *
+ * Result is merged with mergeTrafficSourceFill so a deep link that arrived
+ * via Linking.getInitialURL() takes precedence over install-referrer data.
+ *
+ * The resolution is one-shot: on success we set LOCAL_INSTALL_REFERRER_RESOLVED_KEY
+ * so we never call the native API again (Play returns meaningful data only on
+ * the first fetch).
+ */
+
+import { Platform } from "react-native";
+import { logger } from "../logger";
+import { storage, getStorageManager } from "../storage";
+import { LOCAL_INSTALL_REFERRER_RESOLVED_KEY } from "../../constants/storage";
+import {
+  parseTrafficSource,
+  mergeTrafficSourceFill,
+} from "../../utils/trafficSource";
+import type { ITrafficSource } from "../../types";
+
+// Lazy-load the optional native module. Absence is fine — attribution is best-effort.
+let PlayInstallReferrer: {
+  getInstallReferrerInfo: (
+    cb: (info: { installReferrer?: string } | null, error?: unknown) => void
+  ) => void;
+} | null = null;
+
+try {
+  PlayInstallReferrer = require("react-native-play-install-referrer")
+    .PlayInstallReferrer;
+} catch {
+  // Not installed — Android install referrer capture will no-op.
+}
+
+/**
+ * Upper bound on the Play Install Referrer native call.
+ *
+ * SDK init awaits this capture so the referrer is available for the
+ * Application Installed event, which means it must never block init
+ * indefinitely (a stalled Play Store service connection can leave the callback
+ * pending forever). Until init resolves the provider serves its no-op context,
+ * so any delay here is a window where startup events are dropped.
+ *
+ * That cost is paid on the FIRST launch only: the capture is one-shot, and
+ * every later launch short-circuits on LOCAL_INSTALL_REFERRER_RESOLVED_KEY
+ * before reaching the native call. The bind is normally sub-second, so this is
+ * kept tight rather than generous — on timeout we skip and retry next launch.
+ */
+const INSTALL_REFERRER_TIMEOUT_MS = 1500;
+
+export interface CaptureOptions {
+  customRefParams?: string[];
+  pathPattern?: string;
+}
+
+/**
+ * Capture install-time attribution and merge into the stored traffic source.
+ * One-shot: returns immediately if already resolved on a previous launch.
+ */
+export async function captureInstallReferrer(
+  options: CaptureOptions = {}
+): Promise<void> {
+  try {
+    // The one-shot flag is only useful if it can persist across launches.
+    // Without AsyncStorage (MemoryStorage fallback) the flag is lost every
+    // restart, so we'd re-hit the native API every cold start. Mirror the
+    // lifecycle manager's guard and skip capture entirely in that case.
+    const hasPersistentStorage =
+      getStorageManager()?.hasPersistentStorage() ?? false;
+    if (!hasPersistentStorage) {
+      logger.debug(
+        "InstallReferrer: persistent storage unavailable, skipping capture"
+      );
+      return;
+    }
+
+    const resolved = storage().get(LOCAL_INSTALL_REFERRER_RESOLVED_KEY);
+    if (resolved === "true") {
+      logger.debug("InstallReferrer: already resolved, skipping");
+      return;
+    }
+
+    let didResolve = false;
+
+    if (Platform.OS === "android") {
+      didResolve = await captureAndroidReferrer(options);
+    } else {
+      // iOS (and any non-Android platform): no OS-level install referrer exists.
+      // Attributing an install to a referring website requires a third-party
+      // attribution SDK (Branch/AppsFlyer) or fingerprint matching. No-op.
+      logger.debug(
+        `InstallReferrer: no install-referrer source on ${Platform.OS}, skipping`
+      );
+      return;
+    }
+
+    if (didResolve) {
+      await storage().setAsync(LOCAL_INSTALL_REFERRER_RESOLVED_KEY, "true");
+    }
+  } catch (error) {
+    // Never let attribution failures break SDK init.
+    logger.debug("InstallReferrer: capture failed", error);
+  }
+}
+
+/**
+ * Android: call Play Install Referrer API once, parse the returned UTM query
+ * string, fill in any empty traffic-source fields.
+ */
+async function captureAndroidReferrer(
+  options: CaptureOptions
+): Promise<boolean> {
+  if (!PlayInstallReferrer) {
+    // Warn (not debug) on Android: attribution silently does nothing here, and
+    // marking the peer optional suppresses the missing-peer install warning, so
+    // this is the only actionable signal the integrator gets.
+    logger.warn(
+      "InstallReferrer: react-native-play-install-referrer is not installed — " +
+        "Android install attribution is disabled. Install it and rebuild the " +
+        "native app to enable web-to-mobile attribution."
+    );
+    return false;
+  }
+
+  // Distinguish "native API errored" (retry next launch) from "native API
+  // succeeded but no referrer data" (organic install — mark resolved so we
+  // don't re-call every launch).
+  //
+  // The native callback is bounded by a timeout: a stalled Play Store service
+  // connection would otherwise leave this promise pending forever, and since
+  // init() awaits this, that would hang SDK initialization and leave every
+  // consumer on the no-op context. On timeout we resolve as "errored" so the
+  // capture is retried on the next launch.
+  const result = await new Promise<{
+    ok: boolean;
+    info: { installReferrer?: string } | null;
+  }>((resolve) => {
+    let settled = false;
+    const finish = (value: {
+      ok: boolean;
+      info: { installReferrer?: string } | null;
+    }) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+
+    const timer = setTimeout(() => {
+      logger.debug(
+        `InstallReferrer: Play API did not respond within ${INSTALL_REFERRER_TIMEOUT_MS}ms, continuing`
+      );
+      finish({ ok: false, info: null });
+    }, INSTALL_REFERRER_TIMEOUT_MS);
+
+    try {
+      PlayInstallReferrer!.getInstallReferrerInfo((info, error) => {
+        if (error) {
+          logger.debug("InstallReferrer: Play API error", error);
+          finish({ ok: false, info: null });
+          return;
+        }
+        finish({ ok: true, info: info ?? null });
+      });
+    } catch (e) {
+      logger.debug("InstallReferrer: Play API threw", e);
+      finish({ ok: false, info: null });
+    }
+  });
+
+  if (!result.ok) return false; // errored — retry next launch
+
+  const referrerQuery = result.info?.installReferrer;
+  if (!referrerQuery) {
+    // Organic install (or untracked). API answered definitively — mark
+    // resolved so we don't ask Play again on every launch.
+    logger.debug("InstallReferrer: no Play referrer (organic install)");
+    return true;
+  }
+
+  // The referrer string is already URL-encoded UTM params, e.g.
+  //   "utm_source=google&utm_medium=cpc&utm_campaign=spring&utm_term=kw&utm_content=ad1"
+  // Wrap in a dummy URL so parseTrafficSource can read it.
+  const parsed = parseTrafficSource(
+    `https://play.google.com/store/apps?${referrerQuery}`,
+    options.customRefParams,
+    options.pathPattern
+  );
+
+  // Don't let the dummy play.google.com URL overwrite a real referrer — clear
+  // referrer if it's the synthetic one and no deep link was present.
+  const toMerge: Partial<ITrafficSource> = { ...parsed };
+  if (
+    toMerge.referrer &&
+    toMerge.referrer.startsWith("https://play.google.com/store/apps?")
+  ) {
+    // Preserve the raw referrer query as-is, useful for debugging campaigns
+    // that use non-UTM keys.
+    toMerge.referrer = referrerQuery;
+  }
+
+  mergeTrafficSourceFill(toMerge);
+  logger.info("InstallReferrer: captured Android install referrer");
+  return true;
+}

package/src/lib/lifecycle/index.ts

@@ -17,6 +17,7 @@ import {
   LOCAL_APP_VERSION_KEY,
   LOCAL_APP_BUILD_KEY,
 } from "../../constants/storage";
+import { getStoredTrafficSource } from "../../utils/trafficSource";
 
 /** Interface for the analytics instance to avoid circular deps */
 interface IAnalyticsInstance {
@@ -141,11 +142,19 @@ export class AppLifecycleManager {
     const { version, build } = this.appVersionInfo;
 
     if (previousVersion === null && previousBuild === null) {
-      // No stored version — first install
+      // No stored version — first install. Attach the captured web-to-mobile
+      // attribution (Android Play Install Referrer / deep link) so the install
+      // event reports where the user came from, e.g. referrer=example.com.
+      // Only non-empty fields are included to keep properties clean.
+      const trafficSource = getStoredTrafficSource() ?? {};
+      const attribution = Object.fromEntries(
+        Object.entries(trafficSource).filter(([, value]) => Boolean(value))
+      );
       logger.info("AppLifecycleManager: Application Installed");
       await this.analytics.track("Application Installed", {
         version,
         build,
+        ...attribution,
       });
     } else if (previousVersion !== version || previousBuild !== build) {
       // Version or build changed — update

package/src/lib/wagmi/WagmiEventHandler.ts

@@ -33,7 +33,6 @@ interface IFormoAnalyticsInstance {
     chainId: number;
     address: string;
     message: string;
-    signatureHash?: string;
   }): Promise<void>;
   transaction(params: {
     status: TransactionStatus;
@@ -362,13 +361,11 @@ export class WagmiEventHandler {
 
     try {
       let status: SignatureStatus;
-      let signatureHash: string | undefined;
 
       if (state.status === "pending") {
         status = SignatureStatus.REQUESTED;
       } else if (state.status === "success") {
         status = SignatureStatus.CONFIRMED;
-        signatureHash = state.data as string;
       } else if (state.status === "error") {
         status = SignatureStatus.REJECTED;
       } else {
@@ -394,7 +391,6 @@ export class WagmiEventHandler {
         chainId,
         address,
         message,
-        ...(signatureHash && { signatureHash }),
       }).catch((error) => {
         logger.error("WagmiEventHandler: Error tracking signature:", error);
       });

package/src/solana/address.ts

@@ -0,0 +1,122 @@
+/**
+ * Solana address validation utilities
+ *
+ * Solana uses Base58 encoded 32-byte public keys as addresses.
+ * Format: FDKJvWcJNe6wecbgDYDFPCfgs14aJnVsUfWQRYWLn4Tn (32-44 characters)
+ *
+ * @see https://solana.com/developers/courses/intro-to-solana/interact-with-wallets
+ */
+
+import { SolanaPublicKey } from "./types";
+
+/**
+ * Base58 alphabet used by Solana (Bitcoin alphabet)
+ */
+const BASE58_ALPHABET =
+  "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+const BASE58_CHAR_SET = new Set(BASE58_ALPHABET);
+
+const MIN_SOLANA_ADDRESS_LENGTH = 32;
+const MAX_SOLANA_ADDRESS_LENGTH = 44;
+
+/**
+ * System program addresses and other special Solana addresses
+ * These are valid addresses but may not represent user wallets
+ */
+export const SOLANA_SYSTEM_ADDRESSES = {
+  SYSTEM_PROGRAM: "11111111111111111111111111111111",
+  TOKEN_PROGRAM: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+  TOKEN_2022_PROGRAM: "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
+  ASSOCIATED_TOKEN_PROGRAM: "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
+  RENT_SYSVAR: "SysvarRent111111111111111111111111111111111",
+  CLOCK_SYSVAR: "SysvarC1ock11111111111111111111111111111111",
+} as const;
+
+function isValidBase58String(str: string): boolean {
+  for (const ch of str) {
+    if (!BASE58_CHAR_SET.has(ch)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Check if a string is a valid Solana address format
+ *
+ * Performs format validation only (length and character set). Does not
+ * verify that the address is a valid point on the Ed25519 curve.
+ */
+export function isSolanaAddress(value: unknown): value is string {
+  if (typeof value !== "string") {
+    return false;
+  }
+
+  const trimmed = value.trim();
+
+  if (
+    trimmed.length < MIN_SOLANA_ADDRESS_LENGTH ||
+    trimmed.length > MAX_SOLANA_ADDRESS_LENGTH
+  ) {
+    return false;
+  }
+
+  return isValidBase58String(trimmed);
+}
+
+/**
+ * Get a valid Solana address from a string or PublicKey
+ */
+export function getValidSolanaAddress(
+  address: string | SolanaPublicKey | null | undefined
+): string | null {
+  if (!address) {
+    return null;
+  }
+
+  if (typeof address === "object" && "toBase58" in address) {
+    try {
+      const base58 = address.toBase58();
+      return isSolanaAddress(base58) ? base58 : null;
+    } catch {
+      return null;
+    }
+  }
+
+  if (typeof address === "string") {
+    const trimmed = address.trim();
+    return isSolanaAddress(trimmed) ? trimmed : null;
+  }
+
+  return null;
+}
+
+/**
+ * Check if a Solana address is a system program or well-known program address
+ */
+export function isSolanaSystemAddress(address: string): boolean {
+  const validAddress = getValidSolanaAddress(address);
+  if (!validAddress) {
+    return false;
+  }
+
+  return Object.values(SOLANA_SYSTEM_ADDRESSES).includes(
+    validAddress as (typeof SOLANA_SYSTEM_ADDRESSES)[keyof typeof SOLANA_SYSTEM_ADDRESSES]
+  );
+}
+
+/**
+ * Check if a Solana address is blocked (should not emit events).
+ * Blocks system program addresses since they don't represent user wallets.
+ */
+export function isBlockedSolanaAddress(
+  address: string | SolanaPublicKey | null | undefined
+): boolean {
+  const validAddress = getValidSolanaAddress(address);
+  if (!validAddress) {
+    return false;
+  }
+
+  return isSolanaSystemAddress(validAddress);
+}

package/src/solana/index.ts

@@ -0,0 +1,2 @@
+export * from "./address";
+export * from "./types";

package/src/solana/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Solana-specific type definitions
+ */
+
+/**
+ * Solana cluster/network types
+ * Solana doesn't use chainId like EVM, instead it uses cluster names
+ */
+export type SolanaCluster = "mainnet-beta" | "testnet" | "devnet" | "localnet";
+
+/**
+ * Mapping of Solana clusters to numeric chain IDs for consistency with EVM events
+ * These IDs are non-standard but provide a way to identify Solana networks in our analytics
+ *
+ * Using high numbers (900000+) to avoid collision with EVM chain IDs
+ */
+export const SOLANA_CHAIN_IDS: Record<SolanaCluster, number> = {
+  "mainnet-beta": 900001,
+  testnet: 900002,
+  devnet: 900003,
+  localnet: 900004,
+} as const;
+
+/**
+ * Default Solana chain ID (mainnet-beta)
+ */
+export const DEFAULT_SOLANA_CHAIN_ID = SOLANA_CHAIN_IDS["mainnet-beta"];
+
+/**
+ * Check if a chain ID belongs to a Solana network.
+ */
+export function isSolanaChainId(chainId: number | undefined | null): boolean {
+  if (chainId === undefined || chainId === null) return false;
+  return Object.values(SOLANA_CHAIN_IDS).includes(chainId);
+}
+
+/**
+ * Solana PublicKey interface
+ * Used by address validation utilities.
+ */
+export interface SolanaPublicKey {
+  toBase58(): string;
+  toString(): string;
+  toBytes(): Uint8Array;
+  equals(other: SolanaPublicKey): boolean;
+}

package/src/types/base.ts

@@ -56,7 +56,6 @@ export interface IFormoAnalytics {
       chainId?: ChainID;
       address: Address;
       message: string;
-      signatureHash?: string;
     },
     properties?: IFormoEventProperties,
     context?: IFormoEventContext,
@@ -161,6 +160,37 @@ export interface AutocaptureOptions {
   lifecycle?: boolean;
 }
 
+/**
+ * Configuration options for attribution capture.
+ *
+ * Attribution is not an event type — it's context enrichment that decorates
+ * every tracked event with `utm_*`, `ref`, and `referrer` fields. These
+ * options control the SDK's automatic attribution data sources.
+ */
+export interface AttributionOptions {
+  /**
+   * Capture traffic source from deep links via React Native's Linking API.
+   * When enabled, the SDK calls Linking.getInitialURL() on init and subscribes
+   * to the `url` event, parsing UTM parameters and referral codes into the
+   * event context.
+   * @default true
+   */
+  deeplinks?: boolean;
+
+  /**
+   * Capture install-time attribution on first launch:
+   * - Android: Google Play Install Referrer API (requires react-native-play-install-referrer).
+   *   Enables web-to-mobile attribution, e.g. referrer=example.com.
+   * - iOS: not supported — Apple exposes no install-referrer API, so this is a no-op.
+   *
+   * Resolved once on first successful fetch and cached; subsequent launches
+   * skip the native call. Silently no-ops when the optional native module
+   * is not installed.
+   * @default true
+   */
+  installReferrer?: boolean;
+}
+
 /**
  * Configuration options for Wagmi integration
  * Allows the SDK to hook into Wagmi v2 wallet events
@@ -230,6 +260,16 @@ export interface Options {
    * @default true
    */
   autocapture?: boolean | AutocaptureOptions;
+  /**
+   * Control attribution context capture (deep links and install referrer).
+   * Attribution decorates every tracked event with `utm_*`, `ref`, and
+   * `referrer` fields — it is not itself an event type.
+   * - `false`: Disable all attribution capture
+   * - `true`: Enable all attribution sources (default)
+   * - `AttributionOptions`: Granular control over specific sources
+   * @default true
+   */
+  attribution?: boolean | AttributionOptions;
   /**
    * Wagmi integration configuration
    * When provided, the SDK will hook into Wagmi's event system

package/src/types/events.ts

@@ -5,6 +5,7 @@ export type AnonymousID = string;
 
 export interface ICommonProperties {
   anonymous_id: AnonymousID;
+  session_id: string;
   user_id: Nullable<string>;
   address: Nullable<string>;
   type: TEventType;
@@ -85,7 +86,6 @@ export interface SignatureAPIEvent {
   chainId?: ChainID;
   address: Address;
   message: string;
-  signatureHash?: string;
 }
 
 export interface ConnectAPIEvent {

package/src/utils/address.ts

@@ -1,11 +1,19 @@
 /**
  * Address validation and checksum utilities
  *
- * Uses ethereum-cryptography for proper EIP-55 checksum computation
+ * Supports both EVM and Solana addresses.
+ *
+ * Uses ethereum-cryptography for proper EIP-55 checksum computation.
  */
 
 import { keccak256 } from "ethereum-cryptography/keccak.js";
 import { utf8ToBytes } from "ethereum-cryptography/utils.js";
+import {
+  isSolanaAddress,
+  getValidSolanaAddress,
+  isBlockedSolanaAddress,
+} from "../solana/address";
+import { isSolanaChainId } from "../solana/types";
 
 /**
  * Convert Uint8Array to hex string
@@ -17,7 +25,7 @@ function toHex(bytes: Uint8Array): string {
 }
 
 /**
- * Check if a string is a valid Ethereum address
+ * Check if a string is a valid Ethereum (EVM) address
  */
 export function isValidAddress(address: string): boolean {
   if (!address) return false;
@@ -56,7 +64,7 @@ export function toChecksumAddress(address: string): string {
 }
 
 /**
- * Get valid address or null
+ * Get a valid (trimmed) EVM address, or null if invalid.
  */
 export function getValidAddress(
   address: string | undefined | null
@@ -68,7 +76,52 @@ export function getValidAddress(
 }
 
 /**
- * Blocked addresses that should not emit events
+ * Validates an EVM address and returns it in checksummed format.
+ */
+export function validateAndChecksumAddress(
+  address: string
+): string | undefined {
+  const validAddress = getValidAddress(address);
+  return validAddress ? toChecksumAddress(validAddress) : undefined;
+}
+
+/**
+ * Validates an address for both EVM and Solana chains.
+ *
+ * For EVM addresses, returns checksummed format.
+ * For Solana addresses, returns the Base58 address as-is.
+ *
+ * When chainId is explicitly provided, validation is strict:
+ * - Solana chainId → only Solana validation
+ * - Non-Solana chainId → only EVM validation
+ *
+ * When chainId is omitted, EVM is tried first with Solana fallback.
+ */
+export function validateAddress(
+  address: string,
+  chainId?: number | null
+): string | undefined {
+  // Explicit Solana chainId → validate ONLY as Solana
+  if (chainId !== undefined && chainId !== null && isSolanaChainId(chainId)) {
+    return getValidSolanaAddress(address) || undefined;
+  }
+
+  // Explicit non-Solana chainId → validate ONLY as EVM
+  if (chainId !== undefined && chainId !== null) {
+    return validateAndChecksumAddress(address);
+  }
+
+  // No chainId → try EVM first, then Solana fallback
+  const validEvmAddress = validateAndChecksumAddress(address);
+  if (validEvmAddress) {
+    return validEvmAddress;
+  }
+
+  return getValidSolanaAddress(address) || undefined;
+}
+
+/**
+ * Blocked EVM addresses that should not emit events
  * (zero address, dead address)
  */
 const BLOCKED_ADDRESSES = new Set<string>([
@@ -77,8 +130,21 @@ const BLOCKED_ADDRESSES = new Set<string>([
 ]);
 
 /**
- * Check if address is in blocked list
+ * Check if an address is in a blocked list.
+ * Handles both EVM (zero/dead addresses) and Solana (system program) blocks.
  */
 export function isBlockedAddress(address: string): boolean {
-  return BLOCKED_ADDRESSES.has(address.toLowerCase());
+  if (!address || typeof address !== "string") return false;
+
+  const trimmed = address.trim();
+
+  if (isValidAddress(trimmed)) {
+    return BLOCKED_ADDRESSES.has(trimmed.toLowerCase());
+  }
+
+  if (isSolanaAddress(trimmed)) {
+    return isBlockedSolanaAddress(trimmed);
+  }
+
+  return false;
 }