mimz-react-native-tracker 1.0.0

package/README.md

@@ -0,0 +1,246 @@
+# Mimz React Native Tracker SDK
+
+Analytics tracking SDK for React Native apps — the native equivalent of the Mimz web tracking script.
+
+Track **visitors, UTM parameters, conversions, contacts, and user engagement** in your native mobile app, exactly like the Mimz web script does on websites.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install mimz-react-native-tracker @react-native-async-storage/async-storage
+```
+
+For iOS, also run:
+```bash
+cd ios && npx pod-install
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Initialize the Tracker
+
+In your `App.js` or entry file:
+
+```javascript
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import MimzTracker from 'mimz-react-native-tracker';
+
+// Initialize when the app starts
+const initTracking = async () => {
+  await MimzTracker.init({
+    clientId: 'YOUR_MIMZ_CLIENT_ID',           // From your Mimz dashboard (userId)
+    backendUrl: 'https://your-mimz-backend.com', // Your Mimz backend URL
+    asyncStorage: AsyncStorage,
+    appName: 'MyApp',
+    appVersion: '1.0.0',
+  });
+};
+
+// Call it in your App component
+function App() {
+  useEffect(() => {
+    initTracking();
+  }, []);
+  
+  return (/* your app */);
+}
+```
+
+### 2. Track Deep Links (UTM Parameters)
+
+When your app receives a deep link (e.g., from an ad or email campaign), pass the URL to the tracker. The SDK will automatically extract UTMs like `utm_source`, `utm_medium`, `utm_campaign`, `gclid`, `fbclid`, etc.
+
+```javascript
+import { Linking } from 'react-native';
+
+useEffect(() => {
+  // Handle deep links
+  const handleDeepLink = (event) => {
+    MimzTracker.trackDeepLink(event.url, 'facebook'); // optional referrer
+  };
+
+  Linking.addEventListener('url', handleDeepLink);
+
+  // Handle initial URL (if app opened via deep link)
+  Linking.getInitialURL().then((url) => {
+    if (url) MimzTracker.trackDeepLink(url);
+  });
+}, []);
+```
+
+### 3. Track Screen Views
+
+```javascript
+// In your navigation listener or screen components:
+MimzTracker.trackScreenView('HomeScreen');
+MimzTracker.trackScreenView('ProductDetail', { productId: '123', category: 'Shoes' });
+```
+
+### 4. Track Custom Events
+
+```javascript
+MimzTracker.trackEvent('add_to_cart', { productId: '123', price: 29.99 });
+MimzTracker.trackEvent('button_click', { buttonId: 'signup_btn', text: 'Sign Up' });
+MimzTracker.trackEvent('search', { query: 'running shoes' });
+```
+
+### 5. Track Conversions
+
+```javascript
+MimzTracker.trackConversion({
+  productName: 'Premium Plan',
+  value: 49.99,
+  currency: 'USD',
+  conversionKey: 'premium_signup',
+  level: 'Purchase',
+});
+```
+
+### 6. Track Contacts (Form Submissions)
+
+```javascript
+// When a user submits a form in the app
+MimzTracker.trackContact({
+  email: 'user@example.com',
+  name: 'John Doe',
+  phone: '+1234567890',
+  source: 'Signup Form',
+});
+```
+
+### 7. Identify Users
+
+```javascript
+// When a user logs in or provides their info
+MimzTracker.identify({
+  email: 'user@example.com',
+  name: 'John',
+  phone: '+1234567890',
+});
+```
+
+### 8. Flush on App Background
+
+```javascript
+import { AppState } from 'react-native';
+
+useEffect(() => {
+  const subscription = AppState.addEventListener('change', (nextAppState) => {
+    if (nextAppState === 'background' || nextAppState === 'inactive') {
+      MimzTracker.flush(); // Send pending data immediately
+    }
+  });
+  return () => subscription.remove();
+}, []);
+```
+
+### 9. Reset on Logout
+
+```javascript
+const handleLogout = async () => {
+  await MimzTracker.reset(); // Clears all stored tracking data
+  // ... your logout logic
+};
+```
+
+---
+
+## 🔄 Web Script ↔ Native SDK Feature Mapping
+
+| Web Script Feature             | Native SDK Equivalent              | How It Works                          |
+| ------------------------------ | ---------------------------------- | ------------------------------------- |
+| `visitorId` (cookie)           | `MimzTracker.getVisitorId()`       | UUID stored in AsyncStorage           |
+| `visitId` (cookie)             | `MimzTracker.getVisitId()`         | Timestamp-based, new per session      |
+| UTM params (URL query string)  | `MimzTracker.trackDeepLink(url)`   | Parsed from deep link URLs            |
+| First-touch UTMs (cookie)      | Automatic                          | Stored on first deep link             |
+| Page view tracking             | `MimzTracker.trackScreenView()`    | Tracks screen names instead of URLs   |
+| Click/scroll tracking          | `MimzTracker.trackEvent()`         | Manual event tracking                 |
+| Form submission tracking       | `MimzTracker.trackContact()`       | Creates Contact + Conversion          |
+| Conversion tracking            | `MimzTracker.trackConversion()`    | Same payload as web                   |
+| Device info (userAgent)        | Automatic                          | Uses React Native Platform API        |
+| IP geolocation                 | Automatic                          | Uses ipify.org                        |
+| Traffic source detection       | Via deep link referrer              | Same classification logic as web      |
+| Session duration               | `MimzTracker.getSessionDuration()` | Calculated from init time             |
+| Session count                  | Automatic                          | Incremented per init()                |
+| `window.userId` (cookie)       | `config.clientId`                  | Passed during init()                  |
+| SPA navigation tracking        | `MimzTracker.trackScreenView()`    | Call on each screen navigation        |
+| `postUserDataToServer()`       | Automatic                          | Same `/api/visitors/add-visitors` API |
+| `beforeunload` flush           | `MimzTracker.flush()` + AppState   | Call on app background                |
+
+---
+
+## 📱 React Navigation Integration
+
+If you use React Navigation, you can automatically track screen views:
+
+```javascript
+import { NavigationContainer } from '@react-navigation/native';
+
+function App() {
+  const routeNameRef = useRef();
+  const navigationRef = useRef();
+
+  return (
+    <NavigationContainer
+      ref={navigationRef}
+      onReady={() => {
+        routeNameRef.current = navigationRef.current.getCurrentRoute().name;
+      }}
+      onStateChange={() => {
+        const currentRouteName = navigationRef.current.getCurrentRoute().name;
+        const previousRouteName = routeNameRef.current;
+
+        if (previousRouteName !== currentRouteName) {
+          MimzTracker.trackScreenView(currentRouteName);
+        }
+
+        routeNameRef.current = currentRouteName;
+      }}
+    >
+      {/* screens */}
+    </NavigationContainer>
+  );
+}
+```
+
+---
+
+## 🔑 API Reference
+
+| Method                    | Description                                           |
+| ------------------------- | ----------------------------------------------------- |
+| `init(config)`            | Initialize the SDK (must be called first)             |
+| `trackDeepLink(url)`      | Track a deep link and extract UTM params              |
+| `trackScreenView(name)`   | Track a screen view                                   |
+| `trackEvent(name, props)` | Track a custom event                                  |
+| `trackConversion(data)`   | Track a conversion                                    |
+| `trackContact(data)`      | Track a contact (form submission)                     |
+| `identify(data)`          | Set user identity (email, name, phone)                |
+| `setUtmParams(utms)`      | Manually set UTM parameters                           |
+| `getVisitorId()`          | Get the current visitor ID                            |
+| `getVisitId()`            | Get the current visit/session ID                      |
+| `getSessionDuration()`    | Get session duration in seconds                       |
+| `flush()`                 | Send pending data immediately                         |
+| `reset()`                 | Clear all stored data (for logout)                    |
+
+---
+
+## 📋 Backend API Compatibility
+
+This SDK sends data to the exact same backend endpoints as the web script:
+
+- `POST /api/visitors/add-visitors` — Visitor tracking
+- `POST /api/visitors/email-submission` — Contact + Conversion
+- `POST /api/conversion/add-conversion` — Standalone conversions
+
+The payload format matches the web script exactly, so your existing Mimz dashboard will display native app data seamlessly alongside web data.
+
+---
+
+## License
+
+MIT

package/bin/mimz-setup.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+
+/**
+ * Mimz React Native Tracker — Setup CLI
+ *
+ * Usage:
+ *   npx mimz-setup <clientId>
+ *   npx mimz-setup <clientId> <backendUrl>
+ *
+ * Examples:
+ *   npx mimz-setup 68b58625949a81fd08330b38
+ *   npx mimz-setup 68b58625949a81fd08330b38 https://mimz-backend.onrender.com
+ *
+ * This script will automatically inject tracking initialization code into your App.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── Parse CLI arguments ───────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+
+// Handle --help
+if (args.includes('--help') || args.includes('-h')) {
+  console.log('');
+  console.log('Usage:');
+  console.log('  npx mimz-setup <clientId>');
+  console.log('  npx mimz-setup <clientId> <backendUrl>');
+  console.log('');
+  console.log('Arguments:');
+  console.log('  clientId     Your Mimz Client ID (userId from the Mimz dashboard)');
+  console.log('  backendUrl   Your Mimz Backend URL (default: https://mimz-backend.onrender.com)');
+  console.log('');
+  console.log('Examples:');
+  console.log('  npx mimz-setup 68b58625949a81fd08330b38');
+  console.log('  npx mimz-setup 68b58625949a81fd08330b38 https://my-backend.com');
+  console.log('');
+  process.exit(0);
+}
+
+const clientId = args[0];
+let backendUrl = args[1] || 'https://mimz-backend.onrender.com';
+
+// Validate
+if (!clientId) {
+  console.log('');
+  console.log('╔══════════════════════════════════════════════╗');
+  console.log('║     🚀 Mimz React Native Tracker Setup      ║');
+  console.log('╚══════════════════════════════════════════════╝');
+  console.log('');
+  console.log('❌ Client ID is required!');
+  console.log('');
+  console.log('Usage:');
+  console.log('  npx mimz-setup <your-client-id>');
+  console.log('');
+  console.log('Example:');
+  console.log('  npx mimz-setup 68b58625949a81fd08330b38');
+  console.log('');
+  console.log('You can find your Client ID in the Mimz dashboard.');
+  console.log('');
+  process.exit(1);
+}
+
+// Normalize: remove trailing slash
+backendUrl = backendUrl.replace(/\/+$/, '');
+
+// ── The tracking code template ────────────────────────────────────────────────
+
+const getTrackingImports = () => {
+  return `import AsyncStorage from '@react-native-async-storage/async-storage';
+import MimzTracker from 'mimz-react-native-tracker';`;
+};
+
+const getTrackingInitCode = (cId, bUrl, appName) => {
+  return `
+  // ── Mimz Tracking ──────────────────────────────────────────────────────
+  useEffect(() => {
+    const initMimzTracking = async () => {
+      try {
+        await MimzTracker.init({
+          clientId: '${cId}',
+          backendUrl: '${bUrl}',
+          asyncStorage: AsyncStorage,
+          appName: '${appName}',
+          appVersion: '1.0.0',
+        });
+      } catch (error) {
+        console.warn('Mimz tracking init failed:', error.message);
+      }
+    };
+    initMimzTracking();
+
+    // Flush tracking data when app goes to background
+    const subscription = require('react-native').AppState.addEventListener('change', (state) => {
+      if (state === 'background' || state === 'inactive') {
+        MimzTracker.flush();
+      }
+    });
+    return () => subscription.remove();
+  }, []);
+  // ── End Mimz Tracking ──────────────────────────────────────────────────`;
+};
+
+// ── Main setup logic ──────────────────────────────────────────────────────────
+
+console.log('');
+console.log('╔══════════════════════════════════════════════╗');
+console.log('║     🚀 Mimz React Native Tracker Setup      ║');
+console.log('╚══════════════════════════════════════════════╝');
+console.log('');
+
+// Detect the app name from package.json
+let appName = 'MyApp';
+const pkgPath = path.join(process.cwd(), 'package.json');
+if (fs.existsSync(pkgPath)) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    appName = pkg.name || 'MyApp';
+  } catch (e) {
+    // ignore
+  }
+}
+
+console.log(`✅ Client ID:   ${clientId}`);
+console.log(`✅ Backend URL:  ${backendUrl}`);
+console.log(`✅ App Name:     ${appName}`);
+console.log('');
+
+// Find App.js
+const appJsPaths = [
+  path.join(process.cwd(), 'App.js'),
+  path.join(process.cwd(), 'App.jsx'),
+  path.join(process.cwd(), 'App.tsx'),
+  path.join(process.cwd(), 'src', 'App.js'),
+  path.join(process.cwd(), 'src', 'App.jsx'),
+  path.join(process.cwd(), 'src', 'App.tsx'),
+];
+
+let appJsPath = null;
+for (const p of appJsPaths) {
+  if (fs.existsSync(p)) {
+    appJsPath = p;
+    break;
+  }
+}
+
+if (!appJsPath) {
+  console.log('⚠️  Could not find App.js in your project.');
+  console.log('');
+  console.log('Add this manually to your App.js:');
+  console.log('──────────────────────────────────────────────');
+  console.log(getTrackingImports());
+  console.log('');
+  console.log('// Inside your App component, add this useEffect:');
+  console.log(getTrackingInitCode(clientId, backendUrl, appName));
+  console.log('');
+  process.exit(0);
+}
+
+console.log(`📄 Found: ${path.relative(process.cwd(), appJsPath)}`);
+
+// Read the file
+let content = fs.readFileSync(appJsPath, 'utf8');
+
+// Check if already set up
+if (content.includes('mimz-react-native-tracker') || content.includes('MimzTracker')) {
+  // Remove existing Mimz code to replace with new
+  content = content.replace(/import MimzTracker from ['"]mimz-react-native-tracker['"];?\r?\n?/g, '');
+  content = content.replace(/import AsyncStorage from ['"]@react-native-async-storage\/async-storage['"];?\r?\n?/g, '');
+  // Remove the tracking useEffect block
+  content = content.replace(/\s*\/\/ ── Mimz Tracking[\s\S]*?\/\/ ── End Mimz Tracking ──+/g, '');
+  console.log('🔄 Replacing existing Mimz tracking code...');
+}
+
+// ── Inject imports at the top ──────────────────────────────────────────────
+const trackingImports = getTrackingImports();
+
+// Find the last import line and add our imports after it
+const importRegex = /^(import\s+.+?;?\s*$)/gm;
+let lastImportIndex = -1;
+let match;
+while ((match = importRegex.exec(content)) !== null) {
+  lastImportIndex = match.index + match[0].length;
+}
+
+if (lastImportIndex > -1) {
+  content = content.slice(0, lastImportIndex) + '\n' + trackingImports + content.slice(lastImportIndex);
+} else {
+  // No imports found — try require() style
+  const requireRegex = /^(const\s+.+?=\s*require\(.+?\);?\s*$)/gm;
+  while ((match = requireRegex.exec(content)) !== null) {
+    lastImportIndex = match.index + match[0].length;
+  }
+  if (lastImportIndex > -1) {
+    content = content.slice(0, lastImportIndex) + '\n' + trackingImports + content.slice(lastImportIndex);
+  } else {
+    content = trackingImports + '\n' + content;
+  }
+}
+
+// ── Inject useEffect inside the App component ──────────────────────────────
+const trackingInit = getTrackingInitCode(clientId, backendUrl, appName);
+
+// Find the pattern: "return (" or "return(<" in the main component
+const returnRegex = /(\r?\n)([ \t]*)(return\s*\()/;
+const returnMatch = returnRegex.exec(content);
+
+if (returnMatch) {
+  const insertPos = returnMatch.index;
+  const indent = returnMatch[2] || '  ';
+  // Add the useEffect block before the return statement
+  const indentedCode = trackingInit
+    .split('\n')
+    .map((line) => (line.trim() ? indent + line.trimStart() : ''))
+    .join('\n');
+  content = content.slice(0, insertPos) + '\n' + indentedCode + '\n' + content.slice(insertPos);
+} else {
+  console.log('');
+  console.log('⚠️  Could not find the right place to inject tracking code.');
+  console.log('');
+  console.log('Add this useEffect inside your App component manually:');
+  console.log('──────────────────────────────────────────────');
+  console.log(trackingInit);
+  console.log('');
+  process.exit(0);
+}
+
+// ── Ensure useEffect is imported ───────────────────────────────────────────
+if (!content.includes('useEffect')) {
+  // Try to add useEffect to existing React import
+  const reactImportFixed = content.replace(
+    /import\s+React\s*,?\s*\{([^}]*)\}\s*from\s*['"]react['"]/,
+    (m, imports) => {
+      if (!imports.includes('useEffect')) {
+        return m.replace(imports, `${imports.trim()}, useEffect`);
+      }
+      return m;
+    }
+  );
+
+  if (reactImportFixed !== content) {
+    content = reactImportFixed;
+  } else if (!content.includes('useEffect')) {
+    // Try plain React import
+    content = content.replace(
+      /import\s+React\s+from\s*['"]react['"]/,
+      "import React, { useEffect } from 'react'"
+    );
+  }
+}
+
+// ── Write the updated file ─────────────────────────────────────────────────
+// Create a backup
+const backupPath = appJsPath + '.bak';
+fs.writeFileSync(backupPath, fs.readFileSync(appJsPath, 'utf8'));
+
+// Write the patched file
+fs.writeFileSync(appJsPath, content, 'utf8');
+
+console.log('');
+console.log('╔══════════════════════════════════════════════╗');
+console.log('║         ✅ Setup Complete!                   ║');
+console.log('╚══════════════════════════════════════════════╝');
+console.log('');
+console.log(`📄 Updated: ${path.relative(process.cwd(), appJsPath)}`);
+console.log(`📦 Backup:  ${path.relative(process.cwd(), backupPath)}`);
+console.log('');
+console.log('📦 Make sure you have installed:');
+console.log('   npm install @react-native-async-storage/async-storage');
+console.log('');
+console.log('   For iOS: cd ios && npx pod-install');
+console.log('');
+console.log('🚀 You\'re all set! Your app will now send tracking data to Mimz.');
+console.log('');

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "mimz-react-native-tracker",
+  "version": "1.0.0",
+  "description": "Mimz Analytics Tracking SDK for React Native apps. Track visitors, UTM parameters, conversions, contacts, and user engagement in native mobile apps.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "bin": {
+    "mimz-setup": "./bin/mimz-setup.js"
+  },
+  "scripts": {
+    "setup": "node bin/mimz-setup.js",
+    "test": "echo \"No tests yet\" && exit 0",
+    "lint": "eslint src/",
+    "postinstall": "echo \"\\n🚀 Run 'npx mimz-setup' to automatically configure tracking in your App.js\\n\""
+  },
+  "keywords": [
+    "mimz",
+    "analytics",
+    "tracking",
+    "react-native",
+    "utm",
+    "visitor",
+    "conversion",
+    "contact",
+    "mobile-analytics"
+  ],
+  "author": "Mimz",
+  "license": "MIT",
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.17.0",
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0"
+  },
+  "peerDependenciesMeta": {
+    "@react-native-async-storage/async-storage": {
+      "optional": false
+    }
+  },
+  "files": [
+    "src/",
+    "bin/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,131 @@
+/**
+ * TypeScript type definitions for mimz-react-native-tracker
+ */
+
+export interface MimzConfig {
+  /** Your Mimz client/account ID from the dashboard */
+  clientId: string;
+  /** The Mimz backend URL (e.g., https://mimz-backend.onrender.com) */
+  backendUrl: string;
+  /** The AsyncStorage module from @react-native-async-storage/async-storage */
+  asyncStorage: any;
+  /** Your app's name (for tracking context) */
+  appName?: string;
+  /** Your app's version */
+  appVersion?: string;
+}
+
+export interface ConversionData {
+  /** Product or conversion name */
+  productName?: string;
+  /** Conversion value */
+  value?: number;
+  /** Currency code (default: 'USD') */
+  currency?: string;
+  /** Unique conversion identifier */
+  conversionKey?: string;
+  /** Conversion level/type */
+  level?: string;
+}
+
+export interface ContactData {
+  /** Email address */
+  email?: string;
+  /** Full name */
+  name?: string;
+  /** First name */
+  firstName?: string;
+  /** Last name */
+  lastName?: string;
+  /** Phone number */
+  phone?: string;
+  /** Where the contact was captured (e.g., 'Signup Form') */
+  source?: string;
+}
+
+export interface UserData {
+  /** Email */
+  email?: string;
+  /** Name */
+  name?: string;
+  /** Phone */
+  phone?: string;
+}
+
+export interface UtmParams {
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_term?: string;
+  utm_content?: string;
+  utm_device?: string;
+  utm_devicemodel?: string;
+  fbclid?: string;
+  msclkid?: string;
+  gclid?: string;
+}
+
+/**
+ * Initialize the Mimz Tracker SDK
+ */
+export function init(config: MimzConfig): Promise<void>;
+
+/**
+ * Track a deep link URL — extracts and stores UTM parameters
+ */
+export function trackDeepLink(url: string, referrer?: string): Promise<void>;
+
+/**
+ * Track a screen view (replaces web page view tracking)
+ */
+export function trackScreenView(screenName: string, properties?: Record<string, any>): Promise<void>;
+
+/**
+ * Track a custom event
+ */
+export function trackEvent(eventName: string, properties?: Record<string, any>): Promise<void>;
+
+/**
+ * Track a conversion
+ */
+export function trackConversion(conversionData?: ConversionData): Promise<any>;
+
+/**
+ * Track a contact (form submission equivalent)
+ */
+export function trackContact(contactData?: ContactData): Promise<any>;
+
+/**
+ * Identify a user by setting their personal details
+ */
+export function identify(userData?: UserData): Promise<void>;
+
+/**
+ * Manually set UTM parameters
+ */
+export function setUtmParams(utms?: UtmParams): Promise<void>;
+
+/**
+ * Get the current visitor ID
+ */
+export function getVisitorId(): string | null;
+
+/**
+ * Get the current visit ID
+ */
+export function getVisitId(): number | null;
+
+/**
+ * Get current session duration in seconds
+ */
+export function getSessionDuration(): number;
+
+/**
+ * Flush: send current interactions to backend immediately
+ */
+export function flush(): Promise<void>;
+
+/**
+ * Reset the tracker (clear all stored data)
+ */
+export function reset(): Promise<void>;