@formo/analytics 1.16.7 → 1.16.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formo/analytics",
-  "version": "1.16.7",
+  "version": "1.16.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/getformo/sdk.git"
@@ -87,7 +87,7 @@
   "size-limit": [
     {
       "path": "dist/index.umd.min.js",
-      "limit": "25 KB"
+      "limit": "26 KB"
     }
   ],
   "peerDependencies": {

package/src/FormoAnalytics.ts

@@ -12,16 +12,19 @@ import {
   EventManager,
   EventQueue,
   IEventManager,
+  IStorageKeyManager,
   local,
   logger,
   Logger,
   session,
+  StorageKey,
 } from "./lib";
 import {
   Address,
   ChainID,
   Config,
   EIP1193Provider,
+  IFormoAnalytics,
   IFormoEventContext,
   IFormoEventProperties,
   Options,
@@ -32,94 +35,18 @@ import {
 } from "./types";
 import { isAddress, isLocalhost } from "./validators";
 
-interface IFormoAnalytics {
-  page(
-    category?: string,
-    name?: string,
-    properties?: IFormoEventProperties,
-    context?: IFormoEventContext,
-    callback?: (...args: unknown[]) => void
-  ): void;
-  reset(): void;
-  detect(
-    params: { rdns: string; providerName: string },
-    properties?: IFormoEventProperties,
-    context?: IFormoEventContext,
-    callback?: (...args: unknown[]) => void
-  ): Promise<void>;
-  connect(
-    params: { chainId: ChainID; address: Address },
-    properties?: IFormoEventProperties,
-    context?: IFormoEventContext,
-    callback?: (...args: unknown[]) => void
-  ): Promise<void>;
-  disconnect(
-    params?: { chainId?: ChainID; address?: Address },
-    properties?: IFormoEventProperties,
-    context?: IFormoEventContext,
-    callback?: (...args: unknown[]) => void
-  ): Promise<void>;
-  chain(
-    params: { chainId: ChainID; address?: Address },
-    properties?: IFormoEventProperties,
-    context?: IFormoEventContext,
-    callback?: (...args: unknown[]) => void
-  ): Promise<void>;
-  signature(
-    params: {
-      status: SignatureStatus;
-      chainId?: ChainID;
-      address: Address;
-      message: string;
-      signatureHash?: string;
-    },
-    properties?: IFormoEventProperties,
-    context?: IFormoEventContext,
-    callback?: (...args: unknown[]) => void
-  ): Promise<void>;
-  transaction(
-    params: {
-      status: TransactionStatus;
-      chainId: ChainID;
-      address: Address;
-      data?: string;
-      to?: string;
-      value?: string;
-      transactionHash?: string;
-    },
-    properties?: IFormoEventProperties,
-    context?: IFormoEventContext,
-    callback?: (...args: unknown[]) => void
-  ): Promise<void>;
-  identify(
-    params: {
-      address: Address;
-      providerName?: string;
-      userId?: string;
-      rdns?: string;
-    },
-    properties?: IFormoEventProperties,
-    context?: IFormoEventContext,
-    callback?: (...args: unknown[]) => void
-  ): Promise<void>;
-  track(
-    event: string,
-    properties?: IFormoEventProperties,
-    context?: IFormoEventContext,
-    callback?: (...args: unknown[]) => void
-  ): Promise<void>;
-}
-
 export class FormoAnalytics implements IFormoAnalytics {
   private _provider?: EIP1193Provider;
   private _providerListeners: Record<string, (...args: unknown[]) => void> = {};
   private session: FormoAnalyticsSession;
   private eventManager: IEventManager;
+  private storageKeyManager: IStorageKeyManager;
+  private _providers: readonly EIP6963ProviderDetail[] = [];
 
   config: Config;
   currentChainId?: ChainID;
-  currentAddress?: Address;
-  currentUserId?: string;
+  currentAddress?: Address = "";
+  currentUserId?: string = "";
 
   private constructor(
     public readonly writeKey: string,
@@ -130,9 +57,22 @@ export class FormoAnalytics implements IFormoAnalytics {
       trackLocalhost: options.trackLocalhost || false,
     };
 
-    this.session = new FormoAnalyticsSession();
+    this.storageKeyManager = new StorageKey(this.config.writeKey);
+
+    this.session = new FormoAnalyticsSession(this.storageKeyManager);
     this.currentUserId =
-      (session.get(SESSION_USER_ID_KEY) as string) || undefined;
+      (session.get(
+        this.storageKeyManager.getKey(SESSION_USER_ID_KEY)
+      ) as string) || undefined;
+
+    this.identify = this.identify.bind(this);
+    this.connect = this.connect.bind(this);
+    this.disconnect = this.disconnect.bind(this);
+    this.chain = this.chain.bind(this);
+    this.signature = this.signature.bind(this);
+    this.transaction = this.transaction.bind(this);
+    this.detect = this.detect.bind(this);
+    this.track = this.track.bind(this);
 
     // Initialize logger with configuration from options
     Logger.init({
@@ -147,7 +87,8 @@ export class FormoAnalytics implements IFormoAnalytics {
         retryCount: options.retryCount,
         maxQueueSize: options.maxQueueSize,
         flushInterval: options.flushInterval,
-      })
+      }),
+      this.storageKeyManager
     );
 
     // TODO: replace with eip6963
@@ -167,8 +108,8 @@ export class FormoAnalytics implements IFormoAnalytics {
     const analytics = new FormoAnalytics(writeKey, options);
 
     // Auto-detect wallet provider
-    const providers = await analytics.getProviders();
-    await analytics.detectWallets(providers);
+    analytics._providers = await analytics.getProviders();
+    await analytics.detectWallets(analytics._providers);
 
     return analytics;
   }
@@ -200,8 +141,8 @@ export class FormoAnalytics implements IFormoAnalytics {
    */
   public reset(): void {
     this.currentUserId = undefined;
-    local.remove(LOCAL_ANONYMOUS_ID_KEY);
-    session.remove(SESSION_USER_ID_KEY);
+    local.remove(this.storageKeyManager.getKey(LOCAL_ANONYMOUS_ID_KEY));
+    session.remove(this.storageKeyManager.getKey(SESSION_USER_ID_KEY));
   }
 
   /**
@@ -429,17 +370,17 @@ export class FormoAnalytics implements IFormoAnalytics {
 
   /**
    * Emits an identify event with current wallet address and provider info.
-   * @param {string} params.providerName
-   * @param {string} params.rdns
-   * @param {string} params.userId
    * @param {string} params.address
+   * @param {string} params.userId
+   * @param {string} params.rdns
+   * @param {string} params.providerName
    * @param {IFormoEventProperties} properties
    * @param {IFormoEventContext} context
    * @param {(...args: unknown[]) => void} callback
    * @returns {Promise<void>}
    */
-  public async identify(
-    params: {
+  async identify(
+    params?: {
       address?: Address;
       providerName?: string;
       userId?: string;
@@ -449,26 +390,52 @@ export class FormoAnalytics implements IFormoAnalytics {
     context?: IFormoEventContext,
     callback?: (...args: unknown[]) => void
   ): Promise<void> {
-    const { userId, address, providerName, rdns } = params;
+    try {
+      if (!params) { // If no params provided, auto-identify
+        for (const providerDetail of this._providers) {
+          const provider = providerDetail.provider;
+          if (!provider) continue;
+
+          try {
+            const address = await this.getAddress(provider);
+            if (address) {
+              // NOTE: do not set this.currentAddress without explicit connect or identify
+              await this.identify({
+                address,
+                providerName: providerDetail.info.name,
+                rdns: providerDetail.info.rdns,
+              }, properties, context, callback);
+            }
+          } catch (err) {
+            logger.error(`Failed to identify provider ${providerDetail.info.name}:`, err);
+          }
+        }
+        return;
+      }
 
-    this.currentAddress = address;
-    if (userId) {
-      this.currentUserId = userId;
-      session.set(SESSION_USER_ID_KEY, userId);
-    }
+      // Explicit identify
+      const { userId, address, providerName, rdns } = params;
+      if (address) this.currentAddress = address;
+      if (userId) {
+        this.currentUserId = userId;
+        session.set(this.storageKeyManager.getKey(SESSION_USER_ID_KEY), userId);
+      }
 
-    await this.trackEvent(
-      EventType.IDENTIFY,
-      {
-        address,
-        providerName,
-        userId,
-        rdns,
-      },
-      properties,
-      context,
-      callback
-    );
+      await this.trackEvent(
+        EventType.IDENTIFY,
+        {
+          address,
+          providerName,
+          userId,
+          rdns,
+        },
+        properties,
+        context,
+        callback
+      );
+    } catch (e) {
+      logger.log("identify error", e);
+    }
   }
 
   /**
@@ -734,7 +701,7 @@ export class FormoAnalytics implements IFormoAnalytics {
     };
     this.currentChainId = undefined;
     this.currentAddress = undefined;
-    session.remove(SESSION_USER_ID_KEY);
+    session.remove(this.storageKeyManager.getKey(SESSION_USER_ID_KEY));
 
     await this.trackEvent(
       EventType.DISCONNECT,
@@ -783,8 +750,14 @@ export class FormoAnalytics implements IFormoAnalytics {
   }
 
   private async trackFirstPageHit(): Promise<void> {
-    if (session.get(SESSION_CURRENT_URL_KEY) === null) {
-      session.set(SESSION_CURRENT_URL_KEY, window.location.href);
+    if (
+      session.get(this.storageKeyManager.getKey(SESSION_CURRENT_URL_KEY)) ===
+      null
+    ) {
+      session.set(
+        this.storageKeyManager.getKey(SESSION_CURRENT_URL_KEY),
+        window.location.href
+      );
     }
 
     return this.trackPageHit();
@@ -810,10 +783,15 @@ export class FormoAnalytics implements IFormoAnalytics {
   }
 
   private async onLocationChange(): Promise<void> {
-    const currentUrl = session.get(SESSION_CURRENT_URL_KEY);
+    const currentUrl = session.get(
+      this.storageKeyManager.getKey(SESSION_CURRENT_URL_KEY)
+    );
 
     if (currentUrl !== window.location.href) {
-      session.set(SESSION_CURRENT_URL_KEY, window.location.href);
+      session.set(
+        this.storageKeyManager.getKey(SESSION_CURRENT_URL_KEY),
+        window.location.href
+      );
       this.trackPageHit();
     }
   }
@@ -876,16 +854,24 @@ export class FormoAnalytics implements IFormoAnalytics {
   private async getProviders(): Promise<readonly EIP6963ProviderDetail[]> {
     const store = createStore();
     let providers = store.getProviders();
-    // TODO: consider using store.subscribe to detect changes to providers list
-    store.subscribe((providerDetails) => (providers = providerDetails));
+    store.subscribe((providerDetails) => {
+      providers = providerDetails;
+      this._providers = providers;
+    });
 
     // Fallback to injected provider if no providers are found
     if (providers.length === 0) {
-      return window?.ethereum ? [window.ethereum] : [];
+      this._providers = window?.ethereum ? [window.ethereum] : [];
+      return this._providers;
     }
+    this._providers = providers;
     return providers;
   }
 
+  get providers(): readonly EIP6963ProviderDetail[] {
+    return this._providers;
+  }
+
   private async detectWallets(
     providers: readonly EIP6963ProviderDetail[]
   ): Promise<void> {
@@ -905,15 +891,16 @@ export class FormoAnalytics implements IFormoAnalytics {
     return this._provider;
   }
 
-  private async getAddress(): Promise<Address | null> {
+  private async getAddress(provider?: EIP1193Provider): Promise<Address | null> {
     if (this.currentAddress) return this.currentAddress;
-    if (!this?.provider) {
+    const p = provider || this.provider;
+    if (!p) {
       logger.info("The provider is not set");
       return null;
     }
 
     try {
-      const accounts = await this.getAccounts();
+      const accounts = await this.getAccounts(p);
       if (accounts && accounts.length > 0) {
         if (isAddress(accounts[0])) {
           return accounts[0];
@@ -1023,16 +1010,28 @@ interface IFormoAnalyticsSession {
 }
 
 class FormoAnalyticsSession implements IFormoAnalyticsSession {
-  constructor() {}
+  private storageKeyManager: IStorageKeyManager;
+  constructor(storageKeyManager: IStorageKeyManager) {
+    this.storageKeyManager = storageKeyManager;
+  }
 
   public isWalletDetected(rdns: string): boolean {
-    const rdnses = (session.get(SESSION_WALLET_DETECTED_KEY) as string[]) || [];
+    const rdnses =
+      (session.get(
+        this.storageKeyManager.getKey(SESSION_WALLET_DETECTED_KEY)
+      ) as string[]) || [];
     return rdnses.includes(rdns);
   }
 
   public markWalletDetected(rdns: string): void {
-    const rdnses = (session.get(SESSION_WALLET_DETECTED_KEY) as string[]) || [];
+    const rdnses =
+      (session.get(
+        this.storageKeyManager.getKey(SESSION_WALLET_DETECTED_KEY)
+      ) as string[]) || [];
     rdnses.push(rdns);
-    session.set(SESSION_WALLET_DETECTED_KEY, rdnses);
+    session.set(
+      this.storageKeyManager.getKey(SESSION_WALLET_DETECTED_KEY),
+      rdnses
+    );
   }
 }

package/src/FormoAnalyticsProvider.tsx

@@ -1,11 +1,23 @@
-import { createContext, useContext, useEffect, useState, useRef } from "react";
+import { createContext, useContext, useEffect, useRef, useState } from "react";
 import { FormoAnalytics } from "./FormoAnalytics";
-import { FormoAnalyticsProviderProps } from "./types";
 import { logger } from "./lib";
+import { FormoAnalyticsProviderProps, IFormoAnalytics } from "./types";
 
-export const FormoAnalyticsContext = createContext<FormoAnalytics | undefined>(
-  undefined
-);
+const defaultContext: IFormoAnalytics = {
+  chain: () => Promise.resolve(),
+  page: () => Promise.resolve(),
+  reset: () => Promise.resolve(),
+  detect: () => Promise.resolve(),
+  connect: () => Promise.resolve(),
+  disconnect: () => Promise.resolve(),
+  signature: () => Promise.resolve(),
+  transaction: () => Promise.resolve(),
+  identify: () => Promise.resolve(),
+  track: () => Promise.resolve(),
+};
+
+export const FormoAnalyticsContext =
+  createContext<IFormoAnalytics>(defaultContext);
 
 export const FormoAnalyticsProvider = (props: FormoAnalyticsProviderProps) => {
   const { writeKey, disabled = false, children } = props;
@@ -29,7 +41,7 @@ const InitializedAnalytics = ({
   options,
   children,
 }: FormoAnalyticsProviderProps) => {
-  const [sdk, setSdk] = useState<FormoAnalytics | undefined>();
+  const [sdk, setSdk] = useState<IFormoAnalytics>(defaultContext);
   const initializedStartedRef = useRef(false);
 
   const initializeFormoAnalytics = async (writeKey: string, options: any) => {

package/src/constants/base.ts

@@ -1,13 +1,6 @@
-const STORAGE_PREFIX = "formo-";
+export const SESSION_TRAFFIC_SOURCE_KEY = "traffic-source";
+export const SESSION_WALLET_DETECTED_KEY = "wallet-detected";
+export const SESSION_CURRENT_URL_KEY = "analytics-current-url";
+export const SESSION_USER_ID_KEY = "user-id";
 
-const generateStoragePrefix = (prefix: string) => `${STORAGE_PREFIX}${prefix}`;
-
-export const SESSION_WALLET_DETECTED_KEY = generateStoragePrefix(
-  "session-wallet-detected"
-);
-export const SESSION_CURRENT_URL_KEY = generateStoragePrefix(
-  "analytics-current-url"
-);
-export const SESSION_USER_ID_KEY = generateStoragePrefix("user-id");
-
-export const LOCAL_ANONYMOUS_ID_KEY = generateStoragePrefix("anonymous-id");
+export const LOCAL_ANONYMOUS_ID_KEY = "anonymous-id";

package/src/lib/event/EventFactory.ts

@@ -1,4 +1,8 @@
-import { COUNTRY_LIST } from "../../constants";
+import {
+  COUNTRY_LIST,
+  LOCAL_ANONYMOUS_ID_KEY,
+  SESSION_TRAFFIC_SOURCE_KEY,
+} from "../../constants";
 import {
   Address,
   APIEvent,
@@ -6,6 +10,7 @@ import {
   IFormoEvent,
   IFormoEventContext,
   IFormoEventProperties,
+  ITrafficSource,
   Nullable,
   SignatureStatus,
   TransactionStatus,
@@ -20,14 +25,17 @@ import { getCurrentTimeFormatted } from "../../utils/timestamp";
 import { isUndefined } from "../../validators";
 import { logger } from "../logger";
 import mergeDeepRight from "../ramda/mergeDeepRight";
-import { local } from "../storage";
+import { IStorageKeyManager, local, session } from "../storage";
 import { version } from "../version";
 import { CHANNEL, VERSION } from "./constants";
 import { IEventFactory } from "./type";
 import { generateAnonymousId } from "./utils";
 
 class EventFactory implements IEventFactory {
-  constructor() {}
+  private storageKeyManager: IStorageKeyManager;
+  constructor(storageKeyManager: IStorageKeyManager) {
+    this.storageKeyManager = storageKeyManager;
+  }
 
   private getTimezone(): string {
     try {
@@ -68,23 +76,84 @@ class EventFactory implements IEventFactory {
   }
 
   private extractUTMParameters = (url: string): UTMParameters => {
-    const result: UTMParameters = {};
+    const result: UTMParameters = {
+      utm_campaign: "",
+      utm_content: "",
+      utm_medium: "",
+      utm_source: "",
+      utm_term: "",
+    };
     try {
       const urlObj = new URL(url);
       const UTM_PREFIX = "utm_";
       urlObj.searchParams.forEach((value, sParam) => {
         if (sParam.startsWith(UTM_PREFIX)) {
-          result[sParam] = value.trim() || "";
+          result[sParam as keyof UTMParameters] = value.trim();
         }
       });
     } catch (error) {}
     return result;
   };
 
+  private getTrafficSources = (url: string): ITrafficSource => {
+    const urlObj = new URL(url);
+    const contextTrafficSources: ITrafficSource = {
+      ...this.extractUTMParameters(url),
+      ref: urlObj.searchParams.get("ref")?.trim() || "",
+      referrer: document.referrer,
+    };
+    const storedTrafficSources =
+      (session.get(
+        this.storageKeyManager.getKey(SESSION_TRAFFIC_SOURCE_KEY)
+      ) as ITrafficSource) || {};
+
+    const finalTrafficSources: ITrafficSource = {
+      ref: contextTrafficSources.ref || storedTrafficSources?.ref || "",
+      referrer:
+        contextTrafficSources.referrer || storedTrafficSources?.referrer,
+      utm_campaign:
+        contextTrafficSources.utm_campaign ||
+        storedTrafficSources?.utm_campaign ||
+        "",
+      utm_content:
+        contextTrafficSources.utm_content ||
+        storedTrafficSources?.utm_content ||
+        "",
+      utm_medium:
+        contextTrafficSources.utm_medium ||
+        storedTrafficSources?.utm_medium ||
+        "",
+      utm_source:
+        contextTrafficSources.utm_source ||
+        storedTrafficSources?.utm_source ||
+        "",
+      utm_term:
+        contextTrafficSources.utm_term || storedTrafficSources?.utm_term || "",
+    };
+
+    // Store to session
+    const sessionStoredTrafficSources = Object.keys(finalTrafficSources).reduce(
+      (res: any, key: any) => {
+        const value = finalTrafficSources[key as keyof ITrafficSource];
+        if (!isUndefined(value) && value !== "") {
+          res[key as keyof ITrafficSource] = value;
+        }
+        return res;
+      },
+      {}
+    );
+
+    if (Object.keys(sessionStoredTrafficSources).length)
+      session.set(
+        this.storageKeyManager.getKey(SESSION_TRAFFIC_SOURCE_KEY),
+        sessionStoredTrafficSources
+      );
+
+    return finalTrafficSources;
+  };
+
   // Contextual fields that are automatically collected and populated by the Formo SDK
   private generateContext(context?: IFormoEventContext): IFormoEventContext {
-    const url = new URL(globalThis.location.href);
-    const params = new URLSearchParams(url.search);
     const path = globalThis.location.pathname;
     const language = this.getLanguage();
     const timezone = this.getTimezone();
@@ -97,12 +166,10 @@ class EventFactory implements IEventFactory {
       locale: language,
       timezone,
       location,
-      referrer: document.referrer,
-      ...this.extractUTMParameters(globalThis.location.href),
-      ref: params.get("ref")?.trim() || "",
+      ...this.getTrafficSources(globalThis.location.href),
       page_path: path,
       page_title: document.title,
-      page_url: url.href,
+      page_url: globalThis.location.href,
       library_name: "Formo Web SDK",
       library_version,
     };
@@ -156,7 +223,9 @@ class EventFactory implements IEventFactory {
     if (!local.isAvailable()) {
       commonEventData.anonymous_id = generateNativeUUID();
     } else {
-      commonEventData.anonymous_id = generateAnonymousId();
+      commonEventData.anonymous_id = generateAnonymousId(
+        this.storageKeyManager.getKey(LOCAL_ANONYMOUS_ID_KEY)
+      );
     }
 
     if (formoEvent.address) {
@@ -354,11 +423,16 @@ class EventFactory implements IEventFactory {
     const trackEvent: Partial<IFormoEvent> = {
       properties: {
         ...properties,
-        ...(properties?.revenue !== undefined && { 
+        ...(properties?.revenue !== undefined && {
           revenue: Number(properties.revenue),
-          currency: (typeof properties?.currency === "string" ? properties.currency : "USD").toLowerCase()
+          currency: (typeof properties?.currency === "string"
+            ? properties.currency
+            : "USD"
+          ).toLowerCase(),
+        }),
+        ...(properties?.points !== undefined && {
+          points: Number(properties.points),
         }),
-        ...(properties?.points !== undefined && { points: Number(properties.points) }),
       },
       event,
       type: "track",

package/src/lib/event/EventManager.ts

@@ -1,6 +1,7 @@
 import { Address, APIEvent } from "../../types";
 import { logger } from "../logger";
 import { IEventQueue } from "../queue";
+import { IStorageKeyManager } from "../storage";
 import { EventFactory } from "./EventFactory";
 import { IEventFactory, IEventManager } from "./type";
 
@@ -15,9 +16,9 @@ class EventManager implements IEventManager {
    *
    * @param eventQueue Event queue instance
    */
-  constructor(eventQueue: IEventQueue) {
+  constructor(eventQueue: IEventQueue, storageKeyManager: IStorageKeyManager) {
     this.eventQueue = eventQueue;
-    this.eventFactory = new EventFactory();
+    this.eventFactory = new EventFactory(storageKeyManager);
   }
 
   /**

package/src/lib/event/utils.ts

@@ -1,14 +1,13 @@
-import { LOCAL_ANONYMOUS_ID_KEY } from "../../constants";
 import { AnonymousID } from "../../types";
 import { generateNativeUUID } from "../../utils";
 import { local } from "../storage";
 
-const generateAnonymousId = (): AnonymousID => {
-  const storedAnonymousId = local.get(LOCAL_ANONYMOUS_ID_KEY);
+const generateAnonymousId = (key: string): AnonymousID => {
+  const storedAnonymousId = local.get(key);
   if (storedAnonymousId && typeof storedAnonymousId === "string")
     return storedAnonymousId as AnonymousID;
   const newAnonymousId = generateNativeUUID();
-  local.set(LOCAL_ANONYMOUS_ID_KEY, newAnonymousId);
+  local.set(key, newAnonymousId);
   return newAnonymousId;
 };
 

package/src/lib/storage/index.ts

@@ -1,2 +1,4 @@
+export { StorageKey } from "./key";
 export { default as local } from "./local";
 export { default as session } from "./session";
+export * from "./type";