@formo/analytics-react-native 0.1.4 → 0.1.6

package/src/FormoAnalytics.ts

@@ -35,8 +35,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 +46,7 @@ export class FormoAnalytics implements IFormoAnalytics {
   private eventQueue: EventQueue;
   private wagmiHandler?: WagmiEventHandler;
   private lifecycleManager?: AppLifecycleManager;
+  private linkingSubscription?: EmitterSubscription;
 
   config: Config;
   currentChainId?: ChainID;
@@ -128,6 +131,32 @@ 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 context.
+    //
+    // Deep-link initial URL is awaited because Linking.getInitialURL() is a
+    // fast native bridge call and we need its result before lifecycle events
+    // fire. The url-event subscription is set up synchronously for runtime
+    // deep links. Install-referrer capture (Play / AdServices) is fire-and-
+    // forget since it involves potentially-slow network I/O on iOS and is
+    // best-effort; it'll still populate attribution for subsequent events.
+    if (analytics.isAttributionEnabled("deeplinks")) {
+      try {
+        await analytics.startDeepLinkCapture();
+      } catch (error) {
+        logger.error("FormoAnalytics: Failed to initialize deep link capture", error);
+      }
+    }
+
+    if (analytics.isAttributionEnabled("installReferrer")) {
+      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 +176,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 +243,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);
   }
 
@@ -220,6 +271,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 +306,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 +315,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 +401,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 +422,6 @@ export class FormoAnalytics implements IFormoAnalytics {
         ...(chainId !== undefined && chainId !== null && { chainId }),
         address,
         message,
-        ...(signatureHash && { signatureHash }),
       },
       properties,
       context,
@@ -458,6 +511,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 +621,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 +654,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 +759,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/storage.ts

@@ -5,6 +5,9 @@ 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";
+// One-shot flag: set once the Install Referrer (Android) or AdServices (iOS)
+// 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

@@ -39,8 +39,7 @@ import {
   TransactionStatus,
 } from "../../types";
 import {
-  toChecksumAddress,
-  getValidAddress,
+  validateAddress,
   toSnakeCase,
   mergeDeepRight,
   getStoredTrafficSource,
@@ -337,12 +336,11 @@ class EventFactory implements IEventFactory {
     commonEventData.anonymous_id = generateAnonymousId(LOCAL_ANONYMOUS_ID_KEY);
 
     // 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>,
@@ -501,7 +499,6 @@ class EventFactory implements IEventFactory {
     chainId: ChainID | undefined,
     address: Address,
     message: string,
-    signatureHash?: string,
     properties?: IFormoEventProperties,
     context?: IFormoEventContext
   ): Promise<IFormoEvent> {
@@ -510,7 +507,6 @@ class EventFactory implements IEventFactory {
         status,
         ...(chainId !== undefined && chainId !== null && { chainId }),
         message,
-        ...(signatureHash && { signatureHash }),
         ...properties,
       },
       address,
@@ -648,7 +644,6 @@ class EventFactory implements IEventFactory {
           event.chainId,
           event.address,
           event.message,
-          event.signatureHash,
           event.properties,
           event.context
         );
@@ -680,10 +675,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;
 

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,262 @@
+/**
+ * Install Referrer / attribution capture
+ *
+ * Populates the existing traffic source fields (utm_source, utm_medium,
+ * utm_campaign, utm_term, utm_content, ref, referrer) from platform install
+ * attribution APIs on first launch:
+ *
+ * - Android: Google Play Install Referrer API via react-native-play-install-referrer
+ *   (optional peer dep). Returns a URL-encoded query string like
+ *   "utm_source=google&utm_campaign=spring_sale&..." which we parse with
+ *   parseTrafficSource.
+ *
+ * - iOS: AdServices attribution via react-native-ad-services-attribution
+ *   (optional peer dep). Returns an attribution token which we exchange with
+ *   Apple's AdServices endpoint; the response is mapped onto utm_* fields.
+ *
+ * Both native modules are lazy-required and the capture silently no-ops when
+ * they are 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; Apple only within ~24h of install).
+ */
+
+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 optional native modules. 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.
+}
+
+let AdServicesAttribution: {
+  getAttributionToken: () => Promise<string | null>;
+} | null = null;
+
+try {
+  const mod = require("react-native-ad-services-attribution");
+  AdServicesAttribution = mod.default ?? mod;
+} catch {
+  // Not installed — iOS AdServices capture will no-op.
+}
+
+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 if (Platform.OS === "ios") {
+      didResolve = await captureIOSAttribution();
+    } else {
+      logger.debug(
+        `InstallReferrer: unsupported platform ${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) {
+    logger.debug(
+      "InstallReferrer: react-native-play-install-referrer not installed, skipping Android capture"
+    );
+    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).
+  const result = await new Promise<{
+    ok: boolean;
+    info: { installReferrer?: string } | null;
+  }>((resolve) => {
+    try {
+      PlayInstallReferrer!.getInstallReferrerInfo((info, error) => {
+        if (error) {
+          logger.debug("InstallReferrer: Play API error", error);
+          resolve({ ok: false, info: null });
+          return;
+        }
+        resolve({ ok: true, info: info ?? null });
+      });
+    } catch (e) {
+      logger.debug("InstallReferrer: Play API threw", e);
+      resolve({ 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;
+}
+
+/**
+ * iOS: fetch AdServices attribution token and exchange it with Apple for
+ * campaign metadata. Map campaignId/adGroupId/keywordId onto utm_* fields.
+ * Falls back to no-op if the native module isn't present.
+ */
+async function captureIOSAttribution(): Promise<boolean> {
+  if (!AdServicesAttribution) {
+    logger.debug(
+      "InstallReferrer: react-native-ad-services-attribution not installed, skipping iOS capture"
+    );
+    return false;
+  }
+
+  let token: string | null;
+  try {
+    token = await AdServicesAttribution.getAttributionToken();
+  } catch (e) {
+    logger.debug("InstallReferrer: failed to get AdServices token", e);
+    return false;
+  }
+  if (!token) return false;
+
+  let data: Record<string, unknown> | null = null;
+  // Guard against poor-network hangs — this runs fire-and-forget during init.
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 10000);
+  try {
+    const response = await fetch("https://api-adservices.apple.com/api/v1/", {
+      method: "POST",
+      headers: { "Content-Type": "text/plain" },
+      body: token,
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      // 4xx are permanent (400 = bad/consumed token, 404 = past Apple's ~24h
+      // attribution window). Mark resolved so we stop retrying. 5xx and
+      // other transient failures return false so we re-attempt next launch.
+      const permanent = response.status >= 400 && response.status < 500;
+      logger.debug(
+        `InstallReferrer: AdServices returned ${response.status}, ${
+          permanent ? "permanent — marking resolved" : "transient — will retry"
+        }`
+      );
+      return permanent;
+    }
+    data = (await response.json()) as Record<string, unknown>;
+  } catch (e) {
+    // Network / abort / parse errors — treat as transient.
+    logger.debug("InstallReferrer: AdServices exchange failed", e);
+    return false;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+
+  if (!data || data.attribution === false) {
+    // Organic install
+    return true;
+  }
+
+  const toStr = (v: unknown): string | undefined =>
+    v === undefined || v === null ? undefined : String(v);
+
+  const attributed: Partial<ITrafficSource> = {
+    utm_source: "apple_search_ads",
+    utm_medium: "cpc",
+    ...(toStr(data.campaignId) && { utm_campaign: toStr(data.campaignId)! }),
+    ...(toStr(data.adGroupId) && { utm_content: toStr(data.adGroupId)! }),
+    ...(toStr(data.keywordId) && { utm_term: toStr(data.keywordId)! }),
+  };
+
+  mergeTrafficSourceFill(attributed);
+  logger.info("InstallReferrer: captured iOS AdServices attribution");
+  return true;
+}

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);
       });