@magicpixel/rn-mp-client-sdk 1.12.1 → 1.13.20

package/src/index.tsx

@@ -1,3 +1,6 @@
+// Polyfill for crypto.getRandomValues() required by ULID
+import 'react-native-get-random-values';
+
 import { MpDataLayerHelper } from './eedl/eedl';
 import type {
   AppCustomerInfo,
@@ -17,9 +20,22 @@ import { NetworkService } from './common/network-service';
 import { EventBus } from './common/event-bus';
 import { VisitIdProcessor } from './processors/visit-id.processor';
 import { GeoLocationProcessor } from './processors/geo-location.processor';
+import { DeviceInfoHelper } from './common/device-info-helper';
+import { DeepLinkHelper } from './common/deeplink-helper';
+import { StorageHelper } from './common/storage-helper';
 
 const DL_INIT_EVENT = 'page_load';
 
+// Maximum number of events to buffer before SDK is ready
+const MAX_BUFFERED_EVENTS = 500;
+
+// Type for buffered events
+interface BufferedEvent {
+  type: 'pageLoad' | 'event';
+  name?: string; // event name for recordEvent
+  data: any;
+}
+
 class MagicPixelImpl {
   private static dl: MpDataLayerHelper = new MpDataLayerHelper(
     'mpDlEvent',
@@ -31,26 +47,131 @@ class MagicPixelImpl {
   private static customerIdentifiers: MapLike = {};
 
   private static deepLinkUrl: string | undefined = undefined;
+  private static orgId: string | undefined = undefined;
 
   private static firstAppLaunch = true;
 
-  static async init(options: SdkInitOptions): Promise<void> {
+  // SDK readiness state and event buffer
+  private static isReady = false;
+  private static isInitializing = false;
+  private static eventBuffer: BufferedEvent[] = [];
+  private static onInitFailureCallback: ((error: Error) => void) | undefined;
+
+  /**
+   * Initialize the MagicPixel SDK
+   * This method is synchronous - it stores config immediately and runs async setup in background
+   * Events called before async setup completes are buffered and processed once ready
+   * @param options SDK initialization options
+   */
+  static init(options: SdkInitOptions): void {
+    // Guard against multiple init() calls
+    if (this.isReady) {
+      Logger.logDbg(
+        'MagicPixel SDK already initialized. Ignoring duplicate init() call.'
+      );
+      return;
+    }
+
+    if (this.isInitializing) {
+      Logger.logDbg(
+        'MagicPixel SDK initialization in progress. Ignoring duplicate init() call.'
+      );
+      return;
+    }
+
+    this.isInitializing = true;
+
+    // Sync setup - happens immediately
     Logger.setLogLevel(options.logLevel ?? 'none');
+    this.orgId = options.orgId;
+    this.onInitFailureCallback = options.onInitFailure;
+
+    Logger.logDbg('MagicPixel SDK init started');
+
+    // Async setup - runs in background, events are buffered until complete
+    this.initAsync(options).catch((err) => {
+      Logger.logError('MagicPixel SDK initialization failed:', err);
+      Reporter.reportError('sdk_init', err);
+
+      // Reset initializing flag so developer can retry if needed
+      this.isInitializing = false;
+
+      // Call failure callback if provided
+      if (this.onInitFailureCallback) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.onInitFailureCallback(error);
+      }
+    });
+  }
+
+  /**
+   * Shutdown the SDK and release all resources
+   * Call this when the app is closing or when you need to reinitialize the SDK
+   * After shutdown, you must call init() again to use the SDK
+   */
+  static shutdown(): void {
+    Logger.logDbg('MagicPixel SDK shutting down...');
+
+    // Clean up deeplink listener and callback
+    DeepLinkHelper.cleanup();
+
+    // Clear all EventBus listeners to prevent duplicates on reinit
+    EventBus.clearAll();
+
+    // Clear session-scoped data element values (in-memory store)
+    StorageHelper.clearSessionStore();
+
+    // Clear event buffer
+    this.eventBuffer = [];
+
+    // Reset state flags
+    this.isReady = false;
+    this.isInitializing = false;
+    this.onInitFailureCallback = undefined;
+
+    // Reset customer data
+    this.customerInfo = undefined as any;
+    this.customerIdentifiers = {};
+    this.deepLinkUrl = undefined;
+    this.firstAppLaunch = true;
+
+    // Shutdown EEDL
+    this.dl.shutdown();
+
+    Logger.logDbg('MagicPixel SDK shutdown complete');
+  }
+
+  /**
+   * Async initialization - runs in background
+   */
+  private static async initAsync(options: SdkInitOptions): Promise<void> {
     await NetworkService.refreshClientSdkJson(options);
 
     if (!DataStore.isDataStoreReady()) {
-      throw new Error('MagicPixel SDK is not ready. No tags will be processed');
+      throw new Error(
+        'MagicPixel SDK: DataStore not ready after config fetch. Initialization failed.'
+      );
     }
 
-    if (
-      options &&
-      options.device_type &&
-      options.device_type?.trim().length > 0
-    ) {
-      DataStore.overrideDeviceType(options.device_type);
-    }
+    // Initialize StorageHelper for data element storage duration
+    // This loads visitor-scoped values from AsyncStorage and clears expired ones (>30 days)
+    await StorageHelper.initialize();
+
+    // Auto-detect device info - always use detected values to prevent hardcoded values
+    const autoDetectedInfo = await DeviceInfoHelper.getAppInfo();
+    Logger.logDbg('Auto-detected device info:', autoDetectedInfo);
+
+    // Set device type from auto-detection (Expo/react-native-device-info)
+    // This is more reliable than dimension-based detection which fails on high-res phones
+    const detectedDeviceType = autoDetectedInfo.is_tablet ? 'tablet' : 'mobile';
+    DataStore.overrideDeviceType(detectedDeviceType);
+    Logger.logDbg('Device type set from auto-detection:', detectedDeviceType);
 
-    this.setAppVersion(options.app_version);
+    // Always use auto-detected app_version (ignore options.app_version)
+    this.setAppVersion(autoDetectedInfo.app_version);
+
+    // Set device info with auto-detected values (cannot be overridden)
+    await this.setDeviceInfo();
 
     await VisitIdProcessor.init(options?.orgId);
 
@@ -62,9 +183,39 @@ class MagicPixelImpl {
       Logger.logDbg('No facebook client id found. not setting');
     }
 
+    // Auto-detect deeplink if app was opened via deeplink (e.g., ad click)
+    // Supports: custom schemes (myapp://), universal links (https://), app links, HTTP links
+    const initialDeepLink = await DeepLinkHelper.initialize((url, linkType) => {
+      try {
+        Logger.logDbg(`Deeplink detected (${linkType}):`, url);
+
+        // Store deeplink URL - will be attached to next page_load event
+        this.setDeepLinkUrl(url);
+
+        // Fire deeplink opened event
+        // URL params will be parsed and attached to page_load event automatically
+        this.recordEvent('deeplink_opened', {
+          deep_link_url: url,
+          link_type: linkType,
+        });
+      } catch (err) {
+        Logger.logError('Error processing deeplink:', err);
+        Reporter.reportError('deeplink_callback', err);
+      }
+    });
+
+    if (initialDeepLink) {
+      Logger.logDbg('App opened with initial deeplink:', initialDeepLink);
+    }
+
     // Initialize EEDL with any global event listeners
     await this.dl.init({});
 
+    // Set event deduplication window if specified (default is 5000ms)
+    if (typeof options.eventDeduplicationWindowMs !== 'undefined') {
+      this.dl.setDeduplicationWindow(options.eventDeduplicationWindowMs);
+    }
+
     // Make geo location API call after initialization
     try {
       await GeoLocationProcessor.makeGeoLocationApiCall();
@@ -81,15 +232,14 @@ class MagicPixelImpl {
       Logger.logDbg('Tracking Event:: ', eventName, 'with id:: ', eventId);
 
       if (DataStore.shouldExecuteTMForEvent(eventName)) {
-        // if this is something the tag manager is interested in - fire tag manager
-        DataStore.enQueueTMFire(
+        // Call runTM directly - no queuing, EEDL manages sequential processing
+        await this.runTM(
           false,
           `custom_event_${eventName}`,
           eventName,
           eventId,
           eventDataModel
         );
-        await this.checkAndFireTM();
       }
     });
 
@@ -100,9 +250,38 @@ class MagicPixelImpl {
     }
 
     this.ready();
+
+    // Mark SDK as ready and flush any buffered events
+    this.isReady = true;
+    this.isInitializing = false;
+    Logger.logDbg('SDK is ready, flushing event buffer');
+    this.flushEventBuffer();
   }
 
   static recordEvent(eventName: string, payload: MapLike): void {
+    // Buffer event if SDK is not ready yet
+    if (!this.isReady) {
+      Logger.logDbg(`SDK not ready, buffering event: ${eventName}`);
+      // Evict oldest event if buffer at capacity
+      if (this.eventBuffer.length >= MAX_BUFFERED_EVENTS) {
+        const evicted = this.eventBuffer.shift();
+        Logger.logDbg(
+          `Event buffer at capacity (${MAX_BUFFERED_EVENTS}), evicted oldest:`,
+          evicted?.type === 'event' ? evicted.name : 'pageLoad'
+        );
+      }
+      this.eventBuffer.push({
+        type: 'event',
+        name: eventName,
+        data: payload,
+      });
+      return;
+    }
+
+    this.processRecordEvent(eventName, payload);
+  }
+
+  private static processRecordEvent(eventName: string, payload: MapLike): void {
     if (this.customerInfo) {
       const newPayload: MapLike = {
         ...payload,
@@ -123,42 +302,36 @@ class MagicPixelImpl {
     this.dl.ready();
   }
 
-  static getDebugId(): string {
-    return DataStore.getDebugId();
-  }
+  /**
+   * Flush buffered events after SDK is ready
+   * Events are processed in the order they were received
+   */
+  private static flushEventBuffer(): void {
+    if (this.eventBuffer.length === 0) {
+      Logger.logDbg('No buffered events to flush');
+      return;
+    }
 
-  private static async checkAndFireTM(): Promise<void> {
-    try {
-      if (!DataStore.isTagManagerProcessing()) {
-        const item = DataStore.deQueueTMFire();
-        if (item) {
-          Logger.logDbg(
-            'Executing TM For: ',
-            item.name,
-            ', Event:: ',
-            item.dcrName,
-            ', Event id:: ',
-            item.eventId,
-            'Payload:: ',
-            item.dcrPayload
-          );
-          await this.runTM(
-            item.sseOnly,
-            item.name,
-            item.dcrName,
-            item.eventId,
-            item.dcrPayload
-          );
-        }
-      } else {
-        Logger.logDbg(
-          'Tag Manager is processing or is not ready. This event will start after that'
-        );
+    Logger.logDbg(`Flushing ${this.eventBuffer.length} buffered event(s)`);
+
+    // Process all buffered events in order
+    while (this.eventBuffer.length > 0) {
+      const event = this.eventBuffer.shift()!;
+
+      if (event.type === 'pageLoad') {
+        Logger.logDbg(`Processing buffered page load: ${event.data.page_name}`);
+        this.processRecordPageLoad(event.data);
+      } else if (event.type === 'event') {
+        Logger.logDbg(`Processing buffered event: ${event.name}`);
+        this.processRecordEvent(event.name!, event.data);
       }
-    } catch (err) {
-      Logger.logError('Error check and process tm', err);
-      Reporter.reportError('m:checkAndFireTM', err);
     }
+
+    Logger.logDbg('Event buffer flushed');
+  }
+
+  static getDebugId(): string {
+    return DataStore.getDebugId();
   }
 
   private static async runTM(
@@ -178,9 +351,6 @@ class MagicPixelImpl {
         eventData
       );
 
-      // set tag manager in process status
-      DataStore.setTagManagerProcessing(true);
-
       // process all the data elements and cache them for this run
       await DataElementProcessor.processDataElements(
         DataStore.getSdkDataElements(),
@@ -200,7 +370,12 @@ class MagicPixelImpl {
           DataStore.setPrivacyCompliance(false);
         }
       } else {
-        Logger.logDbg('Set: PR Comp: ', false);
+        // No privacy manager configured - default to true (tracking allowed)
+        Logger.logDbg(
+          'Set: PR Comp: ',
+          true,
+          '(no privacy manager configured)'
+        );
         DataStore.setPrivacyCompliance(true);
       }
 
@@ -271,12 +446,12 @@ class MagicPixelImpl {
   ): void {
     // increment visit_depth if event name is page_load because that's the only way we can track page views in an app for now
     if (evtName === DL_INIT_EVENT) {
-      VisitIdProcessor.incrementVisitDepth().finally(() => {
-        this._fireTMPrivate(envName, envId, evtName, evtId);
-      });
-    } else {
-      this._fireTMPrivate(envName, envId, evtName, evtId);
+      // Synchronous increment - no race condition possible
+      VisitIdProcessor.incrementVisitDepth();
     }
+
+    // Continue immediately after sync increment
+    this._fireTMPrivate(envName, envId, evtName, evtId);
   }
 
   private static _fireTMPrivate(
@@ -297,15 +472,8 @@ class MagicPixelImpl {
         Reporter.reportError('l::postSST', err);
       });
     }
-
-    DataStore.setTagManagerProcessing(false);
-    Utils.sleep(250).then(async () => {
-      try {
-        await this.checkAndFireTM();
-      } catch (err) {
-        Reporter.reportError('i::runTM', err);
-      }
-    });
+    // Note: EEDL handles queue progression via its own .finally() block
+    // No need to call processNext() here - it would be redundant
   }
 
   static setCustomerInfo(customerInfo: AppCustomerInfo): void {
@@ -321,7 +489,46 @@ class MagicPixelImpl {
     this.deepLinkUrl = deepLinkUrl;
   }
 
-  static setDeviceInfo(deviceInfo: MpDeviceInfo): void {
+  /**
+   * Set device info with auto-detected values
+   * Standard fields (os_version, device_model_name, package_name) are always auto-detected
+   * Optional customFields parameter allows adding custom tracking fields only
+   * @param customFields Optional custom fields to add (cannot override standard fields)
+   */
+  static async setDeviceInfo(
+    customFields?: Record<string, any>
+  ): Promise<void> {
+    // Always auto-detect standard device info (cannot be overridden)
+    const autoDetectedInfo = await DeviceInfoHelper.getAppInfo();
+
+    // Standard fields are always auto-detected to prevent hardcoded values
+    const deviceInfo: MpDeviceInfo = {
+      os_version: autoDetectedInfo.os_version,
+      device_model_name: autoDetectedInfo.device_model_name,
+      package_name: autoDetectedInfo.package_name,
+    };
+
+    // Add any custom fields (if provided)
+    if (customFields) {
+      // Filter out attempts to override standard fields
+      const allowedCustomFields = { ...customFields };
+      delete allowedCustomFields.os_version;
+      delete allowedCustomFields.device_model_name;
+      delete allowedCustomFields.package_name;
+
+      Object.assign(deviceInfo, allowedCustomFields);
+
+      if (
+        Object.keys(allowedCustomFields).length !==
+        Object.keys(customFields).length
+      ) {
+        Logger.logDbg(
+          'Warning: Attempted to override standard device fields. Using auto-detected values instead.'
+        );
+      }
+    }
+
+    Logger.logDbg('Setting device info:', deviceInfo);
     DataStore.setDeviceInfo(deviceInfo);
   }
 
@@ -336,6 +543,35 @@ class MagicPixelImpl {
   }
 
   static recordPageLoad(pageLoadInfo: AppPageLoad): void {
+    // Buffer page load if SDK is not ready yet
+    if (!this.isReady) {
+      Logger.logDbg(
+        `SDK not ready, buffering page load: ${pageLoadInfo.page_name}`
+      );
+      // Evict oldest event if buffer at capacity
+      if (this.eventBuffer.length >= MAX_BUFFERED_EVENTS) {
+        const evicted = this.eventBuffer.shift();
+        Logger.logDbg(
+          `Event buffer at capacity (${MAX_BUFFERED_EVENTS}), evicted oldest:`,
+          evicted?.type === 'event' ? evicted.name : 'pageLoad'
+        );
+      }
+      this.eventBuffer.push({
+        type: 'pageLoad',
+        data: { ...pageLoadInfo }, // Clone to preserve original data
+      });
+      return;
+    }
+
+    this.processRecordPageLoad(pageLoadInfo);
+  }
+
+  private static processRecordPageLoad(pageLoadInfo: AppPageLoad): void {
+    // Retry visitor ID fetch if it failed during init (fire and forget)
+    VisitIdProcessor.retryVisitorIdIfNeeded().catch((err) => {
+      Logger.logError('Error retrying visitor ID fetch:', err);
+    });
+
     pageLoadInfo.is_entry = this.firstAppLaunch ? 1 : 0;
 
     // Use stored deepLinkUrl if it exists AND either:
@@ -345,6 +581,30 @@ class MagicPixelImpl {
       pageLoadInfo.deep_link_url = this.deepLinkUrl;
     }
 
+    // Set page_url for attribution framework
+    // Priority: deep_link_url (if present) > constructed URL (v_<orgId>://<screen_name>)
+    // Using deep_link_url allows urlp data elements to extract attribution params (gclid, fbclid, etc.)
+    if (pageLoadInfo.deep_link_url) {
+      pageLoadInfo.page_url = pageLoadInfo.deep_link_url;
+      Logger.logDbg(
+        'Setting page_url from deep_link_url:',
+        pageLoadInfo.page_url
+      );
+    } else if (this.orgId && pageLoadInfo.page_name) {
+      pageLoadInfo.page_url = `v_${this.orgId}://${pageLoadInfo.page_name}`;
+      Logger.logDbg(
+        'Setting page_url from orgId/page_name:',
+        pageLoadInfo.page_url
+      );
+    } else {
+      Logger.logDbg(
+        'Not setting page_url. No deep_link_url and orgId or page_name is missing. Org Id is: ',
+        this.orgId,
+        'page_name is: ',
+        pageLoadInfo.page_name
+      );
+    }
+
     const deviceInfo = DataStore.getDeviceInfo();
 
     if (this.customerInfo) {
@@ -352,7 +612,9 @@ class MagicPixelImpl {
         ...pageLoadInfo,
         ...this.customerInfo,
         ...(this.customerIdentifiers ?? {}),
-        ...Utils.parseQueryParamsToObject(pageLoadInfo?.deep_link_url),
+        page_params: Utils.parseQueryParamsToObject(
+          pageLoadInfo?.deep_link_url
+        ),
       };
 
       if (deviceInfo) {
@@ -364,7 +626,9 @@ class MagicPixelImpl {
       const newPayload: MapLike = {
         ...pageLoadInfo,
         ...(this.customerIdentifiers ?? {}),
-        ...Utils.parseQueryParamsToObject(pageLoadInfo?.deep_link_url),
+        page_params: Utils.parseQueryParamsToObject(
+          pageLoadInfo?.deep_link_url
+        ),
       };
 
       if (deviceInfo) {
@@ -461,3 +725,4 @@ class MagicPixelImpl {
 
 export const MagicPixelEventBus = EventBus;
 export const MagicPixel = MagicPixelImpl;
+export { DeepLinkHelper, DeepLinkType } from './common/deeplink-helper';

package/src/models/mp-client-sdk.ts

@@ -10,6 +10,14 @@ export interface ClientSdkDeItem {
   fn?: (deHelper: any, input: any) => any;
   isAsync?: boolean;
   fnTOut?: number;
+  stDur?: DeStorageDuration; // storage duration
+}
+
+export enum DeStorageDuration {
+  NONE = 'NONE',
+  EVENT = 'EVENT',
+  SESSION = 'SESSION',
+  VISITOR = 'VISITOR',
 }
 
 export enum ParamResourceEncodingType {

package/src/processors/data-element.processor.ts

@@ -4,13 +4,22 @@
  */
 import { Utils } from '../common/utils';
 import type { DeJsvHelper, MapLike } from '../common/app-types';
+import { DeStorageDuration } from '../models/mp-client-sdk';
 import type { ClientSdkDeItem } from '../models/mp-client-sdk';
 import { DataStore } from '../common/data-store';
 import { Logger } from '../common/logger';
+import { StorageHelper } from '../common/storage-helper';
 
 // Note: JSV (JavaScript functions) are not supported in React Native
 // This timeout function is kept for potential future use
 
+/**
+ * Check if a value is defined (not null, undefined, or empty string)
+ */
+function isDefined(value: any): boolean {
+  return value !== null && value !== undefined && value !== '';
+}
+
 const dElemProcessors: MapLike<
   (
     helper: DeJsvHelper,
@@ -86,7 +95,10 @@ const dElemProcessors: MapLike<
     _elem: ClientSdkDeItem,
     _eventData?: Record<string, any>
   ): any => {
-    return DataStore.getVisitInfo()?.visitDepth ?? 0;
+    // Visit depth should start at 1 (first page), not 0
+    // Return at least 1 to ensure first page view shows depth = 1
+    const depth = DataStore.getVisitInfo()?.visitDepth ?? 0;
+    return Math.max(1, depth);
   },
   /* Browser/Platform data elements */
   pg_browser: (
@@ -96,14 +108,13 @@ const dElemProcessors: MapLike<
   ): any => {
     return DataStore.getDeviceOs(); // Using device OS as browser equivalent
   },
-  /* User status data element - TODO: Implement getMpUserStatus in DataStore */
+  /* User status data element - 1 = new visitor (first visit), 0 = returning visitor */
   mp_new_vis: (
     _helper: DeJsvHelper,
     _elem: ClientSdkDeItem,
     _eventData?: Record<string, any>
   ): any => {
-    // TODO: Implement user status functionality
-    return '1'; // Default to new visitor
+    return DataStore.getMpUserStatus();
   },
   pg_random: (
     _helper: DeJsvHelper,
@@ -178,6 +189,55 @@ const dElemProcessors: MapLike<
     _elem.key = 'ev._eventName';
     return processMpDl(_helper, _elem, _eventData);
   },
+  pg_hash: (
+    _helper: DeJsvHelper,
+    _elem: ClientSdkDeItem,
+    _eventData?: Record<string, any>
+  ): any => {
+    return '';
+  },
+  pg_title: (
+    _helper: DeJsvHelper,
+    _elem: ClientSdkDeItem,
+    _eventData?: Record<string, any>
+  ): any => {
+    return '';
+  },
+  pg_params: (
+    _helper: DeJsvHelper,
+    _elem: ClientSdkDeItem,
+    _eventData?: Record<string, any>
+  ): any => {
+    return '';
+  },
+  pg_domain: (
+    _helper: DeJsvHelper,
+    _elem: ClientSdkDeItem,
+    _eventData?: Record<string, any>
+  ): any => {
+    return '';
+  },
+  pg_srch: (
+    _helper: DeJsvHelper,
+    _elem: ClientSdkDeItem,
+    _eventData?: Record<string, any>
+  ): any => {
+    return '';
+  },
+  pg_referrer: (
+    _helper: DeJsvHelper,
+    _elem: ClientSdkDeItem,
+    _eventData?: Record<string, any>
+  ): any => {
+    return '';
+  },
+  pg_url: (
+    _helper: DeJsvHelper,
+    _elem: ClientSdkDeItem,
+    _eventData?: Record<string, any>
+  ): any => {
+    return '';
+  },
   // Note: JSV (JavaScript functions) processor removed - not supported in React Native
 };
 
@@ -238,14 +298,32 @@ export async function processOneDataElement(
   try {
     if (dElemProcessors[deItem.typ]) {
       Logger.logDbg('Processing data element: ', deItem.nm);
-      const deValue = await dElemProcessors[deItem.typ](
+      let deValue = await dElemProcessors[deItem.typ](
         deHelper,
         deItem,
         eventData
       );
 
-      // TODO: Implement storage duration functionality for React Native
-      // For now, we'll just return the value without persistence
+      // Default storage duration to EVENT if not defined
+      if (!deItem.stDur) {
+        deItem.stDur = DeStorageDuration.EVENT;
+      }
+
+      // If data element has persistence enabled, store the value
+      StorageHelper.deStorageDurationSet(deItem.key, deValue, deItem.stDur);
+
+      // If value is not defined, try to retrieve from storage
+      // This allows values like gclid to persist across page loads
+      if (!isDefined(deValue)) {
+        const storedValue = StorageHelper.deStorageDurationGet(
+          deItem.key,
+          deItem.def,
+          deItem.stDur
+        );
+        if (isDefined(storedValue)) {
+          deValue = storedValue;
+        }
+      }
 
       return deValue;
     } else {