@formo/analytics-react-native 1.1.0 → 1.2.0

package/src/FormoAnalytics.ts

@@ -40,7 +40,7 @@ import {
   TransactionStatus,
 } from "./types";
 import { validateAddress } from "./utils";
-import { parseTrafficSource, updateStoredTrafficSource } from "./utils/trafficSource";
+import { clearTrafficSource, parseTrafficSource, updateStoredTrafficSource } from "./utils/trafficSource";
 import { captureInstallReferrer } from "./lib/installReferrer";
 import { Linking, EmitterSubscription } from "react-native";
 
@@ -60,6 +60,9 @@ export class FormoAnalytics implements IFormoAnalytics {
   private crashReporter?: CrashReporter;
   private initialDeepLinkUrl?: string;
   private linkingSubscription?: EmitterSubscription;
+  private walletGeneration = 0;
+  private chainGeneration = 0;
+  private consentGeneration = 0;
 
   config: Config;
   currentChainId?: ChainID;
@@ -86,7 +89,18 @@ export class FormoAnalytics implements IFormoAnalytics {
     this.detect = this.detect.bind(this);
     this.track = this.track.bind(this);
     this.screen = this.screen.bind(this);
+    this.reset = this.reset.bind(this);
+    this.cleanup = this.cleanup.bind(this);
+    this.flush = this.flush.bind(this);
+    this.setTrafficSourceFromUrl = this.setTrafficSourceFromUrl.bind(this);
+    this.optOutTracking = this.optOutTracking.bind(this);
+    this.optInTracking = this.optInTracking.bind(this);
+    this.hasOptedOutTracking = this.hasOptedOutTracking.bind(this);
+    this.pushNotificationReceived = this.pushNotificationReceived.bind(this);
+    this.pushNotificationTapped = this.pushNotificationTapped.bind(this);
+    this.pushNotificationBounced = this.pushNotificationBounced.bind(this);
     this.isAutocaptureEnabled = this.isAutocaptureEnabled.bind(this);
+    this.isAttributionEnabled = this.isAttributionEnabled.bind(this);
 
     // Initialize logger
     Logger.init({
@@ -104,10 +118,15 @@ export class FormoAnalytics implements IFormoAnalytics {
     });
 
     // Initialize event manager
-    this.eventManager = new EventManager(this.eventQueue, options);
+    this.eventManager = new EventManager(
+      this.eventQueue,
+      options,
+      () => !this.hasOptedOutTracking()
+    );
 
     // Check consent status
     if (this.hasOptedOutTracking()) {
+      clearTrafficSource();
       logger.info("User has previously opted out of tracking");
     }
 
@@ -172,9 +191,13 @@ export class FormoAnalytics implements IFormoAnalytics {
 
     if (analytics.isAttributionEnabled("installReferrer")) {
       try {
+        const consentGeneration = analytics.consentGeneration;
         await captureInstallReferrer({
           customRefParams: analytics.options.referral?.queryParams,
           pathPattern: analytics.options.referral?.pathPattern,
+          canCapture: () =>
+            analytics.consentGeneration === consentGeneration &&
+            !analytics.hasOptedOutTracking(),
         });
       } catch (error) {
         logger.debug("FormoAnalytics: install referrer capture failed", error);
@@ -226,9 +249,14 @@ export class FormoAnalytics implements IFormoAnalytics {
    * so attribution is in storage before the first lifecycle event fires.
    */
   private async startDeepLinkCapture(): Promise<void> {
+    const consentGeneration = this.consentGeneration;
     try {
       const url = await Linking.getInitialURL();
-      if (url) {
+      if (
+        url &&
+        this.consentGeneration === consentGeneration &&
+        !this.hasOptedOutTracking()
+      ) {
         if (this.isAttributionEnabled("deeplinks")) {
           this.setTrafficSourceFromUrl(url);
         }
@@ -243,7 +271,7 @@ export class FormoAnalytics implements IFormoAnalytics {
 
     // Runtime deep links (foreground opens, universal links).
     this.linkingSubscription = Linking.addEventListener("url", (event) => {
-      if (!event?.url) return;
+      if (!event?.url || this.hasOptedOutTracking()) return;
       // Each behaviour checks its own flag: the hook may exist because only one
       // of them is enabled.
       if (this.isAttributionEnabled("deeplinks")) {
@@ -367,6 +395,7 @@ export class FormoAnalytics implements IFormoAnalytics {
    * ```
    */
   public setTrafficSourceFromUrl(url: string): void {
+    if (this.hasOptedOutTracking()) return;
     const trafficSource = parseTrafficSource(
       url,
       this.options.referral?.queryParams,
@@ -379,12 +408,14 @@ export class FormoAnalytics implements IFormoAnalytics {
     logger.debug("Traffic source set from URL:", trafficSource);
   }
 
-  /**
-   * Reset the current user session
-   */
+  /** Reset user and wallet state, preserving device identity and attribution. */
   public reset(): void {
+    this.walletGeneration++;
+    this.chainGeneration++;
     this.currentUserId = undefined;
-    storage().remove(LOCAL_ANONYMOUS_ID_KEY);
+    this.currentAddress = undefined;
+    this.currentChainId = undefined;
+    this.wagmiHandler?.clearIdentity();
     storage().remove(LOCAL_SESSION_ID_KEY);
     storage().remove(LOCAL_SESSION_LAST_ACTIVITY_KEY);
     storage().remove(SESSION_USER_ID_KEY);
@@ -447,6 +478,9 @@ export class FormoAnalytics implements IFormoAnalytics {
       logger.warn(`Connect: Invalid address provided ("${address}")`);
       return;
     }
+    if (this.hasOptedOutTracking()) return;
+    const walletGeneration = ++this.walletGeneration;
+    const chainGeneration = ++this.chainGeneration;
 
     // Track event before updating state so connect events TO excluded chains are tracked
     await this.trackEvent(
@@ -457,8 +491,14 @@ export class FormoAnalytics implements IFormoAnalytics {
       callback
     );
 
-    this.currentChainId = chainId;
-    this.currentAddress = validatedAddress;
+    if (!this.hasOptedOutTracking()) {
+      if (walletGeneration === this.walletGeneration) {
+        this.currentAddress = validatedAddress;
+      }
+      if (chainGeneration === this.chainGeneration) {
+        this.currentChainId = chainId;
+      }
+    }
   }
 
   /**
@@ -470,6 +510,8 @@ export class FormoAnalytics implements IFormoAnalytics {
     context?: IFormoEventContext,
     callback?: (...args: unknown[]) => void
   ): Promise<void> {
+    const walletGeneration = ++this.walletGeneration;
+    const chainGeneration = ++this.chainGeneration;
     const chainId = params?.chainId || this.currentChainId;
     const address = params?.address || this.currentAddress;
 
@@ -489,8 +531,8 @@ export class FormoAnalytics implements IFormoAnalytics {
       callback
     );
 
-    this.currentAddress = undefined;
-    this.currentChainId = undefined;
+    if (walletGeneration === this.walletGeneration) this.currentAddress = undefined;
+    if (chainGeneration === this.chainGeneration) this.currentChainId = undefined;
   }
 
   /**
@@ -510,22 +552,37 @@ export class FormoAnalytics implements IFormoAnalytics {
       logger.warn("FormoAnalytics::chain: chainId must be a valid number");
       return;
     }
-    if (!address && !this.currentAddress) {
-      logger.warn("FormoAnalytics::chain: address was empty and no previous address recorded");
+    const validAddress = address
+      ? this.validateAndChecksumAddress(address, chainId)
+      : this.currentAddress;
+    if (!validAddress) {
+      logger.warn("FormoAnalytics::chain: address is invalid or unavailable");
       return;
     }
+    if (this.hasOptedOutTracking()) return;
+    const walletGeneration = address
+      ? ++this.walletGeneration
+      : this.walletGeneration;
+    const chainGeneration = ++this.chainGeneration;
 
     // Track event before updating currentChainId so shouldTrack uses the previous chain
     // This ensures chain change events TO excluded chains are still tracked
     await this.trackEvent(
       EventType.CHAIN,
-      { chainId, address: address || this.currentAddress },
+      { chainId, address: validAddress },
       properties,
       context,
       callback
     );
 
-    this.currentChainId = chainId;
+    if (!this.hasOptedOutTracking()) {
+      if (chainGeneration === this.chainGeneration) {
+        this.currentChainId = chainId;
+      }
+      if (address && walletGeneration === this.walletGeneration) {
+        this.currentAddress = validAddress;
+      }
+    }
   }
 
   /**
@@ -638,6 +695,7 @@ export class FormoAnalytics implements IFormoAnalytics {
     try {
       const { userId, address, providerName, rdns } = params;
       logger.info("Identify", address, userId, providerName, rdns);
+      if (this.hasOptedOutTracking()) return;
 
       let validAddress: Address | undefined = undefined;
       if (address) {
@@ -646,10 +704,12 @@ export class FormoAnalytics implements IFormoAnalytics {
           logger.warn(`Identify: Invalid address provided ("${address}")`);
           return;
         }
+        this.walletGeneration++;
         this.currentAddress = validAddress;
         // Note: validateAddress returns Solana addresses unchanged (Base58, case-sensitive)
         // and EVM addresses checksummed.
       } else {
+        this.walletGeneration++;
         this.currentAddress = undefined;
       }
 
@@ -696,6 +756,7 @@ export class FormoAnalytics implements IFormoAnalytics {
     context?: IFormoEventContext,
     callback?: (...args: unknown[]) => void
   ): Promise<void> {
+    if (this.hasOptedOutTracking()) return;
     if (this.session.isWalletDetected(rdns)) {
       logger.warn(`Detect: Wallet ${providerName} already detected in this session`);
       return;
@@ -734,9 +795,14 @@ export class FormoAnalytics implements IFormoAnalytics {
    */
   public optOutTracking(): void {
     logger.info("Opting out of tracking");
+    this.consentGeneration++;
+    this.initialDeepLinkUrl = undefined;
     setConsentFlag(this.writeKey, CONSENT_OPT_OUT_KEY, "true");
     this.eventQueue.clear();
     this.reset();
+    // Consent withdrawal clears device identity and attribution too.
+    storage().remove(LOCAL_ANONYMOUS_ID_KEY);
+    clearTrafficSource();
     logger.info("Successfully opted out of tracking");
   }
 
@@ -842,7 +908,18 @@ export class FormoAnalytics implements IFormoAnalytics {
     callback?: (...args: unknown[]) => void
   ): Promise<void> {
     try {
-      if (!this.shouldTrack()) {
+      const payloadChainId = payload?.chainId as ChainID | undefined;
+      const validPayloadChainId =
+        typeof payloadChainId === "number" &&
+        Number.isFinite(payloadChainId) &&
+        payloadChainId > 0
+          ? payloadChainId
+          : undefined;
+      const eventChainId =
+        type === EventType.CONNECT || type === EventType.CHAIN
+          ? this.currentChainId
+          : validPayloadChainId;
+      if (!this.shouldTrack(eventChainId)) {
         logger.info(`Skipping ${type} event due to tracking configuration`);
         return;
       }
@@ -873,7 +950,7 @@ export class FormoAnalytics implements IFormoAnalytics {
   /**
    * Check if tracking should be enabled
    */
-  private shouldTrack(): boolean {
+  private shouldTrack(eventChainId?: ChainID): boolean {
     // Check consent
     if (this.hasOptedOutTracking()) {
       return false;
@@ -891,11 +968,13 @@ export class FormoAnalytics implements IFormoAnalytics {
       !Array.isArray(this.options.tracking)
     ) {
       const { excludeChains = [] } = this.options.tracking as TrackingOptions;
+      const chainId = eventChainId ?? this.currentChainId;
 
       if (
         excludeChains.length > 0 &&
-        this.currentChainId &&
-        excludeChains.includes(this.currentChainId)
+        chainId !== undefined &&
+        chainId !== null &&
+        excludeChains.includes(chainId)
       ) {
         return false;
       }

package/src/lib/event/EventFactory.ts

@@ -210,11 +210,13 @@ export function synthesizeUserAgent(info: {
  */
 class EventFactory implements IEventFactory {
   private options?: Options;
+  private canCreate: () => boolean;
   /** Memoised device/app identity — see getDeviceInfo(). */
   private deviceInfoPromise?: Promise<DeviceInfoResult>;
 
-  constructor(options?: Options) {
+  constructor(options?: Options, canCreate: () => boolean = () => true) {
     this.options = options;
+    this.canCreate = canCreate;
   }
 
   /**
@@ -508,6 +510,10 @@ class EventFactory implements IEventFactory {
     formoEvent: Partial<IFormoEvent>,
     context?: IFormoEventContext
   ): Promise<IFormoEvent> {
+    if (!this.canCreate()) throw EVENT_CREATION_CANCELLED;
+
+    const anonymousId = generateAnonymousId(LOCAL_ANONYMOUS_ID_KEY);
+    const sessionId = getSessionId();
     const commonEventData: Partial<IFormoEvent> = {
       context: await this.generateContext(context),
       original_timestamp: getCurrentTimeFormatted(),
@@ -517,8 +523,8 @@ class EventFactory implements IEventFactory {
       version: VERSION,
     };
 
-    commonEventData.anonymous_id = generateAnonymousId(LOCAL_ANONYMOUS_ID_KEY);
-    commonEventData.session_id = getSessionId();
+    commonEventData.anonymous_id = anonymousId;
+    commonEventData.session_id = sessionId;
 
     // Handle address - convert undefined to null for consistency
     // Try EVM first, then Solana fallback (chainId is not always present here).
@@ -886,3 +892,4 @@ class EventFactory implements IEventFactory {
 }
 
 export { EventFactory };
+export const EVENT_CREATION_CANCELLED = Symbol("event creation cancelled");

package/src/lib/event/EventManager.ts

@@ -1,6 +1,6 @@
 import { Address, APIEvent, Options } from "../../types";
 import { logger } from "../logger";
-import { EventFactory } from "./EventFactory";
+import { EVENT_CREATION_CANCELLED, EventFactory } from "./EventFactory";
 import { IEventFactory, IEventManager, IEventQueue } from "./types";
 import { isBlockedAddress } from "../../utils/address";
 
@@ -12,9 +12,13 @@ class EventManager implements IEventManager {
   eventQueue: IEventQueue;
   eventFactory: IEventFactory;
 
-  constructor(eventQueue: IEventQueue, options?: Options) {
+  constructor(
+    eventQueue: IEventQueue,
+    options?: Options,
+    canCreate: () => boolean = () => true
+  ) {
     this.eventQueue = eventQueue;
-    this.eventFactory = new EventFactory(options);
+    this.eventFactory = new EventFactory(options, canCreate);
   }
 
   /**
@@ -26,7 +30,16 @@ class EventManager implements IEventManager {
     userId?: string
   ): Promise<void> {
     const { callback, ..._event } = event;
-    const formoEvent = await this.eventFactory.create(_event, address, userId);
+    const generation = this.eventQueue.getGeneration();
+    let formoEvent;
+    try {
+      formoEvent = await this.eventFactory.create(_event, address, userId);
+    } catch (error) {
+      if (error === EVENT_CREATION_CANCELLED) return;
+      throw error;
+    }
+
+    if (this.eventQueue.getGeneration() !== generation) return;
 
     // Check if the final event has a blocked address
     if (formoEvent.address && isBlockedAddress(formoEvent.address)) {
@@ -43,7 +56,7 @@ class EventManager implements IEventManager {
         logger.info(`Events sent successfully: ${(data as unknown[])?.length ?? 0} events`);
       }
       callback?.(err, _, data);
-    });
+    }, generation);
   }
 }
 

package/src/lib/event/EventQueue.ts

@@ -210,16 +210,17 @@ export class EventQueue implements IEventQueue {
    */
   async enqueue(
     event: IFormoEvent,
-    callback?: (...args: unknown[]) => void
+    callback?: (...args: unknown[]) => void,
+    generation = this.generation
   ): Promise<void> {
     if (this.closed) {
       logger.debug("EventQueue: Ignoring event enqueued after cleanup");
       return;
     }
 
-    callback = callback || noop;
+    if (this.generation !== generation) return;
 
-    const generation = this.generation;
+    callback = callback || noop;
     const message_id = await this.generateMessageId(event);
 
     // Hashing is async, so cleanup() can complete while this call is suspended
@@ -558,6 +559,10 @@ export class EventQueue implements IEventQueue {
     logger.debug("EventQueue: Cleared all pending events");
   }
 
+  public getGeneration(): number {
+    return this.generation;
+  }
+
   /**
    * Give up on the events still queued at teardown, and make sure a send that
    * is still holding a batch cannot put them back.

package/src/lib/event/types.ts

@@ -96,9 +96,11 @@ export interface IEventManager {
 }
 
 export interface IEventQueue {
+  getGeneration(): number;
   enqueue(
     event: IFormoEvent,
-    callback?: (...args: unknown[]) => void
+    callback?: (...args: unknown[]) => void,
+    generation?: number
   ): Promise<void>;
   flush(callback?: (...args: unknown[]) => void): Promise<void>;
   clear(): void;

package/src/lib/installReferrer/index.ts

@@ -39,17 +39,23 @@ import {
 import type { ITrafficSource } from "../../types";
 
 // Lazy-load the optional native module. Absence is fine — attribution is best-effort.
-let PlayInstallReferrer: {
+type PlayInstallReferrerModule = {
   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 playInstallReferrer: PlayInstallReferrerModule | null | undefined;
+
+function getPlayInstallReferrer(): PlayInstallReferrerModule | null {
+  if (playInstallReferrer !== undefined) return playInstallReferrer;
+  try {
+    playInstallReferrer = require("react-native-play-install-referrer")
+      .PlayInstallReferrer ?? null;
+  } catch {
+    playInstallReferrer = null;
+  }
+  return playInstallReferrer ?? null;
 }
 
 /**
@@ -71,6 +77,7 @@ const INSTALL_REFERRER_TIMEOUT_MS = 1500;
 export interface CaptureOptions {
   customRefParams?: string[];
   pathPattern?: string;
+  canCapture?: () => boolean;
 }
 
 /**
@@ -81,6 +88,7 @@ export async function captureInstallReferrer(
   options: CaptureOptions = {}
 ): Promise<void> {
   try {
+    if (options.canCapture && !options.canCapture()) return;
     // 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
@@ -114,7 +122,7 @@ export async function captureInstallReferrer(
       return;
     }
 
-    if (didResolve) {
+    if (didResolve && (!options.canCapture || options.canCapture())) {
       await storage().setAsync(LOCAL_INSTALL_REFERRER_RESOLVED_KEY, "true");
     }
   } catch (error) {
@@ -130,7 +138,8 @@ export async function captureInstallReferrer(
 async function captureAndroidReferrer(
   options: CaptureOptions
 ): Promise<boolean> {
-  if (!PlayInstallReferrer) {
+  const referrer = getPlayInstallReferrer();
+  if (!referrer) {
     // 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.
@@ -174,7 +183,7 @@ async function captureAndroidReferrer(
     }, INSTALL_REFERRER_TIMEOUT_MS);
 
     try {
-      PlayInstallReferrer!.getInstallReferrerInfo((info, error) => {
+      referrer.getInstallReferrerInfo((info, error) => {
         if (error) {
           logger.debug("InstallReferrer: Play API error", error);
           finish({ ok: false, info: null });
@@ -189,6 +198,7 @@ async function captureAndroidReferrer(
   });
 
   if (!result.ok) return false; // errored — retry next launch
+  if (options.canCapture && !options.canCapture()) return false;
 
   const referrerQuery = result.info?.installReferrer;
   if (!referrerQuery) {

package/src/lib/wagmi/WagmiEventHandler.ts

@@ -46,6 +46,7 @@ interface IFormoAnalyticsInstance {
   isAutocaptureEnabled(
     eventType: "connect" | "disconnect" | "signature" | "transaction" | "chain"
   ): boolean;
+  hasOptedOutTracking(): boolean;
 }
 
 export class WagmiEventHandler {
@@ -121,6 +122,12 @@ export class WagmiEventHandler {
     status: WagmiState["status"],
     prevStatus: WagmiState["status"]
   ): Promise<void> {
+    if (this.formo.hasOptedOutTracking()) {
+      this.clearIdentity();
+      this.trackingState.lastStatus = status;
+      return;
+    }
+
     if (this.trackingState.isProcessing) {
       // Limit queue size to prevent unbounded growth during rapid status changes
       if (this.pendingStatusChanges.length >= WagmiEventHandler.MAX_PENDING_STATUS_CHANGES) {
@@ -163,6 +170,12 @@ export class WagmiEventHandler {
       const address = this.getConnectedAddress(state);
       const chainId = state.chainId;
 
+      if (this.formo.hasOptedOutTracking()) {
+        this.clearIdentity();
+        this.trackingState.lastStatus = status;
+        return;
+      }
+
       logger.info("WagmiEventHandler: Status changed", {
         status,
         prevStatus,
@@ -216,6 +229,11 @@ export class WagmiEventHandler {
     chainId: number | undefined,
     prevChainId: number | undefined
   ): Promise<void> {
+    if (this.formo.hasOptedOutTracking()) {
+      this.clearIdentity();
+      return;
+    }
+
     // Skip if no change, chainId is undefined, or this is initial connection (prevChainId undefined)
     if (chainId === prevChainId || chainId === undefined || prevChainId === undefined) {
       return;
@@ -548,6 +566,12 @@ export class WagmiEventHandler {
     return connection?.connector.id;
   }
 
+  public clearIdentity(): void {
+    this.trackingState.lastAddress = undefined;
+    this.trackingState.lastChainId = undefined;
+    this.pendingStatusChanges = [];
+  }
+
   /**
    * Clean up subscriptions
    */

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.1.0';
+export const version = '1.2.0';