mimz-react-native-tracker 1.0.0

package/src/tracker.js

@@ -0,0 +1,647 @@
+/**
+ * MimzTracker - Core tracking engine for React Native
+ *
+ * This is the React Native equivalent of the web tracking script (scriptUtils.js).
+ * It replaces all browser-dependent code (cookies, DOM, window, document)
+ * with React Native compatible APIs (AsyncStorage, fetch, Platform).
+ *
+ * Features:
+ *  - Visitor ID generation & persistence
+ *  - Visit ID (session) tracking
+ *  - UTM parameter tracking (from deep links)
+ *  - First-touch & last-touch attribution
+ *  - Traffic source detection
+ *  - Device info collection
+ *  - IP-based geolocation
+ *  - Conversion tracking
+ *  - Contact capture
+ *  - Screen view tracking (replaces page view tracking)
+ *  - User engagement tracking
+ *  - Session duration tracking
+ */
+
+const storage = require('./storage');
+const network = require('./network');
+const {
+  generateUniqueId,
+  parseUtmFromUrl,
+  getDeviceInfo,
+  getTrafficSource,
+  getUserIp,
+} = require('./utils');
+
+// ─── Internal State ──────────────────────────────────────────────────────────
+
+let isInitialized = false;
+let clientId = null; // The Mimz user/account ID (replaces window.userId)
+let visitorId = null;
+let visitId = null;
+let sessionStartTime = null;
+let sessionCount = 0;
+let currentScreen = null;
+let firstSeenTimestamp = null;
+let cachedIp = null;
+let cachedDeviceInfo = null;
+let currentUtmParams = {};
+let firstTouchUtmParams = {};
+let firstTrafficSource = null;
+let interactions = [];
+let appName = null;
+let appVersion = null;
+
+// ─── Configuration ───────────────────────────────────────────────────────────
+
+const API_ENDPOINTS = {
+  ADD_VISITORS: '/api/visitors/add-visitors',
+  ADD_VISITOR_DATA: '/api/visitors/visitor-data',
+  ADD_CONVERSION: '/api/conversion/add-conversion',
+  EMAIL_SUBMISSION: '/api/visitors/email-submission',
+};
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Initialize the Mimz Tracker SDK
+ *
+ * @param {object} config - Configuration object
+ * @param {string} config.clientId - Your Mimz client/account ID (REQUIRED - this is the userId from your Mimz dashboard)
+ * @param {string} config.backendUrl - The Mimz backend URL (REQUIRED - e.g., https://mimz-backend.onrender.com)
+ * @param {object} config.asyncStorage - The AsyncStorage module (REQUIRED - from @react-native-async-storage/async-storage)
+ * @param {string} [config.appName] - Your app's name (for tracking context)
+ * @param {string} [config.appVersion] - Your app's version (for tracking context)
+ *
+ * @example
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * import MimzTracker from 'mimz-react-native-tracker';
+ *
+ * await MimzTracker.init({
+ *   clientId: '68b58625949a81fd08330b38',
+ *   backendUrl: 'https://mimz-backend.onrender.com',
+ *   asyncStorage: AsyncStorage,
+ *   appName: 'MyApp',
+ *   appVersion: '1.0.0',
+ * });
+ */
+const init = async (config = {}) => {
+  if (isInitialized) {
+    console.warn('[MimzTracker] Already initialized. Call reset() first to re-initialize.');
+    return;
+  }
+
+  const { clientId: cId, backendUrl, asyncStorage, appName: an, appVersion: av } = config;
+
+  // Validate required fields
+  if (!cId) {
+    console.error('[MimzTracker] clientId is required. Get it from your Mimz dashboard.');
+    return;
+  }
+  if (!backendUrl) {
+    console.error('[MimzTracker] backendUrl is required (e.g., https://mimz-backend.onrender.com).');
+    return;
+  }
+  if (!asyncStorage) {
+    console.error('[MimzTracker] asyncStorage is required. Pass the AsyncStorage module.');
+    return;
+  }
+
+  // Initialize sub-modules
+  storage.init(asyncStorage);
+  network.init(backendUrl);
+
+  clientId = cId;
+  appName = an || null;
+  appVersion = av || null;
+  sessionStartTime = Date.now();
+
+  // ── Restore or create visitor ID ────────────────────────────────────────
+  const storedVisitorId = await storage.get('visitorId');
+  if (storedVisitorId) {
+    visitorId = storedVisitorId;
+  } else {
+    visitorId = generateUniqueId();
+    await storage.set('visitorId', visitorId);
+  }
+
+  // ── Create a new visit ID for this session ────────────────────────────
+  visitId = Date.now();
+  await storage.set('visitId', String(visitId));
+
+  // ── Session count ─────────────────────────────────────────────────────
+  const storedSessionCount = await storage.get('sessionCount');
+  sessionCount = storedSessionCount ? parseInt(storedSessionCount, 10) + 1 : 1;
+  await storage.set('sessionCount', String(sessionCount));
+
+  // ── First seen timestamp ──────────────────────────────────────────────
+  const storedFirstSeen = await storage.get('firstSeen');
+  if (storedFirstSeen) {
+    firstSeenTimestamp = storedFirstSeen;
+  } else {
+    firstSeenTimestamp = new Date().toISOString();
+    await storage.set('firstSeen', firstSeenTimestamp);
+  }
+
+  // ── Restore first-touch UTM ───────────────────────────────────────────
+  const storedFirstTouchUtm = await storage.getJSON('firstTouchUtm');
+  if (storedFirstTouchUtm) {
+    firstTouchUtmParams = storedFirstTouchUtm;
+  }
+
+  // ── Restore first traffic source ──────────────────────────────────────
+  const storedFirstTrafficSource = await storage.get('firstTrafficSource');
+  if (storedFirstTrafficSource) {
+    firstTrafficSource = storedFirstTrafficSource;
+  }
+
+  // ── Get device info (cached) ──────────────────────────────────────────
+  cachedDeviceInfo = getDeviceInfo();
+
+  // ── Get IP (non-blocking) ─────────────────────────────────────────────
+  getUserIp().then((ip) => {
+    cachedIp = ip;
+    storage.set('cachedIp', ip);
+  });
+
+  // Fallback: use cached IP from storage
+  const storedIp = await storage.get('cachedIp');
+  if (storedIp) {
+    cachedIp = storedIp;
+  }
+
+  isInitialized = true;
+
+  // ── Send initial visit data to the backend ────────────────────────────
+  const trackingData = await _buildTrackingPayload();
+  await _postVisitorData(trackingData);
+
+  console.log('[MimzTracker] ✅ Initialized successfully');
+  console.log(`[MimzTracker] visitorId: ${visitorId}`);
+  console.log(`[MimzTracker] visitId: ${visitId}`);
+  console.log(`[MimzTracker] sessionCount: ${sessionCount}`);
+};
+
+/**
+ * Track a deep link URL — extracts and stores UTM parameters
+ * Call this whenever your app receives a deep link / universal link
+ *
+ * @param {string} url - The deep link URL
+ * @param {string} [referrer] - Optional referrer URL (where the user came from)
+ *
+ * @example
+ * // In your deep link handler:
+ * MimzTracker.trackDeepLink('myapp://open?utm_source=facebook&utm_campaign=summer_sale');
+ */
+const trackDeepLink = async (url, referrer = null) => {
+  _ensureInitialized();
+
+  // Parse UTMs from the deep link
+  const utms = parseUtmFromUrl(url);
+  if (Object.keys(utms).length > 0) {
+    currentUtmParams = { ...currentUtmParams, ...utms };
+    await storage.setJSON('currentUtm', currentUtmParams);
+
+    // Store first-touch UTMs if not already set
+    if (Object.keys(firstTouchUtmParams).length === 0) {
+      firstTouchUtmParams = { ...utms };
+      await storage.setJSON('firstTouchUtm', firstTouchUtmParams);
+    }
+
+    console.log('[MimzTracker] 🔗 Deep link UTMs captured:', utms);
+  }
+
+  // Detect traffic source from the URL or referrer
+  if (referrer || url) {
+    // Check for paid indicators
+    let trafficSource = 'Direct';
+    if (utms.gclid || utms.msclkid || utms.fbclid) {
+      trafficSource = 'Paid';
+    } else {
+      const traffic = getTrafficSource(referrer || url);
+      trafficSource = traffic.trafficSource;
+    }
+
+    // Store first traffic source
+    if (!firstTrafficSource) {
+      firstTrafficSource = trafficSource;
+      await storage.set('firstTrafficSource', firstTrafficSource);
+    }
+  }
+
+  // Add to interactions
+  _addInteraction('deep_link', {
+    url,
+    referrer,
+    utms,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Re-post visitor data with updated UTMs
+  const trackingData = await _buildTrackingPayload();
+  trackingData.urlpt_url = url;
+  await _postVisitorData(trackingData);
+};
+
+/**
+ * Track a screen view (replaces web page view tracking)
+ *
+ * @param {string} screenName - The name/route of the current screen
+ * @param {object} [properties] - Additional properties to track
+ *
+ * @example
+ * MimzTracker.trackScreenView('HomeScreen');
+ * MimzTracker.trackScreenView('ProductDetail', { productId: '123', category: 'Shoes' });
+ */
+const trackScreenView = async (screenName, properties = {}) => {
+  _ensureInitialized();
+
+  const previousScreen = currentScreen;
+  currentScreen = screenName;
+
+  _addInteraction('screen_view', {
+    screenName,
+    previousScreen,
+    properties,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Update visitor data with current screen info
+  const trackingData = await _buildTrackingPayload();
+  trackingData.urlpt_url = `app://${screenName}`;
+  trackingData.urlpt_url_base = screenName;
+  await _postVisitorData(trackingData);
+
+  console.log(`[MimzTracker] 📱 Screen view: ${screenName}`);
+};
+
+/**
+ * Track a custom event (replaces click/scroll/form tracking)
+ *
+ * @param {string} eventName - The event name (e.g., 'button_click', 'add_to_cart')
+ * @param {object} [properties] - Event properties
+ *
+ * @example
+ * MimzTracker.trackEvent('add_to_cart', { productId: '123', price: 29.99 });
+ * MimzTracker.trackEvent('button_click', { buttonId: 'signup_btn', text: 'Sign Up' });
+ */
+const trackEvent = async (eventName, properties = {}) => {
+  _ensureInitialized();
+
+  _addInteraction(eventName, {
+    ...properties,
+    screen: currentScreen,
+    timestamp: new Date().toISOString(),
+  });
+
+  console.log(`[MimzTracker] 📊 Event: ${eventName}`, properties);
+};
+
+/**
+ * Track a conversion
+ *
+ * @param {object} conversionData - Conversion details
+ * @param {string} [conversionData.productName] - Product or conversion name
+ * @param {number} [conversionData.value] - Conversion value
+ * @param {string} [conversionData.currency] - Currency code (default: 'USD')
+ * @param {string} [conversionData.conversionKey] - Unique conversion identifier
+ * @param {string} [conversionData.level] - Conversion level/type
+ *
+ * @example
+ * MimzTracker.trackConversion({
+ *   productName: 'Premium Plan',
+ *   value: 49.99,
+ *   currency: 'USD',
+ *   conversionKey: 'premium_signup',
+ *   level: 'Purchase',
+ * });
+ */
+const trackConversion = async (conversionData = {}) => {
+  _ensureInitialized();
+
+  const payload = {
+    userId: clientId,
+    visitorId,
+    visitId,
+    product_name: conversionData.productName || '',
+    conversion_value: conversionData.value || 0,
+    currency: conversionData.currency || 'USD',
+    conversion_key: conversionData.conversionKey || `app_conversion_${Date.now()}`,
+    conversion_date: new Date().toISOString().split('T')[0],
+    level: conversionData.level || 'App Conversion',
+  };
+
+  const result = await network.post(API_ENDPOINTS.ADD_CONVERSION, payload);
+
+  _addInteraction('conversion', {
+    ...conversionData,
+    timestamp: new Date().toISOString(),
+  });
+
+  console.log('[MimzTracker] 💰 Conversion tracked:', conversionData.productName || 'unnamed');
+  return result;
+};
+
+/**
+ * Track a contact (form submission equivalent)
+ * Use this when a user submits their contact information in the app
+ *
+ * @param {object} contactData - Contact details
+ * @param {string} [contactData.email] - Email address
+ * @param {string} [contactData.name] - Full name
+ * @param {string} [contactData.firstName] - First name
+ * @param {string} [contactData.lastName] - Last name
+ * @param {string} [contactData.phone] - Phone number
+ * @param {string} [contactData.source] - Where the contact was captured
+ *
+ * @example
+ * MimzTracker.trackContact({
+ *   email: 'user@example.com',
+ *   name: 'John Doe',
+ *   phone: '+1234567890',
+ *   source: 'Signup Form',
+ * });
+ */
+const trackContact = async (contactData = {}) => {
+  _ensureInitialized();
+
+  // Store user data persistently
+  if (contactData.email) await storage.set('email', contactData.email);
+  if (contactData.name || contactData.firstName) {
+    await storage.set('fname', contactData.firstName || contactData.name);
+  }
+  if (contactData.phone) await storage.set('phone', contactData.phone);
+
+  // Send email submission to the backend (this creates both a Contact and Conversion)
+  const payload = {
+    email: contactData.email || '',
+    name: contactData.name || `${contactData.firstName || ''} ${contactData.lastName || ''}`.trim(),
+    clientId,
+    visitorId,
+    visitId: String(visitId),
+    campaignType: 'App Form',
+    campaignAction: contactData.source || 'app_contact',
+  };
+
+  const result = await network.post(API_ENDPOINTS.EMAIL_SUBMISSION, payload);
+
+  _addInteraction('contact_submitted', {
+    hasEmail: !!contactData.email,
+    hasPhone: !!contactData.phone,
+    hasName: !!(contactData.name || contactData.firstName),
+    source: contactData.source,
+    timestamp: new Date().toISOString(),
+  });
+
+  console.log('[MimzTracker] 👤 Contact tracked');
+  return result;
+};
+
+/**
+ * Identify a user by setting their personal details
+ * This data will be attached to all future tracking calls
+ *
+ * @param {object} userData - User details
+ * @param {string} [userData.email] - Email
+ * @param {string} [userData.name] - Name
+ * @param {string} [userData.phone] - Phone
+ *
+ * @example
+ * MimzTracker.identify({ email: 'user@example.com', name: 'John' });
+ */
+const identify = async (userData = {}) => {
+  _ensureInitialized();
+
+  if (userData.email) await storage.set('email', userData.email);
+  if (userData.name) await storage.set('fname', userData.name);
+  if (userData.phone) await storage.set('phone', userData.phone);
+
+  // Re-post visitor data with user info
+  const trackingData = await _buildTrackingPayload();
+  await _postVisitorData(trackingData);
+
+  console.log('[MimzTracker] 🆔 User identified');
+};
+
+/**
+ * Manually set UTM parameters (for cases where deep link isn't used)
+ *
+ * @param {object} utms - UTM parameters
+ *
+ * @example
+ * MimzTracker.setUtmParams({
+ *   utm_source: 'facebook',
+ *   utm_medium: 'cpc',
+ *   utm_campaign: 'summer_sale',
+ * });
+ */
+const setUtmParams = async (utms = {}) => {
+  _ensureInitialized();
+
+  currentUtmParams = { ...currentUtmParams, ...utms };
+  await storage.setJSON('currentUtm', currentUtmParams);
+
+  // Store first-touch if empty
+  if (Object.keys(firstTouchUtmParams).length === 0) {
+    firstTouchUtmParams = { ...utms };
+    await storage.setJSON('firstTouchUtm', firstTouchUtmParams);
+  }
+
+  console.log('[MimzTracker] 🏷️ UTM params set:', utms);
+};
+
+/**
+ * Get the current visitor ID
+ * @returns {string|null}
+ */
+const getVisitorId = () => visitorId;
+
+/**
+ * Get the current visit ID
+ * @returns {number|null}
+ */
+const getVisitId = () => visitId;
+
+/**
+ * Get current session duration in seconds
+ * @returns {number}
+ */
+const getSessionDuration = () => {
+  if (!sessionStartTime) return 0;
+  return Math.floor((Date.now() - sessionStartTime) / 1000);
+};
+
+/**
+ * Flush: send current interactions to backend immediately
+ * Call this on app background/close
+ */
+const flush = async () => {
+  if (!isInitialized) return;
+
+  const trackingData = await _buildTrackingPayload();
+  trackingData.interactions = [...interactions];
+  await _postVisitorData(trackingData);
+
+  console.log('[MimzTracker] 📤 Data flushed');
+};
+
+/**
+ * Reset the tracker (clear all stored data)
+ * Useful for logout flows
+ */
+const reset = async () => {
+  await storage.clearAll();
+
+  isInitialized = false;
+  clientId = null;
+  visitorId = null;
+  visitId = null;
+  sessionStartTime = null;
+  sessionCount = 0;
+  currentScreen = null;
+  firstSeenTimestamp = null;
+  cachedIp = null;
+  cachedDeviceInfo = null;
+  currentUtmParams = {};
+  firstTouchUtmParams = {};
+  firstTrafficSource = null;
+  interactions = [];
+
+  console.log('[MimzTracker] 🔄 Tracker reset');
+};
+
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+
+const _ensureInitialized = () => {
+  if (!isInitialized) {
+    throw new Error('[MimzTracker] Not initialized. Call MimzTracker.init() first.');
+  }
+};
+
+const _addInteraction = (type, data) => {
+  interactions.push({
+    type,
+    data,
+    screen: currentScreen,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Limit array size to prevent memory issues (same as web script)
+  if (interactions.length > 50) {
+    interactions = interactions.slice(-50);
+  }
+};
+
+const _buildTrackingPayload = async () => {
+  const email = await storage.get('email');
+  const fname = await storage.get('fname');
+  const phone = await storage.get('phone');
+
+  return {
+    // Identifiers
+    clientId,
+    visitorId,
+    visitId,
+    urlpt_ip: cachedIp || '0.0.0.0',
+    gaclientid: null, // Not available in native apps
+
+    // Current UTM parameters
+    utm_source: currentUtmParams.utm_source || null,
+    utm_medium: currentUtmParams.utm_medium || null,
+    utm_campaign: currentUtmParams.utm_campaign || null,
+    utm_term: currentUtmParams.utm_term || null,
+    utm_content: currentUtmParams.utm_content || null,
+
+    // First touch UTM parameters
+    first_utm_source: firstTouchUtmParams.utm_source || null,
+    first_utm_medium: firstTouchUtmParams.utm_medium || null,
+    first_utm_campaign: firstTouchUtmParams.utm_campaign || null,
+    first_utm_term: firstTouchUtmParams.utm_term || null,
+    first_utm_content: firstTouchUtmParams.utm_content || null,
+
+    // Click IDs
+    fbclid: currentUtmParams.fbclid || null,
+    msclkid: currentUtmParams.msclkid || null,
+    gclid: currentUtmParams.gclid || null,
+
+    // App info (replaces landing page / URL info)
+    urlpt_original_ref: null,
+    urlpt_landing_page: appName ? `app://${appName}` : null,
+    urlpt_landing_page_base: appName || null,
+
+    // Referrer info (set via deep link tracking)
+    urlpt_ref: null,
+    urlpt_ref_domain: null,
+
+    // Current screen info (replaces current page info)
+    urlpt_url: currentScreen ? `app://${currentScreen}` : `app://${appName || 'main'}`,
+    urlpt_url_base: currentScreen || appName || 'main',
+    domain: appName || 'native-app',
+
+    // Traffic sources
+    traffic_source: firstTrafficSource || 'Direct',
+    first_traffic_source: firstTrafficSource || 'Direct',
+    organic_source: null,
+    organic_source_str: null,
+
+    // User data
+    email: email || null,
+    fname: fname || null,
+    phone: phone || null,
+
+    // Device and technical info
+    user_agent: cachedDeviceInfo?.userAgent || 'MimzSDK/1.0',
+    deviceInfo: cachedDeviceInfo,
+    utm_device: cachedDeviceInfo?.deviceType || 'Mobile',
+    utm_devicemodel: cachedDeviceInfo?.deviceModel || 'Unknown',
+
+    // Facebook tracking (not available in native apps without FB SDK)
+    _fbc: null,
+    _fbp: null,
+
+    // Timestamps
+    firstSeen: firstSeenTimestamp,
+    lastSeen: new Date().toISOString(),
+
+    // Session info
+    sessionDuration: getSessionDuration(),
+    sessionCount,
+
+    // Interactions
+    interactions,
+
+    // App metadata
+    appName: appName,
+    appVersion: appVersion,
+    platform: 'react-native',
+    new: true,
+  };
+};
+
+const _postVisitorData = async (trackingData) => {
+  try {
+    const result = await network.post(API_ENDPOINTS.ADD_VISITORS, trackingData);
+    if (result) {
+      console.log('[MimzTracker] ✅ Visitor data sent');
+    }
+    return result;
+  } catch (error) {
+    console.warn('[MimzTracker] ⚠️ Failed to send visitor data:', error.message);
+    return null;
+  }
+};
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  init,
+  trackDeepLink,
+  trackScreenView,
+  trackEvent,
+  trackConversion,
+  trackContact,
+  identify,
+  setUtmParams,
+  getVisitorId,
+  getVisitId,
+  getSessionDuration,
+  flush,
+  reset,
+};